> 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.md). # ナレッジ管理権限（Query Metadata／クエリメタデータ）概要 ## Query Metadata とは？ AI チャットを導入する際、異なるユーザーには異なる範囲のナレッジが表示されるべきです。訪問者は公開情報のみ閲覧可能、VIP 会員にはプラン資料が追加で表示され、社内従業員のみが従業員ハンドブックを参照できます。 Query Metadata は**ナレッジ検索範囲を絞り込むための条件**です。特定の身分／特定の会話／特定のメッセージが検索時に、どの「ナレッジベース、ドキュメント、FAQ、ラベル条件に合致するコンテンツ」のみを参照できるかを指定します。これは認証メカニズムを置き換えるものではなく、身分が**条件付きで機能する**ようにするものです。 > **コンタクト／会話／メッセージはコンテナであり、Query Metadata はコンテナに付与され、実際に参照可能な範囲を決定する条件です。** {% hint style="info" %} 関連情報：[コンタクト（Contact）の紹介と連携](/tech/ja/authorization-integration/contacts.md)、[ロール（Role）とコンタクト（Contact）の違い](/tech/ja/authorization-integration/role-vs-contact.md) {% endhint %} ## 設定可能なレベル Query Metadata は 3 つのレベルで設定でき、それぞれ異なる連携方法に対応します。 | レベル | 適用範囲 | 設定方法 | | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------ | | **メッセージ（Message）** | 該当メッセージのみ | 会話 API の `message.queryMetadata`、社内 Q\&A インターフェース右側のナレッジ選択、Web Chat 埋め込みの `queryMetadata`（メッセージレベルで送信） | | **会話（Conversation）** | 該当会話のすべてのメッセージ | 会話作成 API で指定 | | **コンタクト（Contact）** | 該当ユーザーのすべての会話 | 管理画面のコンタクト編集（クエリビルダーまたは JSON）、コンタクト API | ### 解決順序 検索時に上から順に**最初に「設定されている」レベル**を取得します。 ``` Message > Conversation > Contact > すべて未設定（制限なし、AI アシスタントにマウントされたすべてのナレッジベースを検索可能） ``` * あるレベルが未設定（`null`）→ 次のレベルを参照 * 最初に設定されているレベルが**そのまま全体として適用**され、下位レベルとはマージされません——上位レベルの設定が下位レベルを完全に上書きします * 「空オブジェクト `{}`」も設定済みとみなされ（制限なしを意味）、下位への参照を終了します——「空集合 vs 未設定」の正確な意味については [JSON 形式ガイド](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md#empty-vs-unset)をご覧ください {% hint style="info" %} **社内メンバーの場合は？** メンバーがプラットフォーム内で閲覧できるリソースは[ロール権限](https://docs.maiagent.ai/org/role-permission)で制御されます（別のメカニズム）。メンバーが社内 Q\&A を使用する際はメッセージごとにナレッジ範囲を選択します。これは上表のメッセージレベルに該当します（[グラフィカルインターフェースガイド](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md)を参照）。 {% endhint %} ## 条件による範囲の絞り込み Query Metadata は 2 つの部分で構成され、段階的に検索可能な範囲を絞り込みます。 1. `knowledge_bases`：どの**ナレッジベース**を公開するか、および各ナレッジベース内でどの**ドキュメント／FAQ**を公開するか（全選択、一部を除外して全選択、一部のみ選択） 2. `label_relations`：公開済みのドキュメントの中から、さらに**ラベル**条件（AND／OR、ネスト可能）でフィルタリング ```mermaid flowchart TB KB["ナレッジベース"] Docs["ナレッジベース配下のドキュメント / FAQ"] Tags["ラベル条件で公開済みコンテンツをさらにフィルタリング"] Result["最終的に検索可能なコンテンツ"] KB --> Docs Docs --> Tags Tags --> Result classDef kbBox fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000 classDef docBox fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000 classDef tagBox fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000000 classDef resultBox fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000 class KB kbBox class Docs docBox class Tags tagBox class Result resultBox ```

ドキュメントフィルタリング条件の階層図

{% hint style="warning" %} Query Metadata は**ナレッジベース検索**のみを制約します：LLM プロンプトには入らず、AI は条件自体を読み取れません。AI に特定の値（商品 ID など）を「知らせたい」場合は [contextData](/tech/ja/api-integration/web-chat-sdk/web-chat-context-data.md) を使用してください。 {% endhint %} ## 2 つの構築方法 | 方法 | 適している場合 | ガイド | | ------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **クエリビルダー**（グラフィカル） | 管理画面でコンタクト権限を手動設定、社内 Q\&A でのメッセージごとの選択 | [構築を始める — クエリビルダーの使用](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md) | | **JSON 形式** | API 連携、Web Chat 埋め込み、複雑なネスト条件 | [構築を始める — JSON 形式の使用](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md) | ## 実際の活用シナリオ
身分渡される条件（query_metadata）応答結果
訪問者ナレッジベース：一般
ファイル：なし
ラベル：訪問者
FAQ：1、2		一般 ナレッジベース内の 訪問者 ラベルが付いたドキュメントおよび FAQ 1、FAQ 2 を取得
一般メンバーナレッジベース：一般
ファイル：A、B、C
ラベル：なし
FAQ：なし		一般 ナレッジベース内のドキュメント A、B、C とすべての FAQ を取得
カスタマーサポートナレッジベース：従業員
ファイル：なし
ラベル：カスタマーサポート
FAQ：なし		従業員 ナレッジベース内で カスタマーサポート ラベルが付いたドキュメントとすべての FAQ を取得
社内従業員ナレッジベース：従業員
ファイル：A、B
ラベル：なし
FAQ：なし		従業員 ナレッジベース内のドキュメント A、B とすべての FAQ を取得
管理者ナレッジベース：従業員、一般
ファイル：なし
ラベル：なし
FAQ：なし		従業員 と 一般 ナレッジベース内のすべてのドキュメントと FAQ を取得
同一の AI アシスタントで複数の身分にサービスを提供する場合、条件を変更するだけでアシスタントを複製する必要はありません。これが 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/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md?ask=&goal= ``` `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.