Microsoft 365 Copilot コネクタのスキーマを登録および管理する

このガイドでは、スキーマの定義に関するガイダンスと、Microsoft 365 Copilot コネクタのベスト プラクティスに従います。

接続スキーマは、Microsoft 365 Copilot エクスペリエンス全体でコンテンツを使用する方法を定義します。 スキーマは、接続に追加する予定のすべてのプロパティのフラット リストです。 各プロパティには、属性、ラベル、エイリアスが含まれます。 接続に項目を追加する前に、スキーマを登録する必要があります。

次の表は、作業チケット システム コネクタのスキーマの例を示しています。

スキーマ オブジェクトと API リファレンスについては、Copilot Connector API リファレンスのスキーマ セクションを参照してください。

スキーマ属性

このセクションでは、各スキーマ属性について説明し、それらを使用するためのベスト プラクティスについて説明します。

プロパティ

この属性は、 プロパティの名前を参照します。

ベスト プラクティス:

• 明確で一意の名前を使用 する – プロパティ名をわかりやすく区別します。 orgName、brOrgName、tpOrgNameなどのあいまいな名前は避けてください。 代わりに、 parentOrganizationName や departmentName などのわかりやすい名前を使用して、Copilot がプロパティを正しく解釈するのに役立ちます。
• 技術的または不可解な名前を避ける - dataBlob や ftxInvIsLead などの名前を、 incidentRootCause や qualifiedSalesLead などの意味のある代替手段に置き換えて、ユーザー クエリの読みやすさと関連性を向上させます。
• プロパティの説明を追加 する – 説明は、Copilot がユーザー クエリに対してプロパティを理解し、照合するのに役立ちます。

検索可能

プロパティが検索可能としてマークされると、その値がフルテキスト インデックスに追加されます。 これにより、Copilot は、ユーザーのクエリがプロパティまたはその コンテンツと一致したときに結果を返すことができます。

次の場合は、プロパティを検索可能としてマークします。

• これには、ユーザーが検索する可能性がある テキスト データ が含まれています。
• 検索クエリ (タイトル、説明、タグなど) に関連します。
• 検索ヒットとスニペットの生成に貢献する必要があります。

一般的な例:title、 description、 tags、 createdBy、 assignedTo。

ベスト プラクティス:

• 大きなバイナリ フィールドを検索可能としてマークしないでください。
• 絞り込み可能なフィールドを検索可能としてマークしないでください。これらの属性は相互に排他的です。
• 検索の関連性に不可欠な場合にのみ、プロパティを検索可能としてマークします。

design検索では、プロパティ (title) とコンテンツに対するヒットの結果が表示されます。

クエリ可能

ユーザーが特定の値に基づいて検索結果をフィルター処理する必要がある場合は、プロパティを クエリ可能 としてマークします。 たとえば、 ticketId、 teamName、 created などのプロパティはクエリ可能です。 ユーザーが tickets created by Williamなどのクエリを実行すると、Copilot は関連するチケットのみをフィルター処理して返すことができます。 ワイルドカード演算子 (*) を使用したプレフィックス 照合により、検索の柔軟性がさらに向上します。

次の場合は、プロパティをクエリ可能としてマークします。

• 検索結果をフィルター処理または絞り込むために使用されます。
• カテゴリ または構造化されたデータ (状態、優先度、割り当てられたユーザーなど) を表します。
• カスタム検索エクスペリエンスまたはファセット ナビゲーションをサポートする必要があります。

一般的な例:

status (たとえば、オープン、クローズ)、 assignedTo (userEmail や ID など)、 priority (高、中、低など)、 category、または type。

ベスト プラクティス:

• 大きなテキスト フィールド (説明など) をクエリ可能としてマークしないようにします。
• Queryable: trueとRetrievable: trueを組み合わせて、プロパティを使用して結果に表示できるようにします。
• UI でプロパティをフィルターとして表示する場合は、Refinable: trueを使用します。

この例では、 tags はクエリ可能としてマークされています。

tags プロパティでdesignを持つ項目に結果を絞り込むtags:design検索。

プロパティがクエリ可能な場合は、 KQL (キーワード クエリ言語) を使用してクエリを実行できます。 KQL では、フリー テキスト キーワードとプロパティ制限がサポートされています。 プロパティ名は、明示的またはプログラムによってクエリに含まれている必要があります。 ワイルドカード演算子 (*) とのプレフィックス 一致がサポートされています。

このプレフィックスに一致する結果を表示する search ba\* の検索。

取得可能

検索結果で値を返す必要がある場合は、プロパティを 取得可能 としてマークします。 表示テンプレートに表示されるプロパティ、またはクエリから返されるプロパティは、取得可能である必要があります。 選択的である - 取得可能なプロパティが多すぎるか大きすぎると、検索の待ち時間が長くなる可能性があります。

結果として表示された取得可能なプロパティ (titleとlastEditedBy) のセット。

次の場合、プロパティを取得可能としてマークします。

• 検索結果に表示する必要があります。
• コンテキスト情報 (タイトル、状態、割り当てられたユーザーなど) を提供します。

一般的な例:
title, summary, description, status, assignedTo, createdDateTime.

ベスト プラクティス:

• 機密性の高いフィールドまたは無関係なフィールドを取得可能としてマークしないようにします。
• 検索カード、Copilot プロンプト、またはカスタム UI に表示されるフィールドには、Retrievable: trueを使用します。

絞り込み可能

Microsoft Search エクスペリエンスでフィルターとして使用する場合は、プロパティを 絞り込み可能 としてマークします。 絞り込み可能なプロパティは、管理者が検索結果ページにカスタム フィルターとして表示するように構成できます。

プロパティがリファイン可能な場合:

• 検索結果を絞り込むために使用できます。
• UI に 絞り込み条件コントロール (ドロップダウンやチェックボックスなど) として表示されます。
• 検索クエリでの 集計 をサポートします。

次の場合は、プロパティをリファイン可能としてマークします。

• カテゴリデータまたは構造化データを表します。
• ユーザーがこれらの値で結果を フィルター処理またはグループ化 する必要があります。

一般的な例:
tags (例えば、金融、人事、エンジニアリング)、 status (例えば、オープン、クローズ、進行中)、 priority (例えば、高、中、低)、 category、 type。

ベスト プラクティス:

• 絞り込み可能と検索可能は相互に排他的です。プロパティは両方にすることはできません。
• 絞り込み可能なのは 、文字列型または数値型 のみです。
• リファイン可能なプロパティが多すぎると 、パフォーマンスに影響する可能性があります。

絞り込み可能なプロパティである tagsで結果を絞り込みます。

完全一致が必要

プロパティの isExactMatchRequired が true に設定されている場合、文字列全体の値にインデックスが作成されます。 この設定は、検索できないプロパティにのみ適用できます。

たとえば、 ticketId プロパティはどちらもクエリ可能であり、完全に一致する必要があります。

• ticketId:CTS-ce913b61クエリを実行すると、チケット ID CTS-ce913b61 の項目が返されます。
• ticketId:CTSクエリを実行しても、チケット ID CTS-ce913b61 の項目は返されません。

同様に、 tags プロパティも完全一致を使用します。

• tags:contosoクエリを実行すると、contoso というタグを持つ項目が返されます。
• tags:contosoクエリを実行しても、タグ contoso チケットを持つアイテムは返されません。

これは、プロパティに GUID などの値や、正確に一致する必要があるその他の識別子が含まれている場合に特に便利です。 このような場合は、 isExactMatchRequired を true に設定します。

isExactMatchRequiredが指定されていない場合、既定では false になります。 たとえば、 title プロパティでは完全一致は必要 ありません 。 これは、アイテム コンテンツの言語ルールに基づいてトークン化されます。

• title: Contoso Titleクエリを実行すると、タイトルにContosoまたはTitleを含む項目が返されます。

セマンティック ラベル

セマンティック ラベルは、スキーマ内のプロパティに割り当てることができる、Microsoft によって発行された既知のタグです。 Microsoft Graph APIを使用してカスタム Copilot コネクタを構築する場合は、セマンティック ラベルを適用することが不可欠です。 これらのラベルは、Microsoft 365 Copilotと Microsoft Search が各プロパティの意味と役割を理解し、検索、要約、および全体的なユーザー エクスペリエンスを向上させるのに役立ちます。

SDK を使用する場合は、Graph APIを使用するか、[プロパティ ラベルの割り当て] ページからセマンティック ラベルを割り当てることができます。 ラベルは意味的な意味を提供し、コネクタ データを Microsoft 365 エクスペリエンスにシームレスに統合できるようにします。

たとえば、さまざまなプロジェクト管理ツール (JIRA、Azure DevOps、Asana など) では、作業項目を作成したユーザーに異なる用語 ( owner、 ownedBy、 assignedToなど) が使用される場合があります。 プロパティが同様の目的を果たす場合は、 createdBy セマンティック ラベルを割り当てることができます。

ソース プロパティにセマンティック ラベルを割り当てるには、graph API を使用するか、sdk の使用中に [プロパティ ラベルの割り当て] ページを使用します。 ラベルは意味的な意味を提供し、コネクタ データを Microsoft 365 エクスペリエンスに統合できます。

ベスト プラクティス:

• 関連するラベルをできるだけ多く追加しますが、正確にマップされていることを確認します。
• 目的と一致しない場合は、ラベルをプロパティに割り当て ないでください 。マッピングが正しくないと、エクスペリエンスが低下します。

title ラベルが最も重要です。 このラベルにプロパティを割り当てると、接続が 結果のクラスター エクスペリエンスに参加できるようになります。 すべてのラベルを使用する必要はありませんが、割り当てるラベルが意味があり正確であることを確認してください。

関連性

正確にマップされたセマンティック ラベルを適用すると、検索によるコンテンツの検出可能性が向上します。 Microsoft では、検出への影響の降順で、次のラベルをできるだけ多く定義することをお勧めします。
title、 lastModifiedDateTime、 lastModifiedBy、 url、 fileName、 fileExtension。

ラベル マッピングが正確であることを確認します。 大きなコンテンツを含むプロパティにラベルを割り当てると、検索の待機時間が長くなり、結果が遅延する可能性があります。

ランク ヒント

ランク ヒントは、次のテキスト プロパティに適用できます。

• 検索可能
• セマンティック ラベルにマップされていません

ランク ヒントは、検索結果の特定のプロパティに優先順位を付けるのに役立ちます。 Microsoft 365 Search 管理ポータルでは、その重要度を 既定 から 非常に高い 値に設定できます。 これらのヒントは、最も関連性の高い結果を返すために、他の項目属性と共に使用されます。

ランク ヒントを構成するには:

1. Microsoft 365 管理ポータルの [ 検索とインテリジェンス ] タブに移動します。
2. [ カスタマイズ>Relevance チューニング] を選択します。

3. [ 関連性のチューニング] で、[ 詳細の表示>ランク ヒントの構成] を選択します。

4. 使用可能なソース プロパティの重要度の重みを変更します。

既定の検索結果の種類

セマンティック ラベルは、 既定の結果の種類 の生成方法にも影響します。 少なくとも、 title ラベルと content ラベルを割り当てると、接続の結果の種類が確実に作成されます。

titleと結果スニペットを含む既定の結果タイプ。

既定の結果エクスペリエンスを強化するには、該当する場合に次のラベルを定義します (影響の昇順に表示されます)。
title、 url、 lastModifiedBy、 lastModifiedDateTime、 fileName、 fileExtension。

ラベルを割り当てるための検証チェックリスト:

• ラベルに割り当てられたプロパティは、 取得可能としてマークする必要があります。
• プロパティの データ型 は、ラベルの予期される型と一致する必要があります。
• 各ラベルは、 1 つのプロパティにマップする必要があります。

エイリアス

エイリアス は、プロパティに割り当てられたフレンドリ名です。 これらは、使いやすさとクエリの柔軟性を向上させるために、クエリや絞り込み可能なプロパティ フィルターで使用されます。

実際の例を次に示します。

エイリアスのベスト プラクティス:

• 共通のシノニムまたはドメイン固有の用語にはエイリアスを使用します。
• 過度にジェネリックまたはあいまいなエイリアスは避けてください。
• エイリアスを 短く直感的に保ちます。

コンテンツ プロパティ

Microsoft Copilot コネクタ スキーマでは、content という既定のプロパティがサポートされています。 他のプロパティ (タイトル、タグなど) のようにスキーマで定義する必要はありません。 代わりに、データを取り込むときに アイテム ペイロードに直接含まれます 。

Microsoft Copilot コネクタ スキーマには、組み込みのcontent プロパティが含まれています。 他のプロパティ ( title や tagsなど) とは異なり、スキーマで定義する必要 はありません 。 代わりに、データ インジェスト中 にアイテム ペイロードに直接含まれます 。

content プロパティは次のとおりです。

• テキスト検索用に意味的にインデックスが付けられます。
• 検索結果で 動的スニペットを 生成するために使用されます。
• 要約とセマンティック理解のために Copilot で使用できます。

content プロパティを使用するためのベスト プラクティス:

• 非 構造化データ を content プロパティに追加して、Copilot がセマンティック検索と一致クエリを効果的に実行できるようにします。
• 非構造化コンテンツまたは自由形式コンテンツの場合は、content フィールドに summary、comment、rootCause、description などのプロパティを含めます。
• これらのプロパティは、完全な値を UI に表示する必要がある 場合にのみ 、個別の取得可能なフィールドとして保持します。
• 複数の プロパティ ( summary、 descriptionなど) を content フィールドに追加して、セマンティック理解を強化できます。

データの取り込み中に content プロパティを使用する方法のサンプル:

{ 
"@odata.type": "microsoft.graph.externalItem", 
"acl": [ 
{ 
"type": "everyone", 
"value": "everyone", 
"accessType": "grant" 
} 
], 

"properties": { 
"title": "Payment Gateway Error", 
"priority": "High", 
"assignee": "john.doe@contoso.com" 
}, 

"content": { 
"value": "Rootcause : Error in payment gateway : MoreDetails about the error.......", 
"type": "text" 
} 
}

宣言型エージェントとプロパティの説明

宣言型エージェント (DA) を使用している場合は、エージェントに提供される命令セットに、Copilot コネクタ スキーマのプロパティの説明を含める必要があります。 これは、DA が次を理解するのに役立ちます。

• 各プロパティの意味
• データを 参照して集計 する方法
• インデックス付きコンテンツを使用して ユーザー クエリに応答 する方法

すべてのプロパティに対して明確で整形式の説明を定義します。 適切な説明は次のとおりです。

• プロパティが表す内容
• 任意の代替名または用語
• 使用するタイミングと方法

スキーマ更新機能

このセクションでは、 スキーマ API の更新機能について説明します。

プロパティを追加する

新しいプロパティをスキーマに追加できます。 再取り付けは必要ありませんが、推奨されます。 プロパティを追加するときは、必要なすべての検索属性を含めます。

検索機能を追加または削除する

プロパティの検索属性を変更できます。 しかし：

• スキーマ更新の一部として絞り込み可能な属性を追加することはできません。
• プロパティを検索可能と絞り込み可能の両方にすることはできません。

検索機能を追加または削除するには、 再インストールが必要です。

エイリアスを追加または削除する

検索クエリで使用するエイリアスを追加または削除できます。 ただし、リファイン可能なプロパティに対 してシステムによって自動作成された エイリアス は削除できません。

セマンティック ラベルを追加または削除する

セマンティック ラベルを割り当てたり削除したりできます。 これらのラベルは、関連性やViva Topicsなどのエクスペリエンスに影響します。

次の手順

• 接続にアイテムを追加する
• Copilot コネクタ API リファレンスを確認する
• カスタムの型を検索する (externalItem)