> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/maiagent-tech-ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md).

# 構築を始める—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>Q&#x26;A データセット</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="/files/jycyBSaqwtTW5bamgJju" 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="/files/vUc9z9Ay8vutVaFK1Wyi" 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 初期化](/tech/maiagent-tech-ja/api-integration/web-chat-sdk.md) をご参照ください
{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.