拡張機能を使用してカスタム データをリソースに追加するAdd custom data to resources using extensions

Microsoft Graph は、ユーザーメッセージなどの数多くのリソースを通じて、多用なユーザー中心のデータと分析情報にアクセスするための単一の API エンドポイントを提供しますします。独自のアプリケーション データを Microsoft Graph で拡張することもできます。外部にデータの保存を必要とせず、Microsoft Graph のリソースにカスタム プロパティを追加できます。Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights through a number of resources such as user and message. You can also extend Microsoft Graph with your own application data. You can add custom properties to Microsoft Graph resources without requiring an external data store.

たとえば、ユーザー リソースを拡張することによって、アプリを軽量に保ちながら、アプリ固有のユーザー プロファイル データを Microsoft Graph に格納できます。For example, you might decide to keep your app lightweight and store app-specific user profile data in Microsoft Graph by extending the user resource. または、アプリの既存のユーザー プロファイル ストアを保持し、ユーザー リソースにアプリ固有のストア識別子を追加することもできます。Alternatively, you might want to retain your app’s existing user profile store, and simply add an app-specific store identifier to the user resource.

Microsoft Graph には、2 種類の拡張機能が備わっています。ご自分のアプリケーションの必要に最適な拡張機能の種類を選択してください。Microsoft Graph offers two types of extensions. Choose the extension type that best suits your application needs:

  • オープン拡張機能:開発者が使用するのに適しています。Open extensions: A good way for developers to get started.
  • スキーマ拡張機能:型指定されたデータを格納すること、スキーマの検出と共有を容易にすること、フィルターを可能にすること、将来、入力データの検証と承認を可能にすることに関心のある開発者にとって、用途のより広いメカニズムとなります。Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future, being able to perform input data validation and authorization.

重要: 拡張機能は、アカウント資格情報、政府による識別番号、カード名義人データ、財務会計データ、医療情報、機密性のある背景情報などの個人を特定できる機密情報を格納するために使用すべきではありません。Important: You should not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.

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

次の表は、オープン拡張機能とスキーマ拡張機能をサポートするリソースを示し、それらが一般提供 (GA - v1.0 およびベータ版エンドポイントで提供) されるようになったか、それともプレビュー段階 (ベータ版エンドポイントでのみ提供) かを示します。The following table lists the resources that support open and schema extensions, and indicates whether they have reached general availability (GA - available in both the v1.0 and beta endpoints) or are in preview (available only in the beta endpoint).

リソースResource オープン拡張機能Open extensions スキーマ拡張機能Schema extensions
管理単位Administrative unit プレビューのみPreview only プレビューのみPreview only
予定表イベントCalendar event GAGA GAGA
デバイスDevice GAGA GAGA
グループGroup GAGA GAGA
グループ予定表イベントGroup calendar event GAGA GAGA
グループ会話の投稿Group conversation post GAGA GAGA
メッセージMessage GAGA GAGA
組織Organization GAGA GAGA
個人用連絡先Personal contact GAGA GAGA
ユーザーUser GAGA GAGA

職場または学校のアカウントを使用してサインインしている場合、これらすべてのリソースについて拡張機能を使用することができます。You can use extensions on all these resources when signed in with a work or school account. また、個人用アカウントでサインインしている場合は、イベント投稿グループメッセージ連絡先ユーザーなどのリソースで拡張機能を使用することができます。In addition, you can use extensions on the event, post, group, message, contact, and user resources when signed in with a personal account.

オープン拡張機能Open extensions

オープン拡張機能 (以前の Office 365 データ拡張機能) は、オープン タイプであり、型指定されていないアプリ データを直接リソース インスタンスに追加するための柔軟な方法を提供します。Open extensions (formerly known as Office 365 data extensions) are open types that offer a flexible way to add untyped app data directly to a resource instance.

オープン拡張機能は、カスタム データとともに、リソース インスタンスの拡張機能ナビゲーション プロパティを介してアクセスできます。Open extensions, together with their custom data, are accessible through the extensions navigation property of the resource instance. オープン拡張機能で_事前に定義される_書き込み可能なプロパティは、extensionName プロパティだけです。The extensionName property is the only pre-defined, writable property in an open extension. オープン拡張機能を作成する場合、extensionName プロパティにテナント内で一意の名前を割り当てる必要があります。When creating an open extension, you must assign the extensionName property a name that is unique within the tenant.

これを行う方法の 1 つは、_独自のドメイン_に依存する逆引きドメイン ネーム システム (DNS) 形式 (例: Com.Contoso.ContactInfo) を使用することです。One way to do this is to use a reverse domain name system (DNS) format that is dependent on your own domain, for example, Com.Contoso.ContactInfo.

拡張機能名に Microsoft ドメイン (Com.Microsoft または Com.OnMicrosoft) を使用しないでください。Do not use the Microsoft domain (Com.Microsoft or Com.OnMicrosoft) in an extension name.

リソース インスタンスにオープン拡張機能を作成し、すべてのカスタム データを同じ操作で保存することができます (サポートされているリソースの一部については、「既知の制限」を参照してください)。You can create an open extension in a resource instance and store custom data to it all in the same operation (note known limitation for some of the supported resources).

その後、拡張機能とそのデータの読み取り更新、または削除を行うことができます。You can subsequently read, update, or delete the extension and its data.

オープン拡張機能の例:オープン拡張機能を使用したユーザーへのカスタム データの追加Open extension example: Add custom data to users using open extensions

スキーマ拡張機能Schema extensions

スキーマ拡張機能を使用すると、リソースの種類の拡張に使用するスキーマを定義できます。最初に、スキーマ拡張機能の定義を作成します。次に、それを使用して厳密に型指定されたカスタム データを含むリソース インスタンスを拡張します。さらに、スキーマ拡張機能の状態を制御し、他のアプリで検出できるようにすることができます。これらのアプリでは、そのデータの拡張機能を使用して、エクスペリエンスを拡張して構築できます。Schema extensions allow you to define a schema that you can use to extend a resource type. First, you create your schema extension definition. Then, use it to extend resource instances with strongly-typed custom data. In addition, you can control the status of your schema extension and let it be discoverable by other apps. These apps can in turn use the extension for their data and build further experiences on top of it.

スキーマ拡張機能定義を作成する場合、その id の一意の名前を指定する必要があります。次の 2 つの名前付けオプションがあります。When creating a schema extension definition, you must provide a unique name for its id. There are two naming options:

  • ご使用のテナントで検証済みのバニティ .com.net.gov.edu.org ドメインのいずれかが既にある場合、ドメイン名とスキーマ名を一緒に使用して一意の名前を定義できます (形式: {domainName}_{schemaName})。If you already have a vanity .com,.net, .gov, .edu or a .org domain that you have verified with your tenant, you can use the domain name along with the schema name to define a unique name, in this format {domainName}_{schemaName}. たとえば、バニティ ドメインが contoso.com の場合、idcontoso_mySchema と定義できます。For example, if your vanity domain is contoso.com, you can define an id of, contoso_mySchema. これは優先オプションです。This is the preferred option.
  • 検証済みバニティ ドメインがない場合、id をスキーマ名 (ドメイン名のプレフィックスなし) に設定できます (例: mySchema)。Microsoft Graph によって、指定した名前に基づいて文字列 ID が割り当てられます (形式: ext{8-random-alphanumeric-chars}_{schema-name})。例: extkvbmkofy_mySchemaIf you don’t have a verified vanity domain, you can just set the id to a schema name (without a domain name prefix), for example, mySchema. Microsoft Graph will assign a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, extkvbmkofy_mySchema.

この一意の名前は、拡張リソース インスタンスにカスタム データを格納する複合型の名前として使用される id に示されます。You will see this unique name in id used as the name of the complex type that will store your custom data on the extended resource instance.

オープン拡張機能とは異なり、スキーマ拡張機能の定義 (リスト作成取得更新、および削除) とそのデータ (データの追加、取得、更新、および削除) の管理は異なるセットの API 操作になっています。Unlike open extensions, managing schema extension definitions (list, create, get, update, and delete) and managing their data (add, get, update, and delete data) are separate sets of API operations.

スキーマ拡張機能は、対象となるリソースのインスタンスで複合型としてアクセス可能であるため、次の方法を使用してスキーマ拡張機能でカスタム データの CRUD 操作を行うことができます。Because schema extensions are accessible as complex types in instances of the targeted resources, you can do CRUD operations on the custom data in a schema extension in the following ways:

  • リソース POST メソッドを使用して、新しいリソース インスタンスを作成するときにカスタム データを指定できます。Use the resource POST method to specify custom data when creating a new resource instance. 連絡先イベントメッセージ投稿のリソースでは、PATCH 操作を使用してスキーマの拡張機能を作成する必要があるという既知の問題があることにご注意ください。Note that there is a known issue on the contact, event, message, and post resources that requires creating a schema extension using a PATCH operation.
  • リソース GET メソッドを使用して、カスタム データを読み取ることができます。Use the resource GET method to read the custom data.
  • リソース PATCH メソッドを使用して、既存のリソース インスタンスでカスタム データを追加または更新できます。Use the resource PATCH method to add or update custom data in an existing resource instance.
  • リソース PATCH メソッドを使用して、複合型を null に設定し、リソース インスタンスのカスタム データを削除できます。Use the resource PATCH method to set the complex type to null, to delete the custom data in the resource instance.

スキーマ拡張機能の例:スキーマ拡張機能を使用したグループへのカスタム データの追加Schema extension example: Add custom data to groups using schema extensions

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

アプリによってスキーマ拡張機能定義が作成されると、そのアプリがスキーマ拡張機能の所有者としてマークされます。When your app creates a schema extension definition, the app is marked as the owner of that schema extension.

所有者アプリは、ステータス プロパティで PATCH 操作を使用して、拡張機能をさまざまな状態のライフサイクル間で移動できます。所有者アプリは現在の状態に応じて、拡張機能を更新または削除することができます。スキーマ拡張機能の更新は常に、付加的で中断を必要としない更新でなければなりません。The owner app can move the extension through different states of a lifecycle, using a PATCH operation on its status property. Depending on the current state, the owner app may be able to update or delete the extension. Any updates to a schema extension should always only be additive and non-breaking.

StateState ライフ サイクル状態の動作Lifecycle state behavior
InDevelopmentInDevelopment
  • 作成後の初期状態です。所有者アプリは引き続きスキーマ拡張機能を開発しています。 Initial state after creation. The owner app is still developing the schema extension.
  • この状態で、所有者のアプリが登録されているディレクトリと同じディレクトリにあるアプリは、このスキーマの定義を持つリソース インスタンスを拡張することができます (アプリにそのリソースへのアクセス許可がある限り)。In this state, any app in the same directory where the owner app is registered can extend resource instances with this schema definition (as long as the app has permissions to that resource).
  • 所有者アプリのみで、拡張機能の定義に追加の変更を加えて更新したり、削除したりできます。Only the owner app can update the extension definition with additive changes or delete it.
  • 所有者アプリは拡張機能をInDevelopment から Available の状態に移行できます。The owner app can move the extension from InDevelopment to the Available state.
AvailableAvailable
  • スキーマ拡張機能は、テナント内のすべてのアプリで利用できます。The schema extension is available for use by all apps in any tenant.
  • 所有者アプリで拡張機能を Available に設定した後、どのアプリでも拡張機能で指定されているこれらのリソースの種類のインスタンスにカスタム データを追加できます (アプリにそのリソースへのアクセス許可がある場合)。After the owner app sets the extension to Available, any app can simply add custom data to instances of those resource types specified in the extension (as long as the app has permissions to that resource). アプリは、新しいインスタンスの作成時または既存のインスタンスの更新時にカスタム データを割り当てることができます。The app can assign custom data when creating a new instance or updating an existing instance.
  • 所有者アプリのみで、拡張機能の定義に追加の変更を加えて更新することができます。Only the owner app can update the extension definition with additive changes. この状態では、どのアプリでも拡張機能の定義を削除することはできません。No app can delete the extension definition in this state.
  • 所有者アプリは、スキーマ拡張機能を Available から Deprecated 状態に移行できます。The owner app can move the schema extension from Available to the Deprecated state.
DeprecatedDeprecated
  • スキーマ拡張機能の定義の読み取りまたは変更はできなくなります。The schema extension definition can no longer be read or modified.
  • どのアプリも、新しいプロパティを表示、更新、追加したり、拡張機能を削除したりすることはできません。No app can view, update, add new properties, or delete the extension.
  • ただし、既存の拡張機能の_プロパティ値_の読み取り、更新、または削除は引き続き行えます。Apps can, however, still read, update, or delete existing extension property values.

サポート対象のプロパティ データ型Supported property data types

スキーマ拡張機能でプロパティを定義する場合、次のデータ型がサポートされています。The following data types are supported when defining a property in a schema extension:

プロパティの種類Property Type 注釈Remarks
BinaryBinary 最大 256 バイトです。256 bytes maximum.
BooleanBoolean メッセージ、イベント、投稿ではサポートされていません。Not supported for messages, events and posts.
DateTimeDateTime ISO 8601 形式で指定する必要があります。UTC で格納されます。Must be specified in ISO 8601 format. Will be stored in UTC.
整数Integer 32 ビット値です。メッセージ、イベント、投稿ではサポートされていません。32-bit value. Not supported for messages, events and posts.
StringString 最大 256 文字です。256 characters maximum.

注: 複数値プロパティはサポートされていません。Note: Multi-value properties are not supported.

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

Azure AD は、いくつかの directoryObject リソースで、ディレクトリ スキーマ機能拡張と呼ばれる、同様の拡張機能をサポートしています。Azure AD Graph API を作成して、ディレクトリ スキーマ拡張機能の定義を作成および管理する必要がある場合でも、Microsoft Graph API を使用して、これらの機能拡張プロパティの_データ_を追加、取得、更新、削除することができます。Azure AD supports a similar type of extension, known as directory schema extensions, on a few directoryObject resources. Although you have to use the Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use the Microsoft Graph API to add, get, update and delete data in the properties of these extensions.

アクセス許可Permissions

特定のリソース上の拡張機能データに対して読み書きするには、そのリソースに対して読み書きするときに必要となるのと同じアクセス許可が必要になります。The same permissions that are required to read from or write to a specific resource are also required to read from or write to any extensions data on that resource. たとえば、サインイン済みのユーザーのプロファイルをカスタム アプリ データで更新できるようにするには、アプリに User.ReadWrite.All アクセス許可を付与しておく必要があります。For example, for an app to be able to update the signed-in user's profile with custom app data, the app must have been granted the User.ReadWrite.All permission.

また、スキーマ拡張機能の定義を作成および管理できるようにするには、アプリケーションに Directory.AccessAsUser.All アクセス許可を付与しておく必要があります。Additionally, to create and manage schema extension definitions, an application must be granted the Directory.AccessAsUser.All permission.

データの上限Data limits

オープン拡張機能の上限Open extension limits

以下に示す上限がディレクトリ リソース (ユーザーグループデバイスなど) に適用されます。The following limits apply to directory resources (such as user, group, device):

  • オープン拡張機能のデータの上限は 2 KB (拡張機能の定義自体を含む) です。Each open extension can have up to 2 KB of data (including the extension definition itself).
  • アプリケーションでは、リソース インスタンスごとに最大 2 つのオープン拡張機能を追加できます。An application can add up to two open extensions per resource instance.

以下に示す上限が Outlook のリソース (メッセージイベント連絡先など) に適用されます。The following limits apply to Outlook resources (such as message, event, and contact):

スキーマの拡張機能の上限Schema extension limits

アプリケーションで作成できるスキーマ拡張機能の定義は最大 5 つです。An application may create no more than five schema extension definitions.

既知の制限Known limitations

拡張機能の使用に関する既知の制限については、既知の問題に関する記事の「拡張機能」セクションを参照してください。For known limitations using extensions, see the extensions section in the known issues article.

拡張機能の例Extension examples

関連項目See also