Microsoft Graph 接続 のスキーマの登録と更新

接続スキーマによって、様々な Microsoft Graph エクスペリエンスにおけるコンテンツの使用方法が決まります。 スキーマは、属性、ラベル、エイリアスと共に、接続に追加する予定のすべてのプロパティのフラットな一覧です。 接続に項目を追加する前に、スキーマを登録する必要があります。

スキーマの例

次の表は、work ticket システムコネクタに使用できるスキーマの例を示しています。

プロパティの属性

検索可能

プロパティが検索可能であれば、その値がフルテキストインデックスに追加されます。 検索を実行すると、検索可能なフィールドまたはその コンテンツのいずれかにヒットがある場合は、検索結果が返されます。

プロパティ (title) およびコンテンツ に対するヒットの結果を表示する 「デザイン」 の検索。

クエリ可能

プロパティがクエリ可能な場合は、ナレッジクエリ言語 (KQL) を使用して、クエリできます。 KQL は、1つ以上のフリーテキストのキーワード (単語または語句) またはプロパティの制限から構成されます。 クエリ自身で指定するか、プログラムでクエリに含めるかして、クエリにプロパティ名を含める必要があります。 ワイルドカード演算子 (*) を使用して、一致するプレフィックスを使用できます。

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

tagsプロパティに "design" を含むアイテムに結果を絞り込む "tags:design" の検索。

取得可能

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

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

絞り込み可能

プロパティが絞り込み可能な場合、管理者は、Microsoft 検索結果ページでカスタムフィルターとして設定できます。 refinable プロパティをsearchableすることはできません。

tagsで 結果を絞り込む、絞り込み可能なプロパティ。

完全一致が必要

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

たとえば、 ticketId プロパティはどちらもクエリ可能であり、完全一致を指定します。

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

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

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

たとえば、item プロパティが GUID 形式の文字列であるシナリオがあります。 このプロパティを項目クエリに対して正確に一致させる必要がある場合は、 isExactMatchRequired が trueであることを指定します。

title プロパティでは、完全一致が指定されていません。 何も指定されていない場合は、 isExactMatchRequired が falseされます。 title プロパティは、アイテム コンテンツの言語のトークン化ルールに基づいてトークン化されます。

• title:Contoso Titleクエリを実行すると、title プロパティにContosoまたはTitleを含む項目が返されます。

セマンティック ラベル

セマンティック ラベルは、Microsoft によって公開されているよく知られているタグで、スキーマのプロパティに対して追加することができます。 セマンティック ラベルを追加することで、さまざまな Microsoft 製品がその特性を理解し、より良い操作性を実現できるようになります。

セマンティック ラベルは、さまざまなコンテンツ ドメインのプロパティを既知のクラスのセットに割り当てる、ドメインに依存しないアプローチを提供します。 様々な異なるコンテンツ エクスペリエンスでアプリケーションを見つけ、次のようなタスクの自動サポートを提供します:

• さまざまな種類のエクスペリエンスでのデータ統合
• 一般的なナレッジ グラフの作成 (たとえば、Viva Topics)
• ユーザー エクスペリエンスの既定のテンプレート

ソース プロパティにセマンティック ラベルを割り当てるには、［プロパティ ラベルを割り当てる］ ページを使用します。 ラベルはセマンティックな意味を提供し、コネクタ データを Microsoft 365 エクスペリエンスに統合します。

たとえば、lastEditedByされた接続プロパティの意味は、 lastModifiedByされたMicrosoftラベルと同じ意味です。

できるだけ多くのラベルを追加しますが、プロパティに正確にマップされていることを確認します。 意味がない場合は、プロパティにラベルを追加しないでください。 不正確なマッピングで、エクスペリエンスが低下します。

ラベル タイトル が最も重要です。 接続が結果クラスター エクスペリエンスに参加できるように、このラベルにプロパティを割り当てているかどうか確認してください。 不正確なラベルのマッピングで、検索エクスペリエンスが低下します。 一部のラベルにプロパティが割り当てられていない場合でも問題ありません。

関連性

できるだけ沢山正確にマップされたラベルを適用することで、検索を通してコンテンツの検出が改善できます。 以下のラベルのうち、できるだけ多くのラベルを定義することを強くお勧めします。潜在的な検出可能性の影響について降順でリストされています:

• タイトル
• lastModifiedDateTime
• lastModifiedBy
• url
• fileName
• FileExtension

探索 (検索シナリオ) の場合は、次の点に注意して下さい:

• マッピングが正しいことを確認します。
• 大規模なコンテンツを含むラベルとしてプロパティを使用すると、検索待ち時間が長くなり、検索の結果が返されるまでの待ち時間が長くなる可能性があります。
• 特に、複数の接続に渡って検索ができるようにカスタムの垂直検索を構成するシナリオでは、可能な限り多くのラベルを予め指定すると、検索結果が改善されます。

ランク ヒント

ランク ヒントは、セマンティック ラベルにマップされず、検索可能として設定されているテキスト プロパティに適用できます。 これらは、検索管理ポータルで 既定 から非常に 高い 範囲で設定できます。 ヒントは、特定のクエリに最も関連する項目を返すために、各項目の他の属性と共に使用されます。

ランク ヒントを設定するには、次の手順に従います。

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

2. チューニングできる接続の一覧を表示するには、[詳細の表示>ランク ヒントの構成] を選択します。

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

既定の検索結果の種類

ラベルは、既定の検索結果の種類が生成される方法にも影響します。 タイトルとコンテンツのラベルを少なくとも追加すると、接続用に結果の種類が作成されます。

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

既定の結果タイプは、これらのラベルを定義して、適用しうる場合、より優れたエクスペリエンスをもたらします。

• タイトル
• url
• lastModifiedBy
• lastModifiedDateTime
• fileName
• FileExtension

最後に、ラベルを割り当てるときに、次のことを確認します。

• ラベルとして機能するように選択したプロパティは、取得可能にする必要があります。
• プロパティと割り当てられたラベルには、同じデータ型が必要です。
• 1つのラベルを1つのプロパティに正確に割り当てることができます。

エイリアス

エイリアスは、割り当てるプロパティのわかりやすい名前です。 これらは、絞り込み可能なプロパティ フィルターのクエリと選択で使用されます。

スキーマ更新機能

このセクションには、スキーマ API の更新機能に関する情報が含まれています。

プロパティを追加する

プロパティをスキーマに追加できます。これを行う場合、再割り込みは必要ありませんが、推奨されます。

プロパティを追加するときに、必要なすべての検索属性を含めることができます。

検索機能の追加/削除

特定の検索属性をプロパティに追加できますが、スキーマの変更として絞り込み条件検索属性を追加することはできません。 また、絞り込み可能な属性を検索可能な機能として使用することはできません。

検索機能を追加するには再入力が必要です。

エイリアスを追加/削除

エイリアスを追加または削除し、検索クエリに使用できます。

システムによって自動作成されたリファイナブル プロパティの元のエイリアスを削除できないことを検討してください。

セマンティック ラベルの追加/削除

セマンティック ラベルを追加すると、関連性やViva Topicsなどのエクスペリエンスに影響する可能性があります。

次の手順

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