Microsoft Graph 接続でアイテムを作成、更新、削除する
Microsoft Graph コネクタは、外部データを Microsoft Graph に取り込む直感的な方法を提供します。 アプリケーションが Microsoft Search Serviceに追加する項目は、Microsoft Graph の externalItem リソースによって表されます。
接続を作成 した後は、コンテンツを追加できます。 データ ソースの各アイテムは、Microsoft Graph で固有のアイテム ID を使用してexternalItem として表される必要があります。 この ID は、Microsoft Graph のアイテムの作成、更新、削除に使用されます。 データ ソースの主キーをアイテム ID として使用することも、1 つまたはそれ以上のフィールドから導くこともできます。
主要なコンポーネント
externalItem には、アクセス制御リスト、プロパティ、コンテンツの3つの主要な構成要素があります。
アクセス制御リスト
アクセス制御リスト (ACL) は、特定のロールが Microsoft エクスペリエンスのアイテムを表示するためのアクセスを許可または拒否するかどうかを指定するために使用されます。 ACL は、Microsoft Entraユーザーまたはグループを表すアクセス制御エントリの配列です。 3 つ目のアクセス制御エントリ タイプ Everyone は、テナント内のすべてのユーザーを表します。
アクセス制御リスト例。
accessType 値 deny は、grant よりも優先されます。 たとえば、上に表示されているアイテムの Everyone へのアクセスが許可されて、特定のユーザーへのアクセスが拒否されている場合、このユーザーの有効なアクセス許可は deny です。
データ ソースに、アイテムのアクセス許可を設定するために使用される非 Azure AD グループ (ヘルプデスク システム内のチームなど) がある場合は、グループ同期 API を使用して allow または deny のアクセス許可を複製することで、Microsoft Graph で外部グループを作成できます。 外部グループのメンバーシップを個々のアイテムの ACL に直接拡張することは避けてください。各グループ メンバーシップは大量のアイテム更新につながる可能性があるためです。
外部グループには、別のグループ、Microsoft Entra ユーザー、およびMicrosoft Entra グループが含まれます。 Azure AD 以外のユーザーがいる場合は、ACL 内のMicrosoft Entra ユーザーに翻訳する必要があります。
プロパティ
[プロパティ] コンポーネントは、Microsoft Graph の操作性に役立つアイテムのメタデータを追加するために使用されます。 アイテムを追加する前に、接続のスキーマを登録し、データ型をサポートされているデータ型に変換する必要があります。
プロパティ コンポーネント例。
コンテンツ
コンテンツ コンポーネントは、フルテキスト インデックスを作成する必要がある項目の大部分を追加します。 たとえばチケットの説明、ファイル本文から解析されたテキスト、Wiki ページ本文などがあります。
コンテンツは、Microsoftエクスペリエンスを通して 関連性に影響する主要なフィールドの1つです。 コンテンツ タイプ text および html はサポートされています。 データソースにバイナリファイル、ビデオ、または画像のような、その他のコンテンツ タイプを含む場合は、そのファイルを解析してテキスト情報に展開してから、Microsoft Graph に追加します。 たとえば、光学式文字認識では、画像から検索可能なテキストを抽出できます。
重要
コンプライアンス ソリューションでは、コンテンツ タイプの text のみがサポートされます。
enabledContentExperience プロパティを compliance に設定してコンプライアンスの接続を有効にする場合は、プレーン テキスト形式でコンテンツを取り込み、コンテンツ タイプを text に設定する必要があります。
コンテンツ コンポーネントの例。
コンテンツを検索結果テンプレートに直接追加することはできませんが、生成された結果スニペットを使用できます。これは、コンテンツ内の関連セクションの動的に生成されたプレビューです。
検索結果テンプレート。
データソース内のコンテンツが変更された場合は、接続アイテムと同期する必要があります。 アイテム全体または 1 つ以上のコンポーネントを更新できます。 Microsoft Graph にコンテンツを追加した後は、 検索の垂直方向 と 結果の種類 を設定した後、または Microsoft Graph Search API を使用して、Microsoft Search エクスペリエンスを使用してコンテンツを検索できます。
アクティビティ
アクティビティ コンポーネントは、アイテムに 対してアクティビティ を送信する一時的なプロパティです。 このプロパティ にのみ書き 込むことができます。
アクティビティは、アクター (アクティビティを実行したユーザー)、時刻 (アクティビティが実行されたとき)、アクティビティの種類 (実行されたアクティビティの種類) で構成されます。 現在サポートされているアクティビティの種類は、externalActivity の type プロパティの Description セクションにあります。
アイテムに対するアクティビティを送信すると、Microsoft 365 全体でインテリジェントなレコメンデーション エクスペリエンスが実現します。 エンド ユーザーは、送信されたアクティビティに基づいて、ユーザーに合わせたコンテンツを受け取ることができます。
アイテムの追加
インデックスにアイテムを追加するには、externalItem を作成します。 アイテムの作成時に、URL で固有の識別子を割り当てます。
たとえば、ヘルプデスク チケットのインデックスを作成するために、アプリケーションではチケット番号を使用できます。 チケットにチケット番号 SR00145 がある場合、要求は次のようになります:
PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
"properties": {
"title": "WiFi outage in Conference Room A",
"priority": 1,
"assignee": "meganb@contoso.com"
}
注:
Microsoft Search UI でインデックス付きアイテムが見つかる前に、管理者は対応する接続の検索結果ページをカスタマイズ する必要があります。
アイテムにアクティビティを追加する
アイテムにアクティビティを追加するには、URL 内のそのアイテムに対して同じ一意識別子を使用して addActivities エンドポイントを呼び出します。
たとえば、Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52を持つユーザーが、2022 年 4 月 11 日午後 4 時 25 分にチケット番号がSR00145されたヘルプデスク チケットにコメントした場合、そのアクティビティの送信要求は次のようになります。
POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json
"activities": [
{
"type": "commented",
"startDateTime": "2022-04-11T16:25:34.3202005Z",
"performedBy": {
"id": "18948b93-d3ed-4307-9981-10fc36a08a52",
"type": "user"
}
}
]
また、アイテムを作成するのと同じ要求内の項目にアクティビティを追加することもできます。
aclやcontentなど、アクティビティを別のエンティティとして追加します。 この方法でアクティビティを追加する場合は、アクティビティの @odata.type を含めるか、要求が失敗します。 タイムスタンプが 7 日を超えるアクティビティは、Microsoft 365 アプリでは表示されません。 エンド ユーザーは、Microsoft 365 アプリで、アクセスできるアイテムとアクティビティのアクティビティ (共有、作成、編集など) についてのみ表示できます。
アイテムを更新する
外部サービスでアイテムが更新されたときには (ヘルプデスク チケットが割り当てられた場合や、製品の説明が更新された場合)、そのアイテムの作成時に割り当てた固有の識別子を使用して externalItem を更新することで、インデックス内のエントリを更新できます。
PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
{
"assignee": "alexw@contoso.com"
}
アイテムを削除する
インデックスから項目を削除するには、アイテムの作成時に割り当てられた一意の識別子を使用して externalItem を削除します。
DELETE /external/connections/contosohelpdesk/items/SR00145
データの同期を維持する
データの同期を維持する方法を選択する場合は、次の情報を考慮してください。
クロール メカニズム:
- 増分クロール: ソース データの追加を検出してプッシュします。フル クロールよりもパフォーマンスの集中が少なくなります。
- フル クロール: ソース データからアイテム全体をUpdates (再クロール)、追加と削除をすべてキャプチャします。精度は向上しますが、増分クロールよりも時間がかかり、パフォーマンスを集中的に消費します。
同期間隔:
- イベントベース: イベントベースでアイテムの更新をプッシュします。 アイテムの状態などの動的または機密性の高いデータには、この同期間隔を使用することをお勧めします。
- スケジュール済み: アイテムの更新を一定の間隔 (N 分ごと) でプッシュします。 この同期間隔は、Wiki や Web ページなど、更新頻度が低いコンテンツが豊富なデータや機密でないデータに使用することをお勧めします。
最終的には、データ更新戦略の選択は、データの種類とコンピューティング機能によって異なります。