アプリケーションで Microsoft Graph接続に追加したアイテムの作成、更新、および削除Create, update, and delete items added by your application in the Microsoft Graph connection

アプリケーションで Microsoft Search サービスに追加したアイテムは、Microsoft Graph の externalItem リソースで表されます。Items added by your application to the Microsoft Search service are represented by the externalItem resource in Microsoft Graph.


Microsoft Graph のコネクタは現在パブリック プレビューの状態です。Microsoft Graph connectors are currently in public preview status. コネクタ機能にアクセスするには、テナントの対象指定リリース オプションを有効にする必要があります。To gain access to connectors functionality, you must turn on the Targeted release option in your tenant. 詳細については、「 コネクタのプレビュープログラム」を参照してください。See more details on the connectors preview program.

接続を作成したら、コンテンツを追加できます。Once you have created a connection, you can add your content. データソース内の各アイテムは、固有のアイテム id が含まれる Microsoft Graph の externalItem として表示される必要があります。この id は、Microsoft Graph からアイテムを作成、更新、または削除するために使用されます。Each item from your data source must be represented as an externalItem in Microsoft Graph with a unique item id. This id is used to create, update or delete the item from Microsoft Graph. データソースの主キーを itemId として使用することもできるし、1つまたは複数のフィールドから取得することもできます。You can use the primary key from your data source as the itemId or derive it from one or more fields. externalItem には、アクセス制御リスト、プロパティ、コンテンツの3つの主要な構成要素があります。An externalItem has three key components: access control list, properties, and content.

アクセス制御リストAccess control list

アクセス制御リストは、指定した役割が Microsoft エクスペリエンスでアイテムを表示するためのアクセスを許可されるか、または拒否されるかどうかを指定するために使用されます。The access control list is used to specify whether the given roles are granted or denied access to view items in Microsoft experiences. これは、Azure Active Directory ユーザーまたはグループを表すアクセス制御エントリの配列です。It is an array of access control entries, each representing an Azure Active Directory user or group. 3つ目のアクセス制御エントリの種類 Everyone には、テナント内のすべてのユーザーを表します。There is a third access control entry type Everyone that represents all the users in the tenant.


accessType 値 denygrantより優先される。The accessType value deny takes precedence over grant. たとえば、上に表示されているアイテムの Everyone にアクセス権が与えられていて、特定のユーザーのアクセスが拒否されている場合、このユーザーの有効な権限は denyです。For example, in the item shown above, while Everyone is granted access and a specific user is denied access, the effective permission for this user is deny.

お客様のデータソースに、そのアイテムのアクセス許可の設定に使用する、使用しているヘルプデスクシステム内のチームなどの Azure Active Directory 以外のグループがある場合は、グループ同期API を使用して Microsoft Graph で外部グループを作成し、 allow また deny のアクセス許可をレプリケートできます。If your data source has non Azure Active Directory groups, such as teams within your helpdesk system, used to set permissions for the item, you can create external groups in Microsoft Graph using the group sync APIs to replicate the allow or deny permissions. 各グループメンバーシップの更新によって大量のアイテムの更新が発生する可能性があるので、個々のアイテムのアクセス制御リストに外部グループのメンバーシップを直接展開しないようにします。Avoid expanding the membership of your external groups directly into the access control lists of individual items since each group membership update could lead to a storm of item updates.

外部グループは、外部グループ、Azure Active Directory ユーザー、および Azure Active Directory グループで構成できます。External groups can consist of another external group, Azure Active Directory users, and Azure Active Directory groups. Azure 以外の Active Directory ユーザーがいる場合は、それらをアクセス制御リストの Azure Active Directory ユーザーに変換する必要があります。If you have non-Azure Active Directory users, you must translate them to Azure Active Directory users in your access control list.


[プロパティ] コンポーネントは、Microsoft Graph の操作性に役立つアイテムのメタデータを追加するために使用されます。The properties component is used to add item metadata that is useful in Microsoft Graph experiences. アイテムを追加する前に、スキーマを登録する必要があります。またデータ型を サポートされているデータ型に変換する必要があります。You must register the schema for the connection before adding items into it and convert datatypes into supported datatypes.



コンテンツコンポーネントは、フルテキストインデックスを作成する必要があるアイテムの大部分を追加するために使用されます。The content component is used to add the bulk of the item that needs to be full text indexed. 例としては、チケットの説明、ファイルの本文またはwiki ページの本文から解析したテキストなどがあります。Examples include ticket description, parsed text from a file body, or a wiki page body.

コンテンツは、Microsoftエクスペリエンスを通して 関連性に影響する主要なフィールドの1つです。Content is one of the key fields influencing relevance across Microsoft experiences. text HTMLの種類のコンテンツをサポートしています。We support content of the type text and HTML. データソースにバイナリファイルが含まれる場合は、そのファイルを解析して本文にしてから、Microsoft Graph に追加します。If your data source has binary files, you can parse them to text before adding them to Microsoft Graph.


コンテンツを検索結果テンプレートに直接追加することはできませんが、生成された結果スニペットを使うことができます。このスニペットは、コンテンツ内の関連セクションの動的に生成されるプレビューです。Content cannot be directly added into a search result template, but you can use a generated result snippet which is a dynamically generated preview of the relevant sections within content.


データソース内のコンテンツが変更された場合は、接続アイテムと同期する必要があります。When content in your data source changes, you must sync it with your connection items. アイテム全体を更新するか、1つ以上のコンポーネントを更新することができます。You can either update the entire item or update one or more of its components. コンテンツを Microsoft Graph に追加した後は、 バーティカルと結果の種類の設定とMicrosoft Graph Search APIを使用した後で、Microsoft Searchエクスペリエンス全体で検索を行うことができます。Once your content has been added to Microsoft Graph, you can search for it through the Microsoft Search experience after setting up verticals and result types or using the Microsoft Graph Search API.

アイテムの追加Add an item

アイテムは、externalItem を作成することでインデックスに追加できます。You can add an item to the index by creating an externalItem. アイテムの作成時に、URL で固有の識別子を割り当てます。When you create an item, you assign a unique identifier in the URL.

たとえば、ヘルプデスク チケットのインデックスを作成するために、アプリケーションではチケット番号を使用できます。For example, your application may index helpdesk tickets using the ticket number. チケットのチケット番号が SR00145 の場合は、要求は次のようになります。If a ticket has the ticket number SR00145, the request may look like the following.

PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

  "title": "WiFi outage in Conference Room A",
  "status": "New",
  "assignee": "meganb@contoso.com"

![注] 管理者は、Microsoft Search UI でインデックス付きアイテムを見つける前に、対応する接続​​の検索結果ページをカスタマイズする必要があります。![NOTE] Before indexed items can be found in the Microsoft Search UI, an administrator must customize the search results page for the corresponding connection.

アイテムを更新するUpdate an item

外部サービスでアイテムが更新されたときには (ヘルプデスク チケットが割り当てられた場合や製品の説明が更新された場合)、そのアイテムの作成時に割り当てた固有の識別子を使用して externalItem を更新することで、インデックス内のエントリを更新できます。When an item is updated in the external service (helpdesk ticket is reassigned, or a product description is updated), you can update its entry in the index by updating the externalItem, using the unique identifier assigned to the item when you created it.

PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

  "assignee": "alexw@contoso.com"

アイテムを削除するDelete an item

アイテムは、そのアイテムの作成時に割り当てた固有の識別子を使用して externalItem を削除することで、インデックスから削除できます。You can remove items from the index by deleting the externalItem, using the unique identifier assigned to the item when you created it.

DELETE /external/connections/contosohelpdesk/items/SR00145

次の手順Next steps