# 開始建構—使用 JSON 格式

## Query Metadata 控制項目說明 <a href="#querymetadata-kong-zhi-xiang-mu-shuo-ming" id="querymetadata-kong-zhi-xiang-mu-shuo-ming"></a>

<table><thead><tr><th width="108.66668701171875">項目類別</th><th width="140.66668701171875">Key名稱</th><th>說明</th><th>使用方法</th></tr></thead><tbody><tr><td>知識庫</td><td><code>knowledge_base</code></td><td>AI 助理產生對話時參考使用的知識庫</td><td>包裹在 knowledge_bases 命名的 <code>Array→[...]</code> 中，傳入知識庫 id 開放多個知識庫</td></tr><tr><td>知識庫檔案文件</td><td><code>Chatbot_file</code></td><td>knowledge_base 指定之知識庫中可參考的檔案文件</td><td>在 knowledge_base 中傳入的 <code>物件→{...}</code> 中定義</td></tr><tr><td>問答資料集</td><td><code>FAQ</code></td><td>knowledge_base 指定之知識庫中可參考的常見問答集</td><td>同上</td></tr><tr><td>知識庫檔案文件標籤</td><td><code>label</code></td><td>檔案文件中的標籤，若無指定 Chatbot_file 仍可指定 label，限制只能參考符合該標籤的文件，用於支援更細緻的文件權限劃分</td><td>使用 label_relations 命名的物件傳入，以 <code>"OR"/"AND"</code> 定義可適用的文件標籤條件，傳入conditions 命名的 <code>Array→[...]</code> 中定義</td></tr></tbody></table>

### 結構格式範例與說明

```json
"query_metadata": {
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e" // 檔案文件
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab" // FAQ
        ],
        "has_user_selected_all": "False" // 選擇所有知識庫
      },
  //  可傳入多個物件，一次設定多個資料庫下的可參考文件、FAQ 等
  //    {
  //      "knowledge_base_id": "Id2",
  //      "chatbot_file_ids": [
  //        "file_id1" // 檔案文件
  //      ],
  //      "faq_ids": [
  //        "faq_id1",
  //        "faq_id2" // FAQ
  //      ],
  //    },
    ],
 
  "label_relations": { // 標籤
      "operator": "OR",  // 設定適用標準 (同時符合全部或符合任一個即可)
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        // 可使用巢狀定義複雜條件
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" }, 
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
}
```

## 如何獲取各層級 ID？ <a href="#ru-he-huo-qu-ge-ceng-ji-id" id="ru-he-huo-qu-ge-ceng-ji-id"></a>

您可以進入左側選單的各層級內容中查看 ID 欄位 (以知識庫為例，可點選複製圖示直接複製所有 ID 內容)

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-ac377b11864763f6d3b96811593f2262b28eba95%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20101733.png?alt=media" alt=""><figcaption><p>取得各層級 ID 位置</p></figcaption></figure>

## 關鍵邏輯說明 <a href="#guan-jian-luo-ji-shuo-ming" id="guan-jian-luo-ji-shuo-ming"></a>

### 1. label\_relations 邏輯 <a href="#id-1labelrelations-luo-ji" id="id-1labelrelations-luo-ji"></a>

* `OR` 運算：符合任一標籤即可存取
* `AND` 運算：必須符合所有標籤才能存取
* 嵌套邏輯：支援多層、巢狀的權限組合

### 2. knowledge\_bases 設定 <a href="#id-2knowledgebases-she-ding" id="id-2knowledgebases-she-ding"></a>

* `has_user_selected_all = "True"`：可存取該知識庫的所有內容
* `has_user_selected_all = "False"`：僅能存取指定的文件跟 FAQ

## 聯絡人(Contact)設定 <a href="#lian-luo-ren-contact-she-ding" id="lian-luo-ren-contact-she-ding"></a>

您可以在編輯聯絡人的地方直接寫入 JSON 格式的 query\_metadata 設定：

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-948b74fac65e94e770db5ec15e7f148c07f242c2%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20163545.png?alt=media" alt=""><figcaption><p>聯絡人 JSON 編輯介面</p></figcaption></figure>

系統會自動驗證格式並套用權限設定。

## Web Chat 初始化設定 <a href="#webchat-chu-shi-hua-she-ding" id="webchat-chu-shi-hua-she-ding"></a>

{% hint style="info" %}
Web Chat 嵌入介紹請參考 [🔗Web Chat 初始化](https://docs.maiagent.ai/tech/api-integration/web-chat-sdk)
{% endhint %}

若想要在聯絡人前限制對話內容(如：提供 Web Chat 服務給未註冊聯絡人帳號的客戶時)，可以在嵌入時提供 Query Metadata，系統將預設啟動訊息(Message)層級的知識庫文件過濾機制

### 程式碼範例 <a href="#cheng-shi-ma-fan-li" id="cheng-shi-ma-fan-li"></a>

```javascript
<script>
  window.maiagentChatbotConfig = {
    // 設定 Web Chat 基礎參數
    webChatId: '從 Admin 嵌入視窗中獲得的 Web Chat ID',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    
    // 設定 Web Chat 知識庫文件搜索範圍
    queryMetadata: {
      labelRelations: { // 標籤
        operator: 'OR',
        conditions: [
          { labelId: '186a3012-44ac-4cd2-a132-a76bfda5bcae' },
          {
            operator: 'AND',
            conditions: [
              { labelId: '0267c405-cc26-4497-b17f-180aedf8b0eb' }, 
              { labelId: '60f81de6-a4b6-4d86-9781-5430783ef0b6' }
            ]
          }
        ]
      },
      knowledgeBases: [
        {
          knowledgeBaseId: '123e4567-e89b-12d3-a456-426614174000',
          chatbotFileIds: [
            '9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e' // 檔案文件
          ],
          faqIds: [
            'a1b2c3d4-e5f6-7890-abcd-1234567890ab' // FAQ
          ],
          hasUserSelectedAll: 'False' // 選擇所有知識庫
        }
      ]
    },
    
    // 設定 Contact
    contactId: '60f81de6-a4b6-4d86-9781-5430783ef0b6'
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>
```

### hasUserSelectedAll 參數說明

此參數為單一知識庫下的排除 / 使用少數項目之設定，在您開放的文件基礎下才會再套用標籤的過濾條件。

<table><thead><tr><th width="82">參數值</th><th>行為</th><th>適用場景</th></tr></thead><tbody><tr><td><code>"True"</code></td><td>系統選擇該知識庫中的所有內容，排除 <code>chatbotFileIds</code> 和 <code>faqIds</code> 中列出的項目</td><td>100 個文件中使用 98 個文件，2 個文件在參數中列出表示不使用</td></tr><tr><td><code>"False"</code></td><td>系統選擇 <code>chatbotFileIds</code> 和 <code>faqIds</code> 中明確列出的項目</td><td>100 個文件中只使用 2 個文件</td></tr></tbody></table>

### 程式碼範例

```js
// hasUserSelectedAll: True，列出想排除的文件 ID
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["不想使用的文件ID1", "不想使用的文件ID2"],
  "faqIds": ["不想使用的FAQ_ID1"],
  "hasUserSelectedAll": "True"
}

// hasUserSelectedAll: False，列出想使用的文件 ID
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["想使用的文件ID1", "想使用的文件ID2"],
  "faqIds": ["想使用的FAQ_ID1"],
  "hasUserSelectedAll": "False"
}
```

### queryMetadata 與 contactId 的優先順序

* **當不設定 queryMetadata 和 contactId 時**：系統會搜索全部知識庫範圍，不做任何排除
* **可以單獨設定 queryMetadata 或 contactId**
* **當兩者都設定時**：系統只會使用聯絡人(以 contactId 辨識)中 Query Metadata 的設定


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.