拡張機能を使用してカスタム データをリソースに追加する

Microsoft Graph は、ユーザーメッセージなどの数多くのリソースを通じて、多用なユーザー中心のデータと分析情報にアクセスするための単一の API エンドポイントを提供しますします。独自のアプリケーション データを Microsoft Graph で拡張することもできます。外部にデータの保存を必要とせず、Microsoft Graph のリソースにカスタム プロパティを追加できます。

たとえば、ユーザー リソースを拡張することによって、アプリを軽量に保ちながら、アプリ固有のユーザー プロファイル データを Microsoft Graph に格納できます。 または、アプリの既存のユーザー プロファイル ストアを保持し、ユーザー リソースにアプリ固有のストア識別子を追加することもできます。

Microsoft Graph には、2 種類の拡張機能が備わっています。ご自分のアプリケーションの必要に最適な拡張機能の種類を選択してください。

  • オープン拡張機能:開発者が使用するのに適しています。
  • スキーマ拡張機能:型指定されたデータを格納すること、スキーマの検出と共有を容易にすること、フィルターを可能にすること、将来、入力データの検証と承認を可能にすることに関心のある開発者にとって、用途のより広いメカニズムとなります。

重要: 拡張機能は、アカウント資格情報、政府による識別番号、カード名義人データ、財務会計データ、医療情報、機密性のある背景情報などの個人を特定できる機密情報を格納するために使用すべきではありません。

サポートされているリソース

次の表は、オープン拡張機能とスキーマ拡張機能をサポートするリソースを示し、それらが一般提供 (GA - v1.0 およびベータ版エンドポイントで提供) されるようになったか、それともプレビュー段階 (ベータ版エンドポイントでのみ提供) かを示します。

リソース オープン拡張機能 スキーマ拡張機能
管理単位 プレビューのみ プレビューのみ
予定表イベント GA GA
デバイス GA GA
グループ GA GA
グループ予定表イベント GA GA
グループ会話の投稿 GA GA
メッセージ GA GA
組織 GA GA
個人用連絡先 GA GA
ユーザー GA GA
To Do タスク GA GA
To Do タスクリスト GA GA

職場または学校のアカウントを使用してサインインしている場合、これらすべてのリソースについて拡張機能を使用することができます。 また、個人用アカウントでサインインしている場合は、イベント投稿グループメッセージ連絡先ユーザー などのリソースで拡張機能を使用することができます。

オープン拡張機能

オープン拡張機能 (以前の Office 365 データ拡張機能) は、オープン タイプであり、型指定されていないアプリ データを直接リソース インスタンスに追加するための柔軟な方法を提供します。

オープン拡張機能は、カスタム データとともに、リソース インスタンスの 拡張機能 ナビゲーション プロパティを介してアクセスできます。 オープン拡張機能で 事前に定義される 書き込み可能なプロパティは、extensionName プロパティだけです。 オープン拡張機能を作成する場合、extensionName プロパティにテナント内で一意の名前を割り当てる必要があります。

これを行う方法の 1 つは、独自のドメイン に依存する逆引きドメイン ネーム システム (DNS) 形式 (例: Com.Contoso.ContactInfo) を使用することです。

拡張機能名に Microsoft ドメイン (Com.Microsoft または Com.OnMicrosoft) を使用しないでください。

リソース インスタンスにオープン拡張機能を作成し、すべてのカスタム データを同じ操作で保存することができます (サポートされているリソースの一部については、「既知の制限」を参照してください)。

その後、拡張機能とそのデータの 読み取り更新、または削除 を行うことができます。

オープン拡張機能の例:オープン拡張機能を使用したユーザーへのカスタム データの追加

スキーマ拡張機能

スキーマ拡張機能を使用すると、リソースの種類の拡張に使用するスキーマを定義できます。最初に、スキーマ拡張機能の定義を作成します。次に、それを使用して厳密に型指定されたカスタム データを含むリソース インスタンスを拡張します。さらに、スキーマ拡張機能の状態を制御し、他のアプリで検出できるようにすることができます。これらのアプリでは、そのデータの拡張機能を使用して、エクスペリエンスを拡張して構築できます。

スキーマ拡張機能定義を作成する場合、その id の一意の名前を指定する必要があります。次の 2 つの名前付けオプションがあります。

  • ご使用のテナントで検証済みのバニティ .com.net.gov.edu.org ドメインのいずれかが既にある場合、ドメイン名とスキーマ名を一緒に使用して一意の名前を定義できます (形式: {domainName}_{schemaName})。 たとえば、バニティ ドメインが contoso.com の場合、idcontoso_mySchema と定義できます。 これは優先オプションです。
  • 検証済みバニティ ドメインがない場合、id をスキーマ名 (ドメイン名のプレフィックスなし) に設定できます (例: mySchema)。Microsoft Graph によって、指定した名前に基づいて文字列 ID が割り当てられます (形式: ext{8-random-alphanumeric-chars}_{schema-name})。例: extkvbmkofy_mySchema

この一意の名前は、拡張リソース インスタンスにカスタム データを格納する複合型の名前として使用される id に示されます。

オープン拡張機能とは異なり、スキーマ拡張機能の定義 (リスト作成取得更新、および削除) とそのデータ (データの追加、取得、更新、および削除) の管理は異なるセットの API 操作になっています。

スキーマ拡張機能は、対象となるリソースのインスタンスで複合型としてアクセス可能であるため、次の方法を使用してスキーマ拡張機能でカスタム データの CRUD 操作を行うことができます。

  • リソース POST メソッドを使用して、新しいリソース インスタンスを作成するときにカスタム データを指定できます。 連絡先イベントメッセージ投稿 のリソースでは、PATCH 操作を使用してスキーマの拡張機能を作成する必要があるという 既知の問題があることにご注意ください。
  • リソース GET メソッドを使用して、カスタム データを読み取ることができます。
  • リソース PATCH メソッドを使用して、既存のリソース インスタンスでカスタム データを追加または更新できます。
  • リソース PATCH メソッドを使用して、複合型を null に設定し、リソース インスタンスのカスタム データを削除できます。

スキーマ拡張機能の例:スキーマ拡張機能を使用したグループへのカスタム データの追加

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

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

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

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

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

サポート対象のプロパティ データ型

スキーマ拡張機能でプロパティを定義する場合、次のデータ型がサポートされています。

プロパティの種類 注釈
Binary 最大 256 バイトです。
Boolean メッセージ、イベント、投稿ではサポートされていません。
DateTime ISO 8601 形式で指定する必要があります。UTC で格納されます。
整数 32 ビット値です。メッセージ、イベント、投稿ではサポートされていません。
String 最大 256 文字です。

注: 複数値プロパティはサポートされていません。

Azure AD ディレクトリのスキーマ拡張機能

Azure AD は、いくつかの directoryObject リソースで、ディレクトリ スキーマ拡張と呼ばれる同様の拡張機能をサポートしています。Microsoft Graph API を使用して、拡張プロパティの定義を管理し、これらの拡張のプロパティで データ を追加、取得、更新、削除できます。

アクセス許可

特定のリソース上の拡張機能データに対して読み書きするには、そのリソースに対して読み書きするときに必要となるのと同じ アクセス許可が必要になります。たとえば、サインイン済みのユーザーのプロファイルをカスタム アプリ データで更新できるようにするには、アプリに User.ReadWrite.All アクセス許可を付与しておく必要があります。

また、スキーマ拡張機能の定義を作成および管理できるようにするには、アプリケーションに Directory.AccessAsUser.All アクセス許可を付与しておく必要があります。

データの上限

オープン拡張機能の上限

次の制限は、ディレクトリ リソース (ユーザーグループデバイスadministrativeUnit組織) に適用されます。

  • オープン拡張機能のデータの上限は 2 KB (拡張機能の定義自体を含む) です。
  • アプリケーションでは、リソース インスタンスごとに最大 2 つのオープン拡張機能を追加できます。

以下に示す上限が Outlook のリソース (メッセージイベント連絡先 など) に適用されます。

スキーマの拡張機能の上限

アプリケーションで作成できる スキーマ拡張機能 の定義は最大 5 つです。

既知の制限

拡張機能の使用に関する既知の制限については、既知の問題に関する記事の「拡張機能」セクションを参照してください。

拡張機能の例

関連項目