目錄結構描述擴充功能 | Graph API 概念

發行項
2021/10/21

本主題探討 Azure AD Graph API 中的目錄延伸模組，這些延伸模組可用於將屬性新增至目錄物件，而不需要外部資料存放區。例如，如果組織的企業營運 (LOB) 應用程式要求目錄中有每位使用者的 Skype 識別碼，則 Graph API 可用來在目錄的使用者物件上註冊名為 skypeId 的新屬性，然後將值寫入至特定使用者的新屬性。此主題會幫助您了解目錄擴充功能的限制、如何在目錄中進行註冊，以及提供在 Graph API 中使用的範例。

重要

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 Microsoft Graph，對於 Azure AD Graph API 則沒有進一步增強的計劃。Azure AD Graph API 仍適用於非常少數的案例；如需詳細資訊，請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。

擴充功能資料類型

只可以使用 Graph API 1.5 版或更新版本註冊擴充功能。可登錄的屬性類型如下：

屬性類型	備註
Binary	最多 256 個位元組。
布林值
日期時間	必須指定採用 ISO 8601 格式。會儲存在 UTC 中。
整數	32 位元值。
LargeInteger	64 位元值。
字串	最多 256 個字元。

在一個目錄的下列物件上可以登錄上述屬性類型：

了解擴充功能的註冊方式

請務必了解在目錄中登錄延伸模組屬性的方式，以及 Azure AD 的同意模型對於其登錄的影響。如需在 Azure AD 中應用程式同意的詳細資訊，請參閱整合應用程式與 Azure Active Directory 中同意架構的概觀。

擴充功能屬性會註冊在開發人員目錄中的 Application 物件上。在應用程式於開發人員目錄中獲得使用者或系統管理員的同意之後，該屬性將加入至目標目錄類型，並可立即在開發人員目錄中存取。若為多租用戶應用程式，當該應用程式獲得其他組織中使用者或系統管理員的同意，擴充功能屬性即可立即在其他組織目錄中的目標目錄類型上進行存取。

如果組織同意含已登錄延伸模組之應用程式的「唯讀」權限，則仍可在其他組織的目錄中存取屬性。此外，組織中任何已獲得同意的應用程式均可存取延伸模組屬性，而不僅限於已登錄的應用程式。該組織中其他獲得同意的應用程式若有足夠的權限，也可以讀取或寫入新延伸模組屬性的值。

如果在其他組織的目錄中，應用程式已遭刪除或同意已被移除，則該擴充功能屬性在目標目錄物件上會變成無法存取。如果擴充功能已遭應用程式刪除，則會同時在目標目錄物件上變成無法存取。如果多租用戶應用程式在獲得同意後新增其他擴充功能，這些屬性可立即在其他組織的目錄中進行存取。

注意︰如果在物件上設定擴充功能屬性的值，且該屬性在物件的目錄中變成無法存取的話，屬性仍算進該物件的 100 個擴充功能屬性值的限制之中。一旦設定屬性值後，移除的唯一方法是明確地將它設定為 Null。如果擴充功能屬性是無法存取的話，您就不能這麼做。

範例案例

請考量下列案例：Litware 是一家獨立軟體廠商 (ISV)，它開發了一個可供其他組織使用的 SaaS 應用程式，而此應用程式在使用者物件上需有名為 skypeId 的擴充功能屬性。 Litware 會先在自己的目錄中註冊此應用程式，然後會呼叫 Graph API 以在 Application 物件上註冊擴充功能屬性，該屬性即可在 Litware 之目錄中的使用者物件上進行存取。最後，Litware 會讓此應用程式具備多租用戶功能，以便用於其他組織中。

Contoso 想要使用 Litware 的 SaaS 應用程式，所以 Contoso 中的使用者或管理員會同意此應用程式。在同意時，於 Contoso 目錄中註冊的應用程式和由 Litware 註冊的擴充功能屬性，會立即在 Contoso 目錄中變為可用。由於使用者物件的 skypeId 擴充功能屬性已由 Litware 在應用程式上註冊，此屬性在 Contoso 目錄中的 User 物件會變成可存取。 Litware 的應用程式或 Contoso 目錄中其他已獲得同意的應用程式，現在可以根據該 Contoso 目錄中的應用程式設定的權限存取新的屬性。這表示該應用程式，可能會根據其權限，在目錄中的一個或多個使用者上寫入該擴充功能的屬性值。只有寫入 skypeId 值的使用者會傳回在其 User 物件上的屬性。這情形會持續到 skypeId 屬性設定為 Null 為止，之後該使用者的使用者物件將不會再傳回屬性。

目錄擴充功能的範例 REST 要求

下列範例要求示範如何在您的目錄中登錄、檢視、寫入、讀取、篩選和取消登錄延伸模組。使用已註冊應用程式的物件識別碼取代 &ltapplicationObjectId&gt 預留位置。您可以下列方式取得此值︰

移至 https://graphexplorer.cloudapp.net/，按一下右上角的 [登入] 連結，然後使用貴組織目錄的系統管理員帳戶認證登入。
在登入之後，請按一下 [資源] 文字方塊中的 URL (在 [GET](取得)按鈕旁)，並選取結尾為 applications/ 的 URL 然後按一下 [GET](取得)，或按一下 [輸入] 鍵。
從結果中尋找所需的應用程式項目，然後複製其 objectId 值，如下所示："objectId"："269fc2f7-6420-4ea4-be90-9e1f93a87a64"

在本節中，下列作業具有範例要求：

登錄延伸模組
檢視已登錄的延伸模組
寫入延伸模組值
移除延伸模組值
讀取延伸模組值
篩選延伸模組值
取消登錄延伸模組

如需使用擴充功能屬性的完整範例，請參閱 Github 上 Azure AD 範例中的下列範例︰

WebApp-GraphAPI-DirectoryExtensions-PHP︰示範如何搭配 PHP 建立及使用擴充功能。
WebApp-GraphAPI-DirectoryExtensions-DotNet︰顯示 AAD 租用戶組織圖，並允許讀取現成可用的擴充功能值。

註冊擴充功能

下列範例要求在想要的 Application 物件上建立 extensionProperty。

要求格式

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「已建立」狀態碼以及完整的延伸模組屬性名稱，而該屬性可用來將值寫入至目標類型。

範例回應

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「確定」狀態碼以及有關應用程式物件上每個已註冊擴充功能屬性的所有資訊。

範例回應

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"
            ]
        }
    ]
}

寫入擴充功能值

下列範例要求可為 User 物件上的 *skypeId^ 擴充功能屬性寫入擴充功能值。

要求格式

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「無內容」狀態碼。

範例回應

HTTP/1.1 204 No Content

如果嘗試寫入超過物件的擴充功能值上限為 100，則會傳回 HTTP 403 禁止回應，以及錯誤碼 “Directory_ResourceSizeExceeded” 和下列訊息：「物件的大小已超過其限制。請減少值的數目，然後重試您的要求」。

移除擴充功能值

下列範例要求可移除先前針對 User 物件上 skypeId 擴充功能屬性所設定的擴充功能值，其方法是將此值設定為 Null。

要求格式

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「無內容」狀態碼。

範例回應

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「確定」狀態碼以及新的延伸模組屬性值 (為求簡單明瞭，已從範例回應中移除許多使用者屬性)。

範例回應

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「確定」狀態碼以及所產生的使用者物件。

範例回應

HTTP/1.1 200 OK

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

取消註冊擴充功能

下列範例要求可對延伸模組物件識別碼執行 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「無內容」狀態碼，並且將在應用程式上取消登錄延伸模組屬性。

範例回應

HTTP/1.1 204 No Content

擴充功能的行為與限制

下列的行為與限制適用於目錄中的擴充功能屬性︰

當目錄使用者或系統管理員同意應用程式，為應用程式註冊的擴充功能屬性就可在目錄中使用。
擴充功能屬性在目錄中變成可用之後，任何已獲得同意的應用程式就可能會讀取或寫入針對任何物件的擴充功能屬性值，因此屬性會根據該應用程式在目錄中的的權限進行套用。 TargetObjects 屬性中會指定套用擴充功能屬性的物件。
在目錄中的特定物件上，可以寫入最多 100 個擴充功能屬性值。例如，假設在目錄中沒有將其他擴充功能屬性值寫入任何使用者中，如果應用程式將擴充功能屬性值寫入至 user1，那麼 99 個其他擴充功能屬性的值，可能會由該應用程式或在目錄中另一個具有適當權限應用程式寫入 user1。不過，在目錄中的其他使用者將仍然可以將高達 100 個的擴充功能屬性值寫入其中。
如果應用程式嘗試為物件上的其他擴充功能屬性設定值，但該擴充功能屬性已將擴充功能值設為 100 的話，Graph API 會傳回包含錯誤碼 “Directory_ResourceSizeExceeded” 的 403 禁止 回應，以及下列訊息：「物件的大小已超過其限制。請減少值的數目，然後重試您的要求」。
如果開發人員從應用程式取消註冊 (刪除) 擴充功能屬性時，則該擴充功能屬性在開發人員目錄及應用程式已獲得同意的目錄中會立即變成無法存取。
如果應用程式從開發人員目錄中移除，所有註冊至該應用程式的擴充功能屬性立即在開發人員目錄中變得無法存取，而在其它該應用程式獲得同意的目錄中也一樣。
如果多租用戶應用程式已在目錄中被授與同意，而該應用程式稍後從該目錄中取消註冊 (移除)，例如，由系統管理員使用 Azure 管理入口網站進行該動作，則目錄中在該應用程式上註冊的任何擴充功能屬性將立刻變得無法存取。
擴充功能屬性值必須明確設定為 Null 才能從目錄物件中移除。如果目錄物件上設定了擴充功能屬性值，且擴充功能屬性因上述原因而變成無法在目錄中存取的話，則擴充功能屬性將不再顯示在該目錄物件上。然而，它還是會算進該物件的 100 個擴充功能屬性值限制中。直到還原擴充功能屬性的可用性為止 (例如，在某些情況下再次同意應用程式)，該值將無法進行讀取或寫入。

其他資源

Azure AD Graph API 參考

共用方式為

目錄結構描述擴充功能 | Graph API 概念

擴充功能資料類型

了解擴充功能的註冊方式

範例案例

目錄擴充功能的範例 REST 要求

註冊擴充功能

要求格式

範例要求

範例回應

檢視已註冊的擴充功能

要求格式

範例要求

範例回應

寫入擴充功能值

要求格式

範例要求

範例回應

移除擴充功能值

要求格式

範例要求

範例回應

讀取擴充功能值

要求格式

範例要求

範例回應

篩選擴充功能值

要求格式

範例要求

範例回應

取消註冊擴充功能

要求格式

範例要求

範例回應

擴充功能的行為與限制

其他資源

其他資源