> 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/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md).

# 構築を始める—JSON 形式を使用する

より複雑なフィルター条件を記述する場合は、JSON 形式で各レベル（ナレッジベース、個別ドキュメントなど）の ID を直接指定できます。

## 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">キー名</th><th>説明</th><th>使用方法</th></tr></thead><tbody><tr><td>ナレッジベース</td><td><code>knowledge_base</code></td><td>Agent が会話を生成する際に参照するナレッジベースです</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 で指定したナレッジベース内で参照できる FAQ です</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"],
        "has_user_selected_all": false
      },
      {
        "knowledge_base_id": "223e4567-e89b-12d3-a456-426614174001",
        "has_user_selected_all": true
      }
    ],
    "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" }
          ]
        }
      ]
    }
  }
}
```

例の説明：

* `knowledge_bases` には複数のオブジェクトを渡せます。複数のナレッジベースで参照可能なドキュメントと FAQ を一度に設定できます。
* 1 つ目のナレッジベースの `has_user_selected_all: false` は、明示的に列挙したドキュメントと FAQ のみを許可します。2 つ目の `has_user_selected_all: true` は、そのナレッジベースのすべてのコンテンツを許可します。
* `label_relations.operator` は `"OR"`（いずれかのラベルに一致）または `"AND"`（すべてのラベルに同時に一致）で条件を組み合わせます。ネストによる複雑な条件の定義にも対応しています。
* 上記の例は、そのままコピーして使える有効な JSON です（JSON は `//` コメントに対応していません）。

## 空の集合と未設定の意味（重要） <a href="#empty-vs-unset" id="empty-vs-unset"></a>

「空の集合」と「未設定」は意味が異なります。設定を誤ると、すべてのアクセスが許可または拒否される可能性があります。

| 設定                                                              | 効果                                                                                                                |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 省略または `null`                                                    | 未設定 → 次のレベルを確認します。3 レベルとも未設定の場合は Agent のデフォルトラベルフィルターを適用します。Agent にも設定がない場合は制限なしとなり、Agent に紐付いたすべてのナレッジベースを検索できます |
| `{}`（空のオブジェクト）                                                  | **制限なし（すべて選択）とみなします**。「設定済み」のため下位レベルの確認を終了します。「権限なし」にする場合は、必ず `"knowledge_bases": []` を使用してください                   |
| `"knowledge_bases": []`（空の配列）                                   | すべてのナレッジベースを検索できなくなります。**「権限なし」にはこの設定を使用してください**                                                                  |
| `"label_relations": {"operator": "OR", "conditions": []}`（空の条件） | ラベルフィルターを行わず、選択したナレッジベースの全コンテンツを検索できます。権限なしを意味する設定**ではありません**                                                     |
| 値あり                                                             | 条件に従い、ナレッジベース → ドキュメント／FAQ → ラベルの順で範囲を絞り込みます                                                                      |

{% hint style="warning" %}
`label_relations` は `knowledge_bases` と一緒に指定する必要があります。`label_relations` のみを指定し（`knowledge_bases` を省略し）た場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同等です）。
{% endhint %}

### フィールド名は完全に一致させてください <a href="#exact-field-names" id="exact-field-names"></a>

* `conditions` 内の各条件は、`{"label_id": "..."}` またはネストしたグループ `{"operator": ..., "conditions": [...]}` の 2 形式のみを受け付けます。`label` や `labelid` など別のキー名を使うと、API は 400 を返し、誤ったフィールド名を示します。
* `knowledge_bases` 内のオブジェクトは、`knowledge_base_id`、`chatbot_file_ids`、`knowledge_base_file_ids`、`faq_ids`、`has_user_selected_all` の 5 フィールドのみを受け付けます。他のフィールドがある場合も 400 を返します。
* `query_metadata` の最上位には、独自の識別フィールド（例：`_user_id`）を追加できます。これらは無視され、検索範囲には影響しません。

{% hint style="info" %}
形式の誤りは API 境界で 400 として拒否されます（fail-closed）。想定より広い権限が通知なく適用されることはありません。設定後も一度実際にテストし、範囲が想定どおりであることを確認することをお勧めします。
{% endhint %}

### レベルの優先順位 <a href="#metadata-hierarchy" id="metadata-hierarchy"></a>

query\_metadata は Message / Conversation / Contact の 3 レベルに設定でき、上から順に最初に「設定されている」レベルを採用します。**Message > Conversation > Contact > Agent のデフォルトラベルフィルター**の順で、上位設定が下位設定を上書きします。Agent のデフォルトラベルフィルターは、3 レベルがすべて未設定の場合にのみ適用されます。詳細は[解決順序](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md#resolution-order)をご覧ください。

## 各レベルの 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://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%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 のみアクセスできます
* JSON の boolean（`true` / `false`）の使用をお勧めします。文字列 `"True"` / `"False"` もシステムが受け付けます（既存の連携との互換性のためです）

## 連絡先（Contact）の設定 <a href="#lian-luo-ren-contact-she-ding" id="lian-luo-ren-contact-she-ding"></a>

連絡先の編集画面で、JSON 形式の query\_metadata 設定を直接入力できます。

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%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 埋め込みと SDK](/tech/ja/serve/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',
    
    // 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 // 上記に明示したドキュメントと FAQ のみを選択します
        }
      ]
    },
    
    // 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 設定のみを使用します

## 会話 API（completions）でリクエストごとに指定する <a href="#completions-api" id="completions-api"></a>

連絡先や Web Chat 埋め込みの設定に加え、会話 API の呼び出しごとに Query Metadata を指定できます。同じ Agent に、リクエストごとに異なるナレッジの範囲を適用できます。バックエンドがその時点のユーザー区分に応じて条件を動的に組み立てる連携に適しています。例えば、次の用途があります。

* **金融／証券業**：会員ランクで参照可能なプラン資料を決めます。一般会員と VIP 顧客が同じ質問をしても、異なる範囲の回答を得られます
* **テクノロジー／電子機器製造業**：顧客の製品ラインに応じ、その製品ラインの仕様書と技術ドキュメントのみを参照するよう制限します
* **教育機関**：在学生、卒業生、一般訪問者の区分に応じて、入学案内や学校運営情報の公開範囲を変えます
* **医療／ヘルスケア業界**：診療科ごとに健康教育資料の範囲を限定し、異なる診療科のコンテンツが互いに干渉することを防ぎます

エンドポイント：`POST https://api.maiagent.ai/api/v1/chatbots/{chatbotId}/completions/`

{% hint style="warning" %}
`queryMetadata` はリクエスト本文の最上位ではなく、**`message` オブジェクト内**に指定してください。誤った位置に指定してもエラーにはなりませんが、条件は適用されず、フィルターが未設定の場合と同じ結果になります。
{% endhint %}

### 完全な例 <a href="#completions-full-example" id="completions-full-example"></a>

{% code title="completions + queryMetadata" overflow="wrap" %}

```bash
curl --location 'https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Api-Key ご自身のAPIキー' \
--data '{
    "conversation": null,
    "message": {
        "content": "私の会員ランクで利用できる優待プランは何ですか？",
        "queryMetadata": {
            "knowledgeBases": [
                {
                    "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000"
                }
            ],
            "labelRelations": {
                "operator": "AND",
                "conditions": [
                    { "labelId": "186a3012-44ac-4cd2-a132-a76bfda5bcae" }
                ]
            }
        }
    },
    "isStreaming": false
}'
```

{% endcode %}

上の例では、ナレッジベース `123e4567…` 内で、ラベル `186a3012…`（例：「一般会員」）にも一致するドキュメントと FAQ のみを参照します。VIP 顧客の場合は、バックエンドが対応するラベル ID に切り替えて渡すだけでよく、Agent を別途複製する必要はありません。

ネストした条件の記述方法は Web Chat と同じです。前のセクションの `labelRelations` 構造をそのまま使用できます。

```json
"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" }
            ]
        }
    ]
}
```

### 3 つの設定場所の違い <a href="#three-entry-points" id="three-entry-points"></a>

<table><thead><tr><th width="150">設定場所</th><th>適用範囲</th><th>用途</th></tr></thead><tbody><tr><td>連絡先（Contact）</td><td>その連絡先のすべての会話</td><td>ユーザー区分に応じて権限を長期的に紐付けます</td></tr><tr><td>Web Chat 埋め込み</td><td>その埋め込みページで生成された会話</td><td>連絡先が未登録の訪問者の範囲を制限します</td></tr><tr><td>会話 API（<code>message.queryMetadata</code>）</td><td>そのリクエストのみ</td><td>バックエンドでリクエストごとに条件を組み立て、同じ Agent で複数の権限に対応します</td></tr></tbody></table>

### フィールドの命名：camelCase と snake\_case の両方を使用できます <a href="#field-naming" id="field-naming"></a>

API は命名形式を自動変換するため、次の 2 つの記述は同等です。

* camelCase：`queryMetadata`、`knowledgeBases`、`knowledgeBaseId`、`labelRelations`、`labelId`、`hasUserSelectedAll`
* snake\_case：`query_metadata`、`knowledge_bases`、`knowledge_base_id`、`label_relations`、`label_id`、`has_user_selected_all`

保守時の混乱を避けるため、リクエスト全体で同じ命名形式を使用することをお勧めします。

### hasUserSelectedAll を省略した場合のデフォルト値 <a href="#default-has-user-selected-all" id="default-has-user-selected-all"></a>

`hasUserSelectedAll` を省略すると、デフォルトは `true` になります。つまり、**そのナレッジベースのすべてのコンテンツ**を対象とし、さらにラベル条件でフィルタリングします。

そのため、「ラベルでナレッジベース全体を制限する」だけの場合、`knowledgeBases` には `knowledgeBaseId` のみを指定すれば十分です。

```json
"knowledgeBases": [
    { "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000" }
]
```

### ラベルフィルターの適用範囲 <a href="#label-filter-scope" id="label-filter-scope"></a>

* ラベル条件は、ナレッジベースのドキュメントと FAQ の**両方**に適用されます。
* ユーザーがその会話で**直接アップロードした添付ファイルは、ラベル条件の制限を受けず**、引き続き参照できます。ラベルが制限するのはナレッジベース内のコンテンツのみです。
* ラベルは**ナレッジベースごとに独立して作成されます**。`label_id` にはそのナレッジベース自身のラベル ID を使用し、他のナレッジベースのラベルを流用しないでください。
* `label_relations` は、ナレッジベースごとの設定ではなく、**リクエスト全体で共用する 1 組の条件**です。プラットフォームは同じ条件を `knowledge_bases` に列挙した各ナレッジベースに適用します。ラベルは自身のナレッジベースのドキュメントにのみ付与されるため、実際の動作は次のとおりです。
  * 複数のナレッジベースのラベル ID を `OR` に混在させることは可能です。各ナレッジベースは自分に属するラベルにのみ一致します。他のラベルに一致するドキュメントはそのナレッジベースにはありません。
  * 異なるナレッジベースのラベル ID を `AND` に混在させると、**どのナレッジベースでも結果を取得できません**。2 つのナレッジベースのラベルを同時に持つドキュメントがないためです。ナレッジベースごとに異なる条件を適用する場合は、リクエストを分けるか、`chatbot_file_ids` でドキュメントを指定してください。
  * 存在しないラベル ID や、これらのナレッジベースに属さないラベル ID はエラーになりません。一致するドキュメントがないものとして扱われます。
* ラベルは**実際にドキュメント／FAQ に付与する**必要があります。「ラベル管理」でラベルの選択肢を作成するだけでコンテンツに付与しなければ、フィルターは効果を発揮しません。
* 質問でファイル名を直接指定して特定のファイルを要求する場合も、ラベル条件の制限を受けます。そのファイルが条件に一致しなければ、Agent はナレッジベース内にそのファイルが見つからないと回答します。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.