Table of contents

管理單位 (預覽) | Graph API 概念

Bryan Lamos|上次更新日期: 2016/9/6
|
1 投稿人

適用對象: Graph API | Azure Active Directory (AD)

概觀和必要條件

管理單位為使用者和群組目錄物件提供了概念化的容器,以更精細的方式將權限委派給管理單位的系統管理角色 (即︰部門、區域等等)。 本主題說明 AdministrativeUnit 實體公開的宣告屬性和導覽屬性,以及 administrativeUnits OData 資源上可呼叫的作業和函數。

重要事項

您也可以透過 Microsoft Graph 取得 Azure AD Graph API 功能,這個統一 API 同時也包含如 Outlook、OneDrive、OneNote、Planner 和 Office Graph 等其他 Microsoft 服務 API,讓您可以使用單一的存取權杖透過單一端點存取所有 API。 請注意,Microsoft Graph 目前不支援管理單位,您必須使用 Azure AD Graph API 來取得這項功能。

使用管理單位預覽之前,必須先熟悉 Azure AD 驗證與應用程式組態。 如果您不熟悉與 Azure AD 驗證相關的概念,和/或為允許應用程式存取租用戶所需的組態步驟,請檢閱 Azure AD 的驗證案例,尤其是在 Azure AD 中註冊應用程式的基本概念一節,它會連結到有詳細內容的使用 Azure Active Directory 整合應用程式一文。

請參閱 Azure.com 上主要的 Azure Active Directory Graph API 一文和下列的 Graph API 文章清單,先取得重要且實用的資訊再繼續以下章節︰

  1. Azure AD Graph API 版本設定

    重要:目前只有預覽提供管理單位功能。 若要使用預覽版功能,必須將 api-version 查詢字串參數設為 "beta"。亦即︰ https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

    您您必須啟用 Azure Active Directory Premium,才能建立及使用系統管理單元。 如需詳細資訊,請參閱開始使用 Azure Active Directory Premium

  2. Azure.com 上的 Azure AD Graph API 快速入門

  3. Graph API 作業概觀

  4. 支援的查詢、篩選和分頁選項

命名空間和繼承

命名空間:Microsoft.DirectoryServices

基底類型DirectoryObject

屬性

AdministrativeUnit 實體支援下列屬性︰

宣告屬性

Name類型Create(POST)Read(GET)Update(PATCH)說明
描述Edm.String選用選用管理單位的選擇性描述。
displayNameEdm.String必要可篩選選用管理單位的顯示名稱。

導覽屬性

Name來源多重性收件者目標多重性說明
members*使用者或群組*指派給管理單位的成員,可以是使用者或群組。 繼承自 DirectoryObject。
scopedAdministrators*ScopedRoleMembership*指派給指定角色的管理員,其權限範圍為管理單位。

注意︰雖然 DirectoryObject 實體也支援其他導覽屬性 (包括 memberOfownersownedObjects),但這些屬性都不是有效的管理單位。 如果傳送對任一這些屬性的要求,就會傳回 400 要求錯誤回應和對應的錯誤訊息。

定址

定址可以跨越目錄中的管理單位集合、個別管理單位,或可透過支援的管理單位導覽屬性取得的相關資源。 表中的範例會使用租用戶網域來定址租用戶。 如需定址租用戶的其他方式,請參閱定址 Graph API 中的實體和作業

成品URL 片段範例
資源集 (所有的管理單位)/administrativeUnitshttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta
單一資源 (即︰一個管理位)/administrativeUnits/{objectId}https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta
透過導覽屬性的相關資源/administrativeUnits/{objectId}/$links/{property-name}https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta

注意︰請參閱前文<導覽屬性>一節來取得可用來代替 {property-name} 之導覽屬性的清單。 移除 URI 資源路徑部分的 "$links" 區段,傳回導覽屬性參考的實際物件,不傳回這些物件的連結。 您也可以使用泛型目錄物件處理管理單位,方法是用 URI 資源路徑部分的 "directoryObjects" 取代 "administrativeUnits"。

如需更完整的查詢目錄物件資訊,請參閱 Azure AD Graph API 常用查詢Azure AD Graph API 差異查詢

支援的作業 – administrativeUnits

這個區段會定義 administrativeUnits 資源集上支援的作業。 如先前所述,請務必先檢閱概觀和必要條件一節中的主題以了解一些適用於所有實體的 API 基本概念,例如正確格式化 URL、定址實體和作業、使用版本控制等等。

請針對下列每項作業︰

  • 執行作業的主體必須是管理員角色,有權使用 PATCH、POST 或 DELETE 要求來修改 administrativeUnits 資源,以及有權使用 GET 要求來讀取物件。

  • 如適用,請使用您的 Azure Active Directory 租用戶網域來取代預留位置字串 “contoso.onmicrosoft.com”,以及使用在 URL 中決定的資源類型識別碼來取代 {objectId},。

  • 每個要求都必須包含下表中的下列 HTTP 要求標頭。

要求標頭說明
授權必要。 由 Azure Active Directory 發出的承載權杖。 如需詳細資訊,請參閱 Azure AD 的驗證案例
Content-Type必要。 要求主體中內容的媒體類型,例如:application/json。
Content-Length必要。 要求的長度 (以位元組為單位)。


下面所列的前四項作業是用來管理建立、擷取、更新及刪除 AdministrativeUnit 實體。 其後的各項作業使用 membersscopedAdministrators 導覽屬性,分別管理 AdminstrativeUnit 的使用者/群組成員和一組已設定領域的管理員 (透過 ScopedRoleMembership 實體),後者擁有 AdministrativeUnit 的管理控制權。

建立管理單位

用以建立新的 AdministrativeUnit

HTTP 方法要求 URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

要求主體指定必要的 displayName 和選用的 description 屬性︰

{
  "displayName":"Central Region",
  "description":"Administrators responsible for the Central region."
}

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體看起來如下。

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

取得管理單位

用來依 {objectId} 擷取特定的 AdministrativeUnit,其為依 displayName 屬性篩選的子集 (請參閱 Supported Queries, Filters, and Paging Options in Azure AD Graph API (Azure AD Graph API 支援的查詢、篩選和分頁選項)),或所有可用項目的清單。 下面的要求/回應範例分別示範查詢特定的管理單位和所有的管理單位。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體看起來像下面項目之一。

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}
{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
      "deletionTimestamp":null,
      "displayName":"Central Region",
      "description":"Administrators responsible for the Central region."
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"455b7304-b245-4d58-95c4-1797c32c80db",
      "deletionTimestamp":null,
      "displayName":"East Coast Region",
      "description":"East Coast Two"
      }
   ]
}

更新管理單位

用以更新 AdministrativeUnit 中的一或多個屬性。

HTTP 方法要求 URI
PATCHhttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

要求主體可以指定其中一個 AdministrativeUnit 屬性,或兩個都指定︰

{ 
  "displayName":"Central Region Administrators"
}

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體中沒有 OData 回應。

刪除管理單位

用以刪除 AdministrativeUnit,如 {objectId} 所指定的。

HTTP 方法要求 URI
刪除https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體中沒有 OData 回應。

下列作業透過 members 導覽屬性實作,管理 AdminstrativeUnit 的使用者/群組成員。 如前文所述,$links 資源區段可讓您周遊或修改兩項資源 (例如 administrativeUnitUserGroup 資源) 之間的關聯性 (也稱為連結)。

在管理單位中加入成員

用以將使用者群組資源成員加入 AdministrativeUnit 中。

HTTP 方法要求 URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta

在本例中,要求主體指定我們想要加入 administrativeUnit 之所需成員的 URL,在這個範例中就是使用者資源。 因為 User 實體也是從 DirectoryObject 實體繼承而來,所以 directoryObjects 可取代 User 用為類型資源區段。 使用群組資源區段也是一樣。

{
  "url":" https://graph.windows.net/contoso.onmicrosoft.com/users/a1daa894-ff32-4839-bb6a-d7a4210fc96a"
}

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體中沒有 OData 回應。

取得管理單位的成員

用以擷取 AdministrativeUnit 中的使用者群組資源成員。 請注意,您可以使用下列 GET 作業的任一形式擷取成員。 第一個會傳回成員的 URL/連結,第二個會傳回成員的屬性。 兩種情況下,{memberObjectId} 區段都是選擇性的,取決於您想要傳回成員集合還是特定的成員。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/members/{memberObjectId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 下面第一個範例顯示使用所有成員的 $links 區段 (即不指定 {memberObjectId}) 的作業回應主體,其中有兩種資源類型:使用者群組。 第二個範例顯示相同範例不使用 $links 區段的回應。

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/members",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a1daa894-ff32-4839-bb6a-d7a4210fc96a/Microsoft.DirectoryServices.User"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a0ab9340-2b20-4b3f-8672-bf1a2f141f91/Microsoft.DirectoryServices.Group"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.User",
      "objectType":"User",
      "objectId":"a1daa894-ff32-4839-bb6a-d7a4210fc96a",
      "deletionTimestamp":null,
      "acceptedAs":null,
      "acceptedOn":null,
      "accountEnabled":true,
      "alternativeSecurityIds":[],
      "alternativeSignInNames":[admin@contoso.com],
      "alternativeSignInNamesInfo":[],
      "appMetadata":null,
      "assignedLicenses":[],
      "assignedPlans":[],
      "city":"Redmond",
      "cloudSecurityIdentifier":"S-1-12-6-2715461780-1211760434-2765580987-1791561505",
      "companyName":null,
      "country":null,
      "creationType":null,
      "department":null,
      "dirSyncEnabled":null,
      "displayName":"Jon Doe",
      "extensionAttribute1":null,
      "extensionAttribute2":null,
      "extensionAttribute3":null,
      "extensionAttribute4":null,
      "extensionAttribute5":null,
      "extensionAttribute6":null,
      "extensionAttribute7":null,
      "extensionAttribute8":null,
      "extensionAttribute9":null,
      "extensionAttribute10":null,
      "extensionAttribute11":null,
      "extensionAttribute12":null,
      "extensionAttribute13":null,
      "extensionAttribute14":null,
      "extensionAttribute15":null,
      "facsimileTelephoneNumber":null,
      "givenName":"Jon",
      "immutableId":null,
      "invitedOn":null,
      "inviteReplyUrl":[],
      "inviteResources":[],
      "inviteTicket":[],
      "isCompromised":null,
      "jobTitle":null,
      "jrnlProxyAddress":null,
      "lastDirSyncTime":null,
      "mail":null,
      "mailNickname":"admin",
      "mobile":null,
      "netId":"100300008001EE6E",
      "onPremisesSecurityIdentifier":null,
      "otherMails":[jon@doe.com],
      "passwordPolicies":null,
      "passwordProfile":null,
      "physicalDeliveryOfficeName":null,
      "postalCode":"98052",
      "preferredLanguage":"en-US",
      "primarySMTPAddress":null,
      "provisionedPlans":[],
      "provisioningErrors":[],
      "proxyAddresses":[],
      "releaseTrack":null,
      "searchableDeviceKey":[],
      "selfServePasswordResetData":null,
      "sipProxyAddress":null,
      "smtpAddresses":[],
      "state":"WA",
      "streetAddress":
      "One Microsoft Way",
      "surname":"Doe",
      "telephoneNumber":"(123) 456-7890",
      "usageLocation":"US",
      "userPrincipalName":admin@constoso.com,
      "userState":null,
      "userStateChangedOn":null,
      "userType":"Member"      
      },
      { 
      "odata.type":"Microsoft.DirectoryServices.Group",
      "objectType":"Group",
      "objectId":"a0ab9340-2b20-4b3f-8672-bf1a2f141f91",
      "deletionTimestamp":null,
      "appMetadata":null,
      "cloudSecurityIdentifier":"S-1-12-6-2695598912-1262431008-448754310-2434733103",
      "description":null,
      "dirSyncEnabled":null,
      "displayName":"Group for users in Central Region Administrative Unit",
      "exchangeResources":[],
      "groupType":null,
      "isPublic":null,
      "lastDirSyncTime":null,
      "licenseAssignment":[],
      "mail":null,
      "mailEnabled":false,
      "mailNickname":"CentralUsers",
      "onPremisesSecurityIdentifier":null,
      "provisioningErrors":[],
      "proxyAddresses":[],
      "securityEnabled":true,
      "sharepointResources":[],
      "targetAddress":null,
      "wellKnownObject":null     
      }
   ]
}

刪除管理單位的成員

用以刪除 AdministrativeUnit 資源的使用者群組資源成員。 因為 members 是多重值的導覽屬性,所以要求 URL 中必須包含您想要刪除之成員/連結的 {objectId}。

HTTP 方法要求 URI
刪除https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體中沒有 OData 回應。

將管理員指派給管理單位的方法是將他們放在該管理單位限定範圍的角色中。 本節中的其餘作業是透過 scopedAdministrators 導覽屬性實作,透過限定範圍的角色管理擁有 AdministrativeUnit 管理控制權的管理員集合。

在管理單位中加入限定範圍角色的管理員

透過 ScopedRoleMembership 實體和 scopedAdministrators 導覽屬性,用以將管理員加入範圍限定在 administrativeUnit 的角色中。 本例中的作業會做兩件事︰

  1. 填入新的 ScopedRoleMembership 項目 (這「不是」可定址的 OData 資源),建立 AdministrativeUnit、範圍限定在管理單位的 DirectoryRole,和管理員使用者之間的關聯性。

  2. 建立 AdministrativeUnit 和新 ScopedRoleMembership 項目間的導覽屬性關聯/連結。

HTTP 方法要求 URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta

要求主體指定來自 ScopedRoleMembership 實體的下列屬性︰

  • roleObjectId – 所需 DirectoryRole 的 objectId。 注意︰目前僅 HelpDeskAdministrators 和 UserAccountAdministrator 角色有效。

  • roleMemberInfo – 識別管理 User:objectId (管理使用者的 objectId) 的結構。

  • objectId - 管理使用者的 objectId。

{
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "roleMemberInfo":{
      "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f"}
}

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體看起來如下。

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
   "roleMemberInfo":{"objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
      "displayName":"Bryan",
      "userPrincipalName":BryanL@contoso.com
      }
}

取得管理單位的限定範圍角色管理員

用以取得 administrativeUnit 資源的限定範圍角色管理員清單作為 ScopedRoleMembership 實體。 請注意,{scopedRoleMemberId} 區段是選擇性的,取決於您想要成員集合還是特定的成員。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 下面的回應本體適合所有成員的查詢。

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }            
   ]
}

刪除管理單位的限定範圍角色管理員。

用以刪除 administrativeUnit 資源中 {scopedRoleMemberId} 區段所指定的 ScopedRoleMembership

HTTP 方法要求 URI
刪除https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 回應主體中沒有 OData 回應。

支援的作業 – 使用者和群組

這個區段會定義使用者群組資源最近支援的作業,它們支援 administrativeUnit 資源。

您可以查看 UserGroup 實體的完整 GA 文件,以及對使用者群組作業的完整 GA 文件。

請針對下列每項作業︰

  • 執行作業的主體必須具有使用 GET 要求讀取物件的權限。

  • 如適用,請使用您的 Azure Active Directory 租用戶網域來取代預留位置字串 “contoso.onmicrosoft.com”,以及使用在 URL 中決定的資源類型識別碼來取代 {objectId}。

  • 每個要求都必須包含下列 HTTP 要求標頭:

    要求標頭說明
    授權必要。 由 Azure Active Directory 發出的承載權杖。 如需詳細資訊,請參閱<Azure AD 的驗證案例>。
    Content-Type必要。 要求主體中內容的媒體類型,例如:application/json。
    Content-Length必要。 要求的長度 (以位元組為單位)。

取得使用者或群組所屬的管理單元

透過 DirectoryObject 實體的 memberOf 導覽屬性,預覽能夠擷取使用者群組資源的 administrativeUnits 成員資格 。 指定「使用者」資源區段,擷取使用者資源的成員資格,或群組資源的「群組」。 指定 “$links” 資源區段,擷取資源 URL/連結,或省略以擷取屬性。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/memberOf?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 下面第一個範例示範具有 $links 區段的使用者資源回應主體,它有兩種資源類型的成員資格:DirectoryRoleAdministrativeUnit。 第二個範例顯示相同範例不使用 $links 區段的回應。

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/memberOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/cbf54c29-6184-484d-92d6-d6af32f896a2/Microsoft.DirectoryServices.DirectoryRole"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/3cc09cfd-5423-4002-85b8-070d60a63fe2/Microsoft.DirectoryServices.AdministrativeUnit"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.DirectoryRole",
      "objectType":"Role",
      "objectId":"cbf54c29-6184-484d-92d6-d6af32f896a2",
      "deletionTimestamp":null,
      "cloudSecurityIdentifier":"S-1-12-6-3421850665-1213030788-2950092434-2727802930",
      "description":"Company Administrator role has full access to perform any operation in the company scope.",
      "displayName":"Company Administrator",
      "isSystem":true,
      "roleDisabled":false,
      "roleTemplateId":"62e90394-69f5-4237-9190-012177145e10"
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "deletionTimestamp":null,
      "displayName":"Central Region Administrators",
      "description":"Administrators responsible for the Central Region"
      }    
   ]  
}

取得使用者是管理員的管理單位

透過 User 實體的 scopedAdministratorOf 導覽屬性,用以擷取使用者是管理員的 adminstrativeUnits 資源。 請注意,您可以使用下列 GET 作業的任一形式。 第一種擷取資源 URL/連結,第二種傳回屬性。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/scopedAdministratorOf?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 下面第一個範例顯示使用 $links 區段的作業回應主體。 第二個範例顯示相同範例不使用 $links 區段的回應。

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/scopedAdministratorOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/scopedRoleMemberships/kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#scopedRoleMemberships",
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }
   ]  
}

支援的作業 - directoryRoles

這個區段會定義為 administrativeUnits 資源提供特定支援的 directoryRoles 資源最近支援的作業。

如需 DirectoryRole 實體與相關作業 **** 的詳細資訊,可查看完整的 GA 文件。

請針對下列每項作業︰

  • 執行作業的主體必須具有使用 GET 要求讀取物件的權限。

  • 如適用,請使用您的 Azure Active Directory 租用戶網域來取代預留位置字串 “contoso.onmicrosoft.com”,以及使用在 URL 中決定的資源類型識別碼來取代 {objectId}。

  • 每個要求都必須包含下列 HTTP 要求標頭:要求 HeaderDescriptionAuthorizationRequired。 由 Azure Active Directory 發出的承載權杖。 如需詳細資訊,請參閱<Azure AD 的驗證案例>。Content-TypeRequired。 要求主體中內容的媒體類型,例如:application/json.Content-LengthRequired。| 要求的長度 (以位元組為單位)。

要求標頭說明
授權必要。 由 Azure Active Directory 發出的承載權杖。 如需詳細資訊,請參閱<Azure AD 的驗證案例>。
Content-Type必要。 要求主體中內容的媒體類型,例如:application/json。
Content-Length必要。 要求的長度 (以位元組為單位)。

取得範圍限定為特定角色的管理單位管理員

將管理員指派給管理單位的方法是將他們放在該管理單位限定範圍的角色中。 這項作業可讓您擷取管理員的這些「範圍限定角色成員資格」,當成一組 scopedRoleMemberships 資源。 請注意,僅 “HelpDeskAdministrators” 或 “UserAccountAdministrator” 角色 {objectId} 有效。 另請注意,{scopedRoleMemberId} 區段是選擇性的,取決於您想要特定角色的所有 scopedRoleMembership 資源還是特定的某項資源。

HTTP 方法要求 URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

沒有要求主體。

如需回應程式碼定義,請參閱以下的 HTTP 回應參考一節。 下面的回應主體適合特定管理單位的所有管理員查詢,範圍限定在 Helpdesk Administrator 角色。

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":[
   {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
      {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
      }
   ]
}

HTTP 回應參考

以下是可能的 HTTP 回應碼清單︰

HTTP 狀態碼OData 錯誤碼說明
200/確定n/a成功查詢的正常回應。 回應主體會包含符合查詢參數指定篩選器的資料。
201/已建立n/a成功的 POST/建立作業的正常回應。 回應主體會包含和新資源填入資料一樣的資料。
204/沒有內容n/a成功的資源 PATCH/更新或 DELETE 作業或連結資源 POST 的正常回應。 回應主體不包含 OData 回應。
400/不正確的要求Request_BadRequest這是無效或遺漏標頭、參數或要求主體資料的一般錯誤訊息。 如果嘗試加入已經存在的連結資源,也會看到這個錯誤。
401/未經授權AuthorizationError當使用者未獲授權檢視內容時,就會顯示這個錯誤。 如需保護呼叫以及取得和指定安全存取權杖的其他詳細資訊,請參閱主要的 AD Graph REST 文章。
404/找不到Request_ResourceNotFound當您嘗試存取的資源不存在時,就會顯示這個錯誤。
405/不允許方法Request_BadRequest當您嘗試專門針對特定資源的作業,但要求 URL 中未提供正確的資源識別碼時,就會顯示這個錯誤。

其他資源

© 2017 Microsoft