> 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 形式を使用

より複雑なフィルター条件を記述する場合は、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>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 で指定したナレッジベース内で参照できる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つのレベルすべてが未設定の場合は制限なしとなり、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` 内の各条件は、`{"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**。上位レベルの設定は下位レベルの設定を上書きします。

## 各レベルの 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/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 のみを選択します
        }
      ]
    },
    
    // 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 を指定し、同じ AI アシスタントにリクエストごとに異なるナレッジ範囲を適用することもできます。バックエンドで現在のユーザーIDに応じて条件をリアルタイムに組み立てる連携シナリオに適しています。たとえば、次のようなシナリオがあります。

* **金融／証券業界**：会員ランクに応じて参照できるプランのドキュメントを決定します。一般会員と 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>ユーザーIDに基づいて権限を長期的に紐付けます</td></tr><tr><td>Web Chat の埋め込み</td><td>その埋め込みページで生成された会話</td><td>未登録の連絡先である訪問者の範囲を制限します</td></tr><tr><td>会話 API（<code>message.queryMetadata</code>）</td><td>そのリクエストのみ</td><td>バックエンドがリクエストごとに条件を組み立て、1つのアシスタントで複数の権限に対応します</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.