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

[アーティクル]
07/19/2022

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

この記事では、Microsoft Graph がリソースの拡張をサポートする方法、カスタムプロパティの追加に使用できるオプション、およびそれらを使用するタイミングについて説明します。

重要

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

Microsoft Graph にカスタムプロパティを追加する理由

重要

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

ISV 開発者は、ユーザー リソースを拡張することによって、アプリを軽量に保ちながら、アプリ固有のユーザープロファイルデータを Microsoft Graph に格納することを決定する場合があります。
または、アプリの既存のユーザープロファイルストアを保持し、ユーザー リソースにアプリ固有の識別子を追加することもできます。
エンタープライズ開発者の場合、構築する社内アプリケーションは、組織の人事固有のデータに依存する可能性があります。 Microsoft Graph のカスタムプロパティにこのデータを格納することで、複数のアプリケーション内の統合を簡略化できます。

Microsoft Graph のカスタムプロパティオプション

Microsoft Graph では、カスタムプロパティを追加するための 4 種類の拡張機能が提供されます。

拡張属性のプロパティ
ディレクトリ (Azure AD) 拡張機能
スキーマ拡張機能
オープン拡張機能

拡張属性

Azure ADでは、ユーザーリソースとデバイスリソースに対して定義済みの名前を持つ 15 個のカスタムプロパティのセットが提供されます。これらのプロパティは、最初はオンプレミスの Active Directory (AD) と Microsoft Exchange で提供されたカスタム属性でした。ただし、オンプレミスの AD および Microsoft Exchange データを Microsoft Graph を通じて Azure AD に同期する以外にも使用できるようになりました。

開発者のエクスペリエンス

15 個の拡張属性は、それぞれ onPremisesExtensionAttributes プロパティと extensionAttributes プロパティを通じて、ユーザー または デバイス のリソースインスタンスに文字列値を格納するために使用することができます。値は、新しいリソースインスタンスを作成するとき、または既存のリソースインスタンスを更新するときに割り当てることができます。フィルター処理することもできます。

拡張属性のデータを追加または更新する

次の例は、extensionAttribute1 にデータを格納し、PATCH メソッドを使用した更新操作を通じて extensionAttribute12 から既存のデータを削除する方法を示しています。

PATCH https://graph.microsoft.com/v1.0/users/071cc716-8147-4397-a5ba-b2105951cc0b

{
    "onPremisesExtensionAttributes": {
        "extensionAttribute1": "skypeId.adeleVance",
        "extensionAttribute13": null
    }
}

要求は 204 No Content 応答オブジェクトを返します。

拡張属性 1 ~ 15 からデータを取得する

要求

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,onPremisesExtensionAttributes

応答

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,onPremisesExtensionAttributes)",
    "value": [
        {
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "displayName": "Adele Vance",
            "onPremisesExtensionAttributes": {
                "extensionAttribute1": "Contractor",
                "extensionAttribute2": "50",
                "extensionAttribute3": null,
                "extensionAttribute4": "1478354",
                "extensionAttribute5": "10239390",
                "extensionAttribute6": null,
                "extensionAttribute7": null,
                "extensionAttribute8": null,
                "extensionAttribute9": null,
                "extensionAttribute10": "11",
                "extensionAttribute11": null,
                "extensionAttribute12": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF47SPDLT)/cn=Recipients/cn=5ee781fc7egc7aa0b9394bddb44e7f04-Adele Vance",
                "extensionAttribute13": null,
                "extensionAttribute14": null,
                "extensionAttribute15": null
            }
        }
    ]
}

ディレクトリ (Azure AD) 拡張機能

ディレクトリ拡張機能は、ディレクトリオブジェクトに対して厳密に型指定され、検出可能でフィルター可能な拡張機能エクスペリエンスを開発者に提供します。

ディレクトリ拡張機能は、まず ExtensionProperty の作成操作を通じてアプリケーションに登録され、特定のディレクトリオブジェクトを明示的にターゲットにする必要があります。アプリケーションがユーザーまたは管理者によって同意されると、拡張機能のプロパティはテナントですぐにアクセスできるようになります。テナント内のすべての承認されたアプリケーションは、ターゲットディレクトリオブジェクトのインスタンスで定義されている拡張プロパティに関するデータの読み取りと書き込みを行うことができます。

ディレクトリ拡張機能のターゲットオブジェクトとして指定できるリソースの種類の一覧については、「アプリケーションの拡張機能の種類を選択する」を参照してください。

開発者のエクスペリエンス

ディレクトリ拡張機能の定義は、extensionProperty リソースとそれに関連するメソッドを使用して管理されます。データは、リソースインスタンスの管理に使用するのと同じ REST 要求を使用して管理されます。

ディレクトリ拡張機能の定義を作成する

リソースインスタンスにディレクトリ拡張機能を追加するには、まずディレクトリ拡張機能の定義を作成する必要があります。

要求

POST https://graph.microsoft.com/v1.0/applications/30a5435a-1871-485c-8c7b-65f69e287e7b/extensionProperties

{
    "name": "jobGroupTracker",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

応答

extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker という名前のディレクトリ拡張プロパティは、extension_{appId-without-hyphens}_{extensionProperty-name} という名前付け規則に従った拡張機能名で作成されます。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications('30a5435a-1871-485c-8c7b-65f69e287e7b')/extensionProperties/$entity",
    "id": "4e3dbc8f-ca32-41b4-825a-346215d7d20f",
    "deletedDateTime": null,
    "appDisplayName": "HR-sync-app",
    "dataType": "String",
    "isSyncedFromOnPremises": false,
    "name": "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker",
    "targetObjects": [
        "User"
    ]
}

ディレクトリ拡張プロパティをターゲットオブジェクトに追加する

ディレクトリ拡張定義を作成したら、それをターゲットオブジェクト型のインスタンスに追加することができます。ターゲットオブジェクトの新しいインスタンスを作成するとき、または既存のオブジェクトを更新するときに、ディレクトリ拡張プロパティにデータを格納できます。次の例は、新しいユーザーオブジェクトを作成するときに、ディレクトリ拡張プロパティにデータを格納する方法を示しています。

POST https://graph.microsoft.com/v1.0/users

{
    "accountEnabled": true,
    "displayName": "Adele Vance",
    "mailNickname": "AdeleV",
    "userPrincipalName": "AdeleV@contoso.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": false,
        "password": "xWwvJ]6NMw+bWH-d"
    },
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "JobGroupN"
}

要求は、201 Created 応答コードと、応答本文で user オブジェクトを返します。

ディレクトリ拡張プロパティを取得する

次の例は、ディレクトリ拡張プロパティと関連データがリソースインスタンスにどのように表示されるかを示しています。拡張プロパティは、beta エンドポイントを通じて既定で返されますが、v1.0 エンドポイントを通じた $select でのみ返されます。

要求

GET https://graph.microsoft.com/beta/users?$select=id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable)",
    "value": [
        {
            "id": "63384f56-42d2-4aa7-b1d6-b10c78f143a2",
            "displayName": "Adele Vance",
            "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "E4",
            "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable": true
        }
    ]
}

ディレクトリ拡張機能のプロパティを更新または削除する

リソースインスタンスのディレクトリ拡張プロパティの値を更新または削除するには、PATCH メソッドを使用します。拡張機能プロパティとそれに関連付けられている値をリソースインスタンスから削除するには、その値を null に設定します。

次の要求は、あるディレクトリ拡張プロパティの値を更新し、別の拡張プロパティを削除します。

PATCH https://graph.microsoft.com/v1.0/users/63384f56-42d2-4aa7-b1d6-b10c78f143a2

{
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable": null,
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "E4"
}

要求は、204 No Content 応答コードを返します。

スキーマ拡張機能

Microsoft Graph スキーマ拡張機能は、概念的にはディレクトリ拡張機能と似ています。最初に、スキーマ拡張機能の定義を作成します。次に、それを使用して、サポートされているリソースインスタンスを、厳密に型指定されたカスタムプロパティで拡張します。さらに、スキーマ拡張機能の状態を制御し、他のアプリで検出できるようにすることができます。

スキーマ拡張機能をサポートするリソースの種類の一覧については、「アプリケーションの拡張機能の種類を選択する」を参照してください。

開発者のエクスペリエンス

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

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

id は、拡張リソースインスタンスにデータを格納する複合型の名前になります。

スキーマ拡張機能が登録されると、関連付けられた所有者アプリケーションと同じテナント内のすべてのアプリケーション (InDevelopment 状態の場合) または任意のテナント内のすべてのアプリケーション (Available 状態の場合) で使用できます。ディレクトリ拡張機能と同様に、承認されたアプリには、ターゲットオブジェクトで定義されている拡張機能に関するデータの読み取りと書き込みを行う機能があります。

オープン拡張機能とは異なり、拡張リソースインスタンスのスキーマ拡張機能の定義とそのデータは、個別の API 操作セットとして管理します。拡張リソースインスタンスのスキーマ拡張データを管理するには、リソースインスタンスの管理に使用するのと同じ REST 要求を使用します。

スキーマ拡張機能の定義を作成する

要求

POST https://graph.microsoft.com/v1.0/schemaExtensions

{
    "id": "graphLearnCourses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "user"
    ],
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#schemaExtensions/$entity",
    "id": "extkmpdyld2_graphLearnCourses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "user"
    ],
    "status": "InDevelopment",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

リソースインスタンスにスキーマ拡張機能を追加する

スキーマ拡張機能の定義を作成したら、拡張プロパティをターゲットオブジェクト型のインスタンスに追加することができます。ターゲットオブジェクトの新しいインスタンスを作成するとき、または既存のオブジェクトを更新するときに、スキーマ拡張機能にデータを格納できます。次の例は、新しいユーザーオブジェクトを作成するときに、スキーマ拡張プロパティにデータを格納する方法を示しています。

POST https://graph.microsoft.com/beta/users/

{
    "accountEnabled": true,
    "displayName": "Adele Vance",
    "mailNickname": "AdeleV",
    "userPrincipalName": "AdeleV@m365x72712789.onmicrosoft.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": false,
        "password": "xWwvJ]6NMw+bWH-d"
    },
    "extkmpdyld2_graphLearnCourses": {
        "courseId": 100,
        "courseName": "Explore Microsoft Graph",
        "courseType": "Online"
    }
}

要求は、201 Created 応答コードと、応答本文で schemaExtension オブジェクトを返します

スキーマ拡張プロパティを更新または削除する

PATCH 操作を使用して、スキーマ拡張プロパティを更新するか、既存のスキーマ拡張オブジェクトを削除します。拡張機能プロパティとそれに関連付けられている値をリソースインスタンスから削除するには、その値を null に設定します。

次の例では、courseId プロパティの値を削除し、courseType プロパティを更新します。 extkmpdyld2_graphLearnCourses 拡張プロパティ全体を削除するには、その値を null に設定します。

PATCH https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e

{
    "extkmpdyld2_graphLearnCourses": {
        "courseType": "Instructor-led",
        "courseId": null
    }
}

要求は 204 No Content 応答オブジェクトを返します。

スキーマ拡張プロパティを取得する

リソースインスタンスのスキーマ拡張プロパティを読み取るには、$select 要求で拡張機能名を指定します。

要求

GET https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e?$select=id,displayName,extkmpdyld2_graphLearnCourses

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,extkmpdyld2_graphLearnCourses)/$entity",
    "id": "63384f56-42d2-4aa7-b1d6-b10c78f143a2",
    "displayName": "Adele Vance",
    "extkmpdyld2_graphLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Instructor-led",
        "courseName": "Explore Microsoft Graph",
        "courseId": null
    }
}

スキーマ拡張機能を使用してカスタムプロパティと関連データを追加する方法の詳細については、「schemaExtension リソースの種類」および「スキーマ拡張機能を使用してグループにカスタムプロパティを追加する」を参照してください。

オープン拡張機能

Microsoft Graph オープン拡張機能は、オープンタイプであり、型指定されていないデータを直接リソースインスタンスに追加するためのシンプルで柔軟な方法を提供します。これらの拡張機能は、厳密に型指定されたもの、検出可能、またはフィルター可能ではありません。

Microsoft Graph オープン拡張機能をサポートするリソースの種類の一覧については、「アプリケーションの拡張機能の種類を選択する」を参照してください。

開発者のエクスペリエンス

オープン拡張機能は、データとともに、リソースインスタンスの 拡張機能 ナビゲーションプロパティを通じてアクセスできます。これらを使用すると、関連するプロパティをグループ化して、アクセスと管理を容易にすることができます。

オープン拡張機能で 事前に定義される 書き込み可能なプロパティは、extensionName プロパティだけです。オープン拡張機能を作成する場合、extensionName プロパティにテナント内で一意の名前を割り当てる必要があります。これを行う方法の 1 つは、独自のドメイン に依存する逆引きドメインネームシステム (DNS) 形式 (例: Com.Contoso.ContactInfo) を使用することです。 拡張機能名に Microsoft ドメイン (Com.Microsoft または Com.OnMicrosoft) を使用しないでください。

オープン拡張機能を作成する

次の例は、3 つのプロパティを持つオープン拡張機能の定義と、カスタムプロパティと関連データがリソースインスタンスにどのように表示されるかを示しています。

POST https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions

{
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "extensionName": "com.contoso.socialSettings",
    "skypeId": "skypeId.AdeleV",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile",
    "xboxGamerTag": "AwesomeAdele",
    "id": "com.contoso.socialSettings"
}

要求は、201 Created 応答コードと、応答本文で openTypeExtension オブジェクトを返します。

既存のオープン拡張機能を更新する

オープン拡張機能を更新するには、要求本文ですべてのプロパティを指定する必要があります。それ以外の場合、未指定のプロパティは null に更新され、オープン拡張機能から削除されます。

次の要求では、linkedInProfile プロパティと xboxGamerTag プロパティのみを指定します。 linkedInProfile プロパティは同じままですが、xboxGamerTag プロパティの値は更新されています。この要求は、指定されていない skypeId プロパティも削除します。

PATCH https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions/com.contoso.socialSettings

{
    "xboxGamerTag": "FierceAdele",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile"
}

この要求は、204 No Content 応答コードを返します。

オープン拡張機能を取得する

GET https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions/com.contoso.socialSettings

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "xboxGamerTag": "FierceAdele",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile",
    "id": "com.contoso.socialSettings"
}

オープン拡張機能を使用してカスタムプロパティと関連データを追加する方法の詳細については、「openTypeExtension リソースの種類」および「オープン拡張機能を使用してユーザーにカスタムプロパティを追加する」を参照してください。

アプリケーションの拡張機能の種類を選択する

次の表は、拡張機能の種類を比較したものです。これは、シナリオに最も適したオプションを決定するのに役立ちます。

機能	拡張属性 1 ~ 15	ディレクトリ拡張機能	スキーマ拡張機能	オープン拡張機能
サポートされているリソースの種類	user device	user group administrativeUnit application device organization	user group administrativeUnit contact device event (ユーザー予定表とグループ予定表の両方) message organization post todoTask todoTaskList	user [グループ][] contact device event¹ (ユーザー予定表とグループ予定表の両方) message organization post
厳密に型指定されている	不要	はい	はい	不要
フィルター処理可能	はい	はい	はい	不要
以下を介して管理:	Microsoft Graph Exchange 管理センター	Microsoft Graph	Microsoft Graph	Microsoft Graph
[AD 接続][]を使用してオンプレミスから拡張機能にデータを同期する	はい (ユーザーの場合)	はい	いいえ	不要
カスタム拡張機能のプロパティとデータを使用して動的メンバーシップルールを作成する	○	はい	いいえ	不要
トークン要求のカスタマイズに使用できます	はい	はい	いいえ	不要
Azure AD B2Cで利用可能	はい	○	はい	はい
制限	ユーザーまたはデバイスリソースインスタンスごとに 15 個の定義済み属性	リソースインスタンスあたり 100 個の拡張機能の値	所有者アプリごとに最大 5 つの定義リソースインスタンスあたり 100 個の拡張機能の値 (ディレクトリオブジェクトのみ)	作成者アプリごと、リソースインスタンスごとに 2 個のオープン拡張機能 ² 最大オープン拡張機能ごとに 2 Kb ² Outlook リソースの場合、各オープン拡張機能は、MAPI 名前付きプロパティに格納されます ³

注意

¹ 既存のサービスの制限により、代理人は共有メールボックス予定表でオープン拡張追加イベントを作成することはできません。これを試みると、ErrorAccessDenied応答が返されます。

² これらのオープン拡張機能の制限は、次のディレクトリリソースに適用されます: user、group、device、 organization。

³ オープン拡張機能は、MAPI 名前付きプロパティに格納されます。これは、ユーザーのメールボックスの限られたリソースです。この制限は、次の Outlook リソースに適用されます: message、event、contact

職場または学校のアカウントでサインインした場合は、すべての拡張機能を管理できます。また、個人用 Microsoft アカウントでサインインすると、次のリソースのオープン拡張機能を管理できます: event、post、group、message、contact、user。

アクセス許可

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

既知の制限

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

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

Microsoft Graph にカスタム プロパティを追加する理由

Microsoft Graph のカスタム プロパティ オプション

拡張属性

開発者のエクスペリエンス

拡張属性のデータを追加または更新する

拡張属性 1 ~ 15 からデータを取得する

要求

応答

ディレクトリ (Azure AD) 拡張機能

開発者のエクスペリエンス

ディレクトリ拡張機能の定義を作成する

要求

応答

ディレクトリ拡張プロパティをターゲット オブジェクトに追加する

ディレクトリ拡張プロパティを取得する

要求

応答

ディレクトリ拡張機能のプロパティを更新または削除する

スキーマ拡張機能

開発者のエクスペリエンス

スキーマ拡張機能の定義を作成する

要求

応答

リソース インスタンスにスキーマ拡張機能を追加する

スキーマ拡張プロパティを更新または削除する

スキーマ拡張プロパティを取得する

要求

応答

オープン拡張機能

開発者のエクスペリエンス

オープン拡張機能を作成する

既存のオープン拡張機能を更新する

オープン拡張機能を取得する

アプリケーションの拡張機能の種類を選択する

アクセス許可

既知の制限

次の手順

フィードバック

Additional resources

Additional resources

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

Microsoft Graph にカスタムプロパティを追加する理由

Microsoft Graph のカスタムプロパティオプション

ディレクトリ拡張プロパティをターゲットオブジェクトに追加する

リソースインスタンスにスキーマ拡張機能を追加する