schemaExtension リソースの種類 (スキーマ拡張機能)

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

スキーマの拡張機能を使用すると、拡張するスキーマを定義し、厳密に型指定されたカスタム データをリソースの種類に追加できます。 カスタム データは拡張したリソースの複合型として表示されます。 スキーマ拡張機能は次のリソースの種類でサポートされています。

スキーマ拡張機能の定義を管理するには、このリソースと関連するメソッドを使用します。 拡張リソース インスタンスのスキーマ拡張データを管理するには、リソース インスタンスの管理に使用するのと同じ REST 要求を使用します。 カスタム データのグループへの追加方法については、スキーマ拡張機能の例を参照してください。

スキーマ拡張機能の制限を含む Microsoft Graph 機能拡張の詳細については、「拡張機能を使用してリソースにカスタム プロパティを追加する」を参照してください。

メソッド

メソッド 戻り値の型 説明
Create schemaExtension スキーマ拡張定義とそれに関連付けられているスキーマ拡張プロパティを作成します。
List schemaExtension 使用可能な schemaExtension の定義とそのプロパティを一覧表示します。
Get schemaExtension 特定の schemaExtension 定義のプロパティを読み取ります。
Update schemaExtension schemaExtension 定義を更新します。 この操作を使用して、説明、状態、ターゲット型を更新するか、スキーマ拡張定義にさらにプロパティを追加します。
Delete なし schemaExtension 定義を削除します。

プロパティ

プロパティ 型 説明
description String スキーマ拡張機能の説明。 $filter (eq)をサポートしています。
id String スキーマ拡張機能の定義の一意の識別子。
値の割り当ては、以下の 2 方法のいずれかで行うことができます。
  • 検証済みドメインの 1 つの名前とスキーマ拡張機能の名前を連結して、この形式の一意の文字列 {domainName}_{schemaName} を形成します。 次に例 contoso_mySchema を示します。
  • スキーマ名を指定し、Microsoft Graph でそのスキーマ名を使用して、ext{8-random-英数字-chars}_{schema-name} という形式で ID の割り当てを完了させます。 たとえば、 です extkvbmkofy_mySchema。
作成後、このプロパティは変更できません。 $filter (eq)をサポートしています。

注: 整数で始まる ID ではクエリ機能が制限される可能性があるため、ID は A から Z の間の英字で始めることをお勧めします。

$filter (eq)をサポートしています。
owner String スキーマ拡張機能の所有者であるアプリケーションの appId です。 スキーマ定義の所有者は、作成および更新操作中に明示的に指定する必要があります。または、次のようにMicrosoft Entra IDによって暗黙的かつ自動割り当てされます。
  • 委任されたアクセス:
    • サインインしているユーザーは、Microsoft Graph を呼び出してスキーマ拡張機能定義を作成するアプリの所有者である必要があります。
    • サインインしているユーザーが呼び出し元アプリの所有者でない場合は、 所有者プロパティを 明示的に指定し、所有するアプリの appId を 割り当てる必要があります。
  • アプリのみのアクセス:
    • owner プロパティは要求本文では必要ありません。 代わりに、呼び出し元のアプリにスキーマ拡張機能の所有権が割り当てられます。

そのため、たとえば、Graph エクスプローラーを使用して新しいスキーマ拡張機能定義を作成する場合は、owner プロパティを指定する必要があります。 設定すると、このプロパティは読み取り専用で、変更することはできません。 $filter (eq) をサポートしています。
properties extensionSchemaProperty コレクション スキーマ拡張機能の定義を構成するプロパティ名と種類のコレクション。
status String スキーマ拡張機能のライフサイクル状態。 考えられる状態は、InDevelopment、Available、および Deprecated です。 作成時に自動で InDevelopment に設定されます。 可能な状態遷移と動作の詳細については、「スキーマ拡張機能のライフサイクル」を参照してください。 $filter (eq) をサポートしています。
targetTypes String コレクション スキーマ拡張機能に適用できる (拡張機能をサポートできる) 一連の Microsoft Graph の種類。 administrativeUnit、連絡先、デバイス、イベント、グループ、メッセージ、組織、投稿、todoTask、todoTaskList、またはユーザーから選択します。

スキーマ拡張機能のライフサイクル

アプリによってスキーマ拡張機能定義が作成されると、そのアプリがスキーマ拡張機能の所有者としてマークされます。

所有者アプリは、ステータス プロパティで PATCH 操作を使用して、拡張機能をさまざまな状態のライフサイクル間で移動できます。 所有者アプリは現在の状態に応じて、拡張機能を更新または削除することができます。 スキーマ拡張機能の更新は常に、付加的で中断を必要としない更新でなければなりません。

State ライフ サイクル状態の動作
InDevelopment
  • 作成後の初期状態。 所有者アプリは引き続きスキーマ拡張機能を開発しています。
  • この状態で、所有者のアプリが登録されているディレクトリと同じディレクトリにあるアプリは、このスキーマの定義を持つリソース インスタンスを拡張することができます (アプリにそのリソースへのアクセス許可がある場合)。
  • マルチテナント所有者アプリの場合、ホーム ディレクトリとは異なるディレクトリにある所有者アプリのインスタンスのみが、このスキーマ定義を使用してリソース インスタンスを拡張するか (アプリがそのリソースに対するアクセス許可を持っている場合)、拡張データを読み取ることができます。
  • 所有者アプリのみで、拡張機能の定義に追加の変更を加えて更新することができます。
  • 所有者アプリのみが拡張機能の定義を削除できます。
  • 所有者アプリは、拡張機能を状態にInDevelopmentAvailable移動できます。
Available
  • スキーマ拡張機能は、テナント内のすべてのアプリで利用できます。
  • 所有者アプリが拡張機能を に Available設定した後、任意のアプリが拡張機能で指定されたリソースの種類のインスタンスにカスタム データを追加できます (アプリがそのリソースに対するアクセス許可を持っている場合)。 アプリは、新しいインスタンスの作成時または既存のインスタンスの更新時にカスタム データを割り当てることができます。
  • 所有者アプリのみで、拡張機能の定義に追加の変更を加えて更新することができます。 この状態では、どのアプリでも拡張機能の定義を削除することはできません。
  • 所有者アプリは、スキーマ拡張機能を状態にAvailableDeprecated移動できます。
Deprecated
  • スキーマ拡張機能の定義の読み取りまたは変更はできなくなります。
  • どのアプリも、新しいプロパティを表示、更新、追加したり、拡張機能を削除したりすることはできません。
  • ただし、アプリは、既存の拡張 プロパティ値の読み取り、更新、または削除を行うことができます。

注:

他のテナントの他の開発者によって作成されたスキーマ拡張定義 (として Availableマーク) は、すべての開発者に表示されます (すべてのスキーマ拡張機能を一覧表示)。 これは、テナント固有のデータだけを返す他の API とは異なります。 一方、スキーマ拡張機能の定義に基づいて作成された拡張データはテナント固有のものであり、明示的に許可されたアプリのみがアクセスできます。

JSON 表記

次の JSON 表現は、リソースの種類を示しています。

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

関連コンテンツ