ディレクトリスキーマ拡張機能 | Graph API の概念

[アーティクル]
2021/10/21

このトピックでは、Azure AD Graph API のディレクトリ拡張機能について説明します。このディレクトリ拡張機能を使用すれば、外部データストアを必要とせずにディレクトリオブジェクトにプロパティを追加することができます。たとえば、組織に、ディレクトリ内のユーザーごとに Skype ID を必要とする基幹業務 (LOB) アプリケーションがある場合は、Graph API を使用することで、skypeId という名前の新しいプロパティをディレクトリの User オブジェクトに登録し、特定のユーザーのためにその新しいプロパティに値を書き込むことができます。このトピックでは、ディレクトリ拡張機能に関する制限事項およびディレクトリ内にディレクトリ拡張機能を登録する方法を分かりやすく説明し、Graph API でディレクトリ拡張機能を使用した例を紹介します。

重要

Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。

拡張機能のデータ型

拡張機能は、Graph API バージョン 1.5 またはそれ以降によってのみ登録可能です。以下のプロパティタイプを登録できます。

プロパティの型	解説
Binary	256 バイト (最大)。
ブール型
DateTime	ISO 8601 形式で指定する必要があります。 UTC 形式で格納されます。
整数	32 ビット値。
LargeInteger	64 ビット値。
文字列型	256 文字 (最大)。

上記のプロパティタイプは、ディレクトリ内の以下のオブジェクトに登録できます。

User
[グループ]
TenantDetail
[デバイス]
[アプリケーション]
ServicePrincipal

拡張機能の登録方法について

ディレクトリ内での拡張機能プロパティの登録方法、および Azure AD の承諾モデルがその登録に及ぼす影響について理解しておくことが重要です。 Azure AD でのアプリケーション承諾の詳細については、「Azure Active Directory とアプリケーションの統合」の「同意フレームワークの概要」を参照してください。

拡張機能プロパティは、開発者のディレクトリにある Application オブジェクトに登録されます。開発者ディレクトリでユーザーまたは管理者がアプリケーションを承諾すると、プロパティがターゲットディレクトリタイプに追加され、開発者ディレクトリですぐにアクセスできるようになります。マルチテナントアプリケーションの場合、別の組織内のユーザーまたは管理者によってアプリケーションが承諾されると、拡張機能プロパティは他の組織のディレクトリにあるターゲットディレクトリタイプですぐにアクセス可能になります。

拡張機能が登録されているアプリケーションについて、1 つの組織が「読み取り専用」権限を承諾すると、拡張機能プロパティはその他の組織のディレクトリでもアクセス可能になります。加えて、拡張機能プロパティには、それが登録されるアプリケーションに限らず、組織内の承諾された任意のアプリケーションからアクセス可能です。その組織内のその他の承諾されたアプリケーションも、十分な権限を持っていれば、新しい拡張機能プロパティの値の読み取りまたは書き込みを行うことができます。

その他の組織のディレクトリ内でアプリケーションまたは承諾が削除された場合は、ターゲットディレクトリオブジェクトで拡張機能プロパティがアクセス不可能になります。アプリケーションによって拡張機能が削除された場合、ターゲットディレクトリオブジェクトでアクセス不可能になります。承諾された後で、マルチテナントアプリケーションによって拡張機能プロパティが追加されると、すぐにこれらのプロパティにはその他の組織のディレクトリでアクセスできるようになります。

注: 拡張機能プロパティの値がオブジェクトで設定され、そのプロパティがそのオブジェクトのディレクトリでアクセス不可能になった場合、引き続き、そのオブジェクトの上限 (100 拡張機能プロパティ値) に対してプロパティがカウントされます。設定されたプロパティ値を考慮から外す唯一の方法は、明示的にそれを null に設定することです。拡張機能プロパティにアクセスできない場合、これは実行できません。

シナリオ例

次のシナリオを考えてみましょう。Litware は、他の組織が使用するための SaaS アプリケーションを開発した独立系ソフトウェアベンダー (ISV) です。このアプリケーションを使用するには、User オブジェクトに skypeId という名前の拡張機能プロパティが必要です。まず、Litware が独自のディレクトリ内にアプリケーションを登録します。次に拡張機能プロパティを Application オブジェクトに登録するために Graph API が呼び出されます。これにより、Litware のディレクトリにある User オブジェクトで拡張機能プロパティにアクセスできるようになります。最後に、Litware はアプリケーションのマルチテナントを有効にして、他の組織でアプリケーションを使用できるようにします。

Contoso では Litware の SaaS アプリケーションを使用する必要があるので、Contoso のユーザーまたは管理者がこのアプリケーションを承諾します。承諾に基づいて、アプリケーションは Contoso のディレクトリに登録され、Litware によりアプリケーションに登録された拡張機能プロパティが Contoso ディレクトリで利用可能になります。 User オブジェクトの skypeId 拡張機能プロパティはアプリケーションで Litware により登録されたため、プロパティは Contoso のディレクトリ内の User オブジェクトでアクセスできるようになります。これで、Contoso のディレクトリにある Litware のアプリケーションまたはその他の承諾されたアプリケーションは、Contoso のディレクトリでそのアプリケーションに対して設定されたアクセス許可に基づき、新しいプロパティにアクセスできます。つまり、そのアプリケーションは、そのアクセス許可に基づき、ディレクトリの 1 人または複数のユーザーに対してその拡張機能プロパティの値を書き込むことができます。 skypeId 値が書き込まれたユーザーのみがその User オブジェクトでそのプロパティを返します。これは skypeId プロパティが null に設定されるまでの動作であり、その後はそのユーザーの User オブジェクトはプロパティを返さなくなります。

ディレクトリ拡張機能に対する REST 要求の例

次の要求例では、ディレクトリ内で拡張機能を登録、表示、書き込み、読み取り、フィルター処理、および登録解除する方法を示します。 &ltapplicationObjectId&gt プレースホルダーを、登録されたアプリケーションのオブジェクト ID と置き換えます。この値は次の方法で取得できます。

https://graphexplorer.cloudapp.net/ に移動して、右上隅にある [サインイン] リンクをクリックし、組織のディレクトリで管理者アカウントの資格情報を使用してサインインします。
サインインしたら、(GET ボタンの隣にある) リソーステキストボックスの URL をクリックし、applications/ で終わる URL を選択して GET をクリックするか、Enter キーをクリックします。
結果の中から目的のアプリケーションエントリを見つけて、以下のように、その objectId 値をコピーします。"objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

このセクションでは、次の操作の要求例があります。

拡張機能の登録
登録された拡張機能の表示
拡張機能値の書き込み
拡張機能値の削除
拡張機能値の読み取り
拡張機能値のフィルター処理
拡張機能の登録解除

拡張機能プロパティを使用する完全なサンプルが必要な場合、Github の Azure AD サンプルの次のサンプルを参照してください。

WebApp-GraphAPI-DirectoryExtensions-PHP: 拡張機能を作成し、PHP で利用する方法を示します。
WebApp-GraphAPI-DirectoryExtensions-DotNet: AAD テナント組織図を表示し、すぐに拡張機能値を読み取ることを可能にします。

拡張機能の登録

以下の要求例では、extensionProperty が目的の Application オブジェクトに作成されます。

要求の形式

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

要求例

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

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

操作が正常に完了すると、状態コード HTTP 201 Created と、完全修飾の拡張機能プロパティ名が返されます。これらは、ターゲットタイプに値を書き込む場合に使用できます。

応答例

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

登録された拡張機能の表示

以下の要求例では、Application オブジェクトに登録されている拡張機能を取得します。

要求の形式

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

要求例

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

操作が正常に完了すると、状態コード HTTP 200 OK と、Application オブジェクトに登録されている各拡張機能プロパティに関するすべての情報が返されます。

応答例

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

拡張機能値の書き込み

以下の要求例では、*skypeId^ 拡張機能プロパティの拡張機能値が User オブジェクトに書き込まれます。

要求の形式

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

要求例

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

操作が正常に完了すると、状態コード HTTP 204 No Content が返されます。

応答例

HTTP/1.1 204 No Content

書き込み試行がオブジェクトの 100 の拡張機能値上限を超えると、HTTP 403 アクセス禁止応答、エラーコード "Directory_ResourceSizeExceeded"、メッセージ "The size of the object has exceeded its limit. Please reduce the number of values and retry your request (オブジェクトのサイズが上限を超えています。値の数値を減らし、要求を再試行してください。)" が返されます。

拡張機能値の削除

以下の要求例では、拡張機能値を NULL に設定することにより、User オブジェクト上の skypeId 拡張機能プロパティに設定されている拡張機能値を削除します。

要求の形式

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

要求例

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

操作が正常に完了すると、状態コード HTTP 204 No Content が返されます。

応答例

HTTP/1.1 204 No Content

拡張機能値の読み取り

以下の要求例では、ユーザーに対する簡単な GET 操作を実行します。これにより、標準的プロパティ値と新しい拡張機能プロパティ値が返されます。

要求の形式

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

要求例

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

操作が正常に完了すると、状態コード HTTP 200 OK と、新しい拡張機能プロパティ値が返されます (わかりやすくするために、ユーザープロパティの多くは応答例から削除しています)。

応答例

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

拡張機能値のフィルター処理

以下の要求例では、指定した拡張機能プロパティ値によってユーザーをフィルター処理します。

注: 拡張機能のプレフィックス検索は文字列検索の場合は 71 文字に、バイナリ拡張機能の場合は 207 バイトに制限されます。

要求の形式

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

要求例

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

操作が正常に完了すると、状態コード HTTP 200 OK と、結果的に生成されたユーザーオブジェクトが返されます。

応答例

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

拡張機能の登録解除

以下の要求例では、拡張機能オブジェクト ID に対して DELETE 操作を実行することにより、拡張機能プロパティを登録解除します。

要求の形式

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

要求例

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

操作が正常に完了すると、状態コード HTTP 204 No Content が返され、拡張機能プロパティがアプリケーションに対して登録解除されます。

応答例

HTTP/1.1 204 No Content

拡張機能の動作と制限事項

次の動作と制限事項がディレクトリの拡張機能プロパティに適用されます。

アプリケーションに登録された拡張機能プロパティは、ディレクトリのユーザーまたは管理者がアプリケーションに承諾したときに利用可能になります。
拡張機能プロパティがディレクトリで利用可能になると、承諾されたアプリケーションは、ディレクトリのそのアプリケーションのアクセス許可に基づき、そのプロパティが適用されるオブジェクトに対して、その拡張機能プロパティの値を読み書きできます。拡張機能プロパティが適用されるオブジェクトは targetObjects プロパティに指定されます。
最大 100 の拡張機能プロパティ値をディレクトリの特定のオブジェクトで書き込むことができます。たとえば、ディレクトリのユーザーに他の拡張機能プロパティ値が書き込まれていないと想定すると、あるアプリケーションがある拡張機能プロパティ値を user1 に書き込む場合、そのアプリケーションか、ディレクトリにあり、適切なアクセス許可を持つ別のアプリケーションが 99 の他の拡張機能プロパティ値を user1 に書き込むことができます。ただし、ディレクトリの他のユーザーも 100 の拡張機能プロパティ値を自分に書き込むことができます。
100 の拡張機能プロパティ値が既に設定されているオブジェクトで、あるアプリケーションが追加の拡張機能プロパティの値を設定しようとすると、Graph API は 403 アクセス禁止応答、エラーコード "Directory_ResourceSizeExceeded"、メッセージ "The size of the object has exceeded its limit. Please reduce the number of values and retry your request (オブジェクトのサイズが上限を超えています。値の数値を減らし、要求を再試行してください。)" が返されます。
開発者がアプリケーションから拡張機能プロパティを登録解除 (削除) すると、開発者ディレクトリとアプリケーションが承諾されているその他のディレクトリでその拡張機能プロパティはすぐにアクセス不可能になります。
アプリケーションが開発者ディレクトリから削除された場合、開発者ディレクトリとアプリケーションが承諾されているその他のディレクトリで、そのアプリケーションに登録されているすべての拡張機能プロパティがアクセス不可能になります。
ディレクトリでマルチテナントアプリケーションが承諾されているとき、そのアプリケーションが後に、たとえば、Azure 管理ポータルを利用する管理者によって、そのディレクトリから登録解除 (削除) された場合、すぐにそのアプリケーションで登録されているすべての拡張機能プロパティがそのディレクトリでアクセス不可能になります。
ディレクトリオブジェクトから削除するには、拡張機能プロパティ値を明示的に null に設定する必要があります。拡張機能プロパティ値がディレクトリオブジェクトで設定されているとき、上記のいずれかの理由により、ディレクトリでその拡張機能プロパティがアクセス不可能になった場合、そのディレクトリオブジェクトには拡張機能プロパティが表示されなくなります。ただし、そのオブジェクトの 100 の拡張機能プロパティ値の上限に対して引き続きカウントされます。アプリケーションが再度承諾されるなど、拡張機能プロパティの可用性が戻るまで、値の読み取りまたは書き込みが禁止されます。

その他のリソース

Azure AD Graph API リファレンス

ディレクトリ スキーマ拡張機能 | Graph API の概念

拡張機能のデータ型

拡張機能の登録方法について

シナリオ例

ディレクトリ拡張機能に対する REST 要求の例

拡張機能の登録

要求の形式

要求例

応答例

登録された拡張機能の表示

要求の形式

要求例

応答例

拡張機能値の書き込み

要求の形式

要求例

応答例

拡張機能値の削除

要求の形式

要求例

応答例

拡張機能値の読み取り

要求の形式

要求例

応答例

拡張機能値のフィルター処理

要求の形式

要求例

応答例

拡張機能の登録解除

要求の形式

要求例

応答例

拡張機能の動作と制限事項

その他のリソース

その他のリソース

ディレクトリスキーマ拡張機能 | Graph API の概念