Microsoft Graph 接続のスキーマを登録するRegister schema for the Microsoft Graph connection

接続 スキーマ によって、さまざまな Microsoft Graphエクスペリエンス でのコンテンツの使用方法が決まります。The connection schema determines how your content will be used in various Microsoft Graph experiences. [スキーマ] は、属性、ラベル、エイリアスと共に、接続に追加する予定のすべてのプロパティのフラットな一覧です。Schema is a flat list of all the properties that you plan to add to the connection along with their attributes, labels, and aliases. 接続に項目を追加する前に、スキーマを登録する必要があります。You must register the schema before adding items into the connection.

重要

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.

スキーマの例Example schema

次の表は、work ticket システムコネクタに使用できるスキーマの例を示しています。The following table represents an example of a possible schema for a work ticket system connector.

プロパティProperty 種類Type 検索可能Searchable クエリ可能Queryable 取得可能Retrievable 絞り込み可能Refinable ラベルLabels エイリアスAliases
ticketIdticketId StringString IDID
titletitle StringString ✔️ ✔️ ✔️ タイトルtitle
createdBycreatedBy StringString ✔️ ✔️ createdBycreatedBy creatorcreator
assignedToassignedTo StringString ✔️ ✔️
lastEditedDatelastEditedDate DateTimeDateTime ✔️ ✔️ ✔️ lastModifiedDateTimelastModifiedDateTime editedDateeditedDate
lastEditedBylastEditedBy StringString ✔️ ✔️ ✔️ lastModifiedBylastModifiedBy 編集済みedited
workItemTypeworkItemType StringString ✔️ ✔️ ticketTypeticketType
prioritypriority Int64Int64 ✔️
tagstags StringCollectionStringCollection ✔️ ✔️ ✔️
statusstatus StringString ✔️ ✔️
urlurl StringString urlurl
解決済みresolved ブール値Boolean ✔️ ✔️

プロパティの属性Property attributes

検索可能Searchable

プロパティが検索可能であれば、その値がフルテキストインデックスに追加されます。If a property is searchable, its value is added to the full text index. 検索を実行すると、検索可能なフィールドまたはその コンテンツのいずれかにヒットがある場合は、検索結果が返されます。When a user performs a search, we return results if there is a search hit in one of the searchable fields or its content.

プロパティおよびコンテンツに対してヒットする結果を表示する "デザイン" の検索A search for "design" displaying results for hits against properties and content

プロパティ (titletags)およびコンテンツ に対するヒットの結果を表示する "デザイン" の検索A search for "design" displaying results for hits against properties (title, tags) and content

クエリ可能Queryable

プロパティがクエリ可能な場合は、ナレッジクエリ言語 (KQL) を使用して、クエリできます。If a property is queryable, you can query against it using knowledge query language (KQL). KQL は、1つ以上のフリーテキストのキーワード (単語または語句) またはプロパティの制限から構成されます。KQL consists of 1 or more free text keywords (words or phrases) or property restrictions. クエリ自身で指定するか、プログラムでクエリに含めるかして、クエリにプロパティ名を含める必要があります。The property name must be included in the query, either specified in the query itself or included in the query programmatically. ワイルドカード演算子 (*) を使用して、一致するプレフィックスを使用できます。You can use prefix matching with the wildcard operator(*).

注意

接尾語一致は、サポートされていません。Suffix matching is not supported.

このプレフィックスに一致する結果が表示されている "検索用のba *" の検索

このプレフィックス * と一致する検索結果を表示する* "検索 ba"の検索*A search for "search ba" displaying results that match this prefix*

"tags:design" の検索は、tags プロパティの "design" のアイテムに結果の範囲が狭くなります。

"ags:design" の検索は、tags プロパティの "design" のアイテムに結果の範囲が狭くなります。A search for "tags:design" scoping down results to items with "design" in the tags property

取得可能Retrievable

プロパティを取得できる場合、検索結果でその値を返すことができます。If a property is retrievable, its value can be returned in search results. 表示テンプレートに追加する、またはクエリから取得する必要があるプロパティで、検索結果に関係があるものは、取得できるようにする必要があります。Any property that you want to add in the display template or be returned from the query and be relevant in search results must be retrievable. editHistoryなどの大きなプロパティや、あまりにも多くのプロパティが取得可能だと、検索の遅延が増加します。Marking large properties, such as editHistory, or too many properties as retrievable will increase search latency. 選択的にして、関連するプロパティを選択します。Be selective and choose relevant properties.

結果としてレンダリングされた取得可能なプロパティのセット

結果としてレンダリングされた取得可能なプロパティ (titlelastEditedBy など) のセットA set of retrievable properties (title, lastEditedBy etc.) rendered as a result

絞り込み可能Refinable

プロパティが絞り込み可能な場合、管理者は、Microsoft 検索結果ページでカスタムフィルターとして設定できます。If a property is refinable, an admin can configure it as a custom filter in the Microsoft Search results page.

絞り込み可能なプロパティのタグを使って結果を絞り込む

結果を絞り込むtags、絞り込み可能なプロパティRefine results by tags, a refinable property

ラベルLabels

ラベルは、Microsoft によって公開されているよく知られているタグで、スキーマのプロパティに対して追加することができます。A label is a well known tag published by Microsoft that you can add against a property in your schema. ラベルを追加することで、さまざまな Microsoft 製品がその特性を理解し、より良い操作性を実現できるようになります。Adding a label helps various Microsoft products understand the property and provide a better experience.

ラベルLabel 説明Description
titletitle 検索 & 他のエクスペリエンスに表示するアイテムのタイトルThe title of the item that you want shown in search & other experiences
urlurl データソース内のアイテムのターゲット URLThe target URL of the item in the data source
createdBycreatedBy データソースでアイテムを作成したユーザーの名前Name of the person who created the item in the data source
lastModifiedBylastModifiedBy データソースでアイテムを最後に編集したユーザーの名前Name of the person who most recently edited the item in the data source
authorsauthors データソース内のアイテムに対して参加した、または共同作業したすべてのユーザーの名前Name of all the people who participated/collaborated on the item in the data source
createdDateTimecreatedDateTime アイテムがデータソース内で作成された日付 &時間Date & time that the item was created in the data source
lastModifiedDateTimelastModifiedDateTime アイテムがデータソースで、最後に変更された日付 & 時間です。Date & time the item was last modified in the data source
fileNamefileName ファイルの場合、データソース内のファイルの名前In case of a file, the name of the file in the data source
FileExtensionfileExtension ファイルの場合、データソース内のファイルの拡張子In case of a file, the extension of the file in the data source

たとえば、lastEditedByされた接続プロパティの意味は、 lastModifiedByされたMicrosoftラベルと同じ意味です。For example, the connection property lastEditedBy has the same meaning as the Microsoft label lastModifiedBy.

できるだけ多くのラベルを追加しますが、プロパティに正確にマップされていることを確認します。Add as many labels as you can, but ensure that they are accurately mapped to properties. 必要ない場合は、プロパティにラベルを追加しません。Do not add a label to a property if it doesn't make sense. マッピングが間違っていると、操作性が劣化します。Incorrect mappings will deteriorate the experience.

重要

ラベルにマップするすべてのプロパティを取得できるようにする必要があります。All properties that you map to labels must be retrievable.

関連性Relevance

できるだけ沢山正確にマップされたラベルを適用することで、検索を通してコンテンツの検出が改善できます。By applying as many accurately mapped labels as possible, you can also improve the discovery of your content through search. 以下のラベルのうち、できるだけ多くのラベルを定義することを強くお勧めします。降順に潜在的な検出への影響によってリストされています。We highly recommend defining as many of the below labels as possible, listed by potential impact on discovery in descending order:

  • タイトルtitle
  • lastModifiedDateTimelastModifiedDateTime
  • lastModifiedBylastModifiedBy
  • urlurl
  • ファイル名filename
  • FileExtensionfileExtension

検索の場合のシナリオは、次の点に注意してください。For discovery, i.e. search scenarios, please note:

  • マッピングが正しいことを確認します。Ensure that your mappings are accurate.
  • 大規模なコンテンツを含むラベルとしてプロパティを使用すると、検索待ち時間が長くなり、検索の結果が返されるまでの待ち時間が長くなる可能性があります。When you use a property as label that contains large content, you might increase search latency and have to wait longer for search to return results.
  • 特に、複数の接続での検索ができるようにカスタムの垂直検索を構成するシナリオでは、可能な限り多くのラベルを指定すると、検索結果が大きくなるという利点があります。Especially in the scenario where you configure a custom vertical that allows search over more than one connection, the search outcomes greatly benefit from appointing as many labels as possible.

既定の検索結果の種類Default result types

ラベルは、既定の検索結果の種類が生成される方法にも影響します。Labels also affect how default result types are generated. 最低数のタイトルとコンテンツラベルを追加すると、接続用に結果の種類が確実に作成されます。Adding the title and content labels at a minimum will ensure that a result type is created for your connection.

タイトルと結果スニペットを含む既定の検索結果の種類

既定の結果型をtitle と結果スニペットでA default result type with title and a result snippet

これらのラベルを昇順にリストして、該当する場合に定義すると、既定の検索結果の種類によって、より良い操作性が得られます。Your default result type will provide a better experience when you define these labels, when applicable, listed by ascending order:

  • タイトルtitle
  • urlurl
  • lastModifiedBylastModifiedBy
  • lastModifiedDateTimelastModifiedDateTime
  • fileNamefileName
  • FileExtensionfileExtension

最後に、ラベルを割り当てるときに、次のことを確認します。Finally, when assigning labels, ensure the following:

  • ラベルとして機能するように選択したプロパティは、取得可能にする必要があります。The properties that you select to function as labels need to be marked retrievable.
  • プロパティと割り当てられたラベルには、同じデータ型が必要です。The properties and their assigned labels must have the same datatype.
  • 1つのラベルを1つのプロパティに正確に割り当てることができます。You can map exactly one label to exactly one property.

エイリアスAliases

エイリアスは、割り当てるプロパティのわかりやすい名前です。Aliases are friendly names for properties that you assign. これらは、絞り込み可能なプロパティフィルターのクエリおよび選択に使用されます。These will be used in queries and selections in refinable property filters.

次の手順Next steps