> 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/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>FAQ データセット</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"],
        "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 レベルすべてが未設定の場合 = 制限なし、AI アシスタントに紐付けられたすべてのナレッジベースを検索できます                      |
| `{}`（空オブジェクト）                                                  | **制限なし（全選択）と見なされます**。また「設定済み」であるため次のレベルへの検索が停止します。「権限なし」を設定するには必ず `"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` 内の各条件は 2 つの形式のみ受け付けます：`{"label_id": "..."}`、またはネストされたグループ `{"operator": ..., "conditions": [...]}`。`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**。上位レベルの設定が下位レベルを上書きします。

## 各レベルの 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 のみアクセスできます
* JSON のブーリアン値（`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="/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 埋め込みと SDK](/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',
    
    // 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 のみ選択
        }
      ]
    },
    
    // コンタクトを設定
    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 をリクエストごとに指定することもできます。同じ AI アシスタントで異なるリクエストに対して異なるナレッジスコープを適用できます。バックエンドが現在のユーザーの身元に基づいてリアルタイムで条件を構成する統合シナリオに適しています。例えば：

* **金融・証券業**：会員ランクに応じて参照可能なプランドキュメントを決定します。一般会員と 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 を変更して送信するだけで、AI アシスタントを別途複製する必要はありません。

ネスト条件の記述方法は 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>バックエンドがリクエストごとに条件を構成し、同一アシスタントで複数の権限に対応します</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 を使用する必要があり、他のナレッジベースのラベルを流用することはできません。
* ラベルは**実際にファイル／FAQ に紐付けられている**必要があります。「ラベル管理」でラベル選択肢を作成しただけでコンテンツに紐付けていない場合、フィルタリングは効果を発揮しません。
* 質問文で直接ファイル名を指定して特定のファイルを取得する場合も、同様にラベル条件の制約を受けます。該当ファイルが条件に一致しない場合、AI アシスタントはナレッジベース内にそのファイルが見つからないと回答します。


---

# 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/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.