Административные единицы (предварительная версия) | Основные понятия API Graph

Статья
21.10.2021

Область применения: API Graph Azure AD

Общие сведения и необходимые компоненты

Административная единица представляет собой концептуальный контейнер для объектов каталога пользователей и групп, который позволяет делегировать разрешения административным ролям в административной единице с более высокой степенью детализации (т. е. по отделам, регионам и т. д.). В этом разделе приводится описание объявленных свойств и свойств навигации, предоставляемых сущностью AdministrativeUnit, а также операций и функций, которые могут вызываться в ресурсе OData administrativeUnits.

Важно!

Для доступа к ресурсам Azure Active Directory мы настоятельно рекомендуем использовать Microsoft Graph вместо API Azure AD Graph.Теперь наши усилия сфокусированы на разработке Microsoft Graph; дальнейшее продвижение API Azure AD Graph мы не планируем.Есть очень мало сценариев, в которых по-прежнему можно использовать API Azure AD Graph. Дополнительные сведения об этом см. в записи блога в центре разработчиков Office, где сравниваются решения Microsoft Graph и Azure AD Graph.

Для использования предварительной версии административной единицы также требуется знакомство с конфигурацией приложений и проверкой подлинности Azure AD. Если вы не знакомы с понятиями, связанными с проверкой подлинности Azure AD и (или) процедурой проверки подлинности, необходимой для того, чтобы приложение могло получить доступ к клиенту, см. статью Сценарии проверки подлинности для Azure AD и, в частности, разделы Основы регистрации приложения в Azure AD и Интеграция приложений с Azure Active Directory.

Прежде чем переходить к следующим разделам, изучите основную статью API Graph Azure Active Directory на сайте Azure.com, а также перечисленные ниже статьи об API Graph, где вы найдете дополнительные важные и полезные сведения:

Управление версиями API Graph Azure AD

Важно. В настоящее время функция административной единицы доступна только в предварительной версии. Чтобы использовать функции предварительной версии, укажите для параметра строки запроса api-version значение beta, например https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta.

Вы можете создавать и использовать административные единицы, только если включите Azure Active Directory Premium. Дополнительные сведения см. в статье Начало работы с Azure Active Directory Premium.
Краткое руководство по API Graph Azure AD на Azure.com
Общие сведения об операциях API Graph
Поддерживаемые параметры запросов, фильтров и разбиения на страницы

Пространство имен и наследование

Пространство имен: Microsoft.DirectoryServices

Базовый тип: DirectoryObject

Свойства

Сущность AdministrativeUnit поддерживает следующие свойства:

Объявленные свойства

Имя	Тип	Create(POST)	Read(GET)	Update(PATCH)	Описание
description	Edm.String	Необязательно		Необязательно	Необязательное описание для административной единицы.
displayName	Edm.String	Обязательно	Фильтруемый	Необязательно	Отображаемое имя административной единицы.

Свойства навигации

Имя	Кратность "От"	Кому	Кратность "Кому"	Описание
члены	*	Пользователь или группа	*	Элементы, назначенные административной единицей. Это могут быть пользователи или группы. Наследуется от DirectoryObject.
scopedAdministrators	*	ScopedRoleMembership	*	Администраторы, назначенные заданной роли (ролям) в административной единице.

Примечание. Несмотря на то что сущность DirectoryObject поддерживает другие свойства навигации, включая memberOf, owners и ownedObjects, эти свойства недопустимы для административной единицы. При отправке запроса о любом из этих свойств возвращается ответ 400 — Ошибочный запрос с соответствующими сообщениями об ошибках.

Адресация

Адресация может затрагивать коллекцию административных единиц в каталоге, отдельную административную единицу или связанные ресурсы, доступные через поддерживаемые свойства навигации административной единицы. В примерах из таблицы для обращения используется домен клиента. Другие способы адресации клиента см. в статье Адресация сущностей и операций в API Graph.

Артефакт	Фрагмент URL-адреса	Пример
Набор ресурсов (все административные единицы)	/administrativeUnits	`https://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}. Чтобы получить сами объекты, на которые ссылается свойство навигации, а не ссылки на эти объекты, удалите сегмент $links из пути к ресурсу в URI. Для адресации административной единицы можно также использовать стандартные объекты каталога, заменив administrativeUnits в пути к ресурсу в URI на directoryObjects.

Более подробные сведения о запросе объектов каталогов см. в статьях Стандартные запросы Azure AD API Graph и Разностный запрос Azure AD API Graph.

Поддерживаемые операции — administrativeUnits

В этом разделе определяются операции, поддерживаемые в наборе ресурсов administrativeUnits. Как уже говорилось, для начала следует ознакомиться с разделами статьи Обзор и необходимые компоненты и разобраться в основах API Graph, которые относятся ко всем сущностям, таким как правильное форматирование URL-адресов, адресация сущностей и операций, управление версиями и многое другое.

Для каждой из указанных ниже операций:

Субъект, выполняющий операцию, должен принадлежать к роли администратора с разрешениями на изменение ресурсов administrativeUnits с помощью запросов PATCH, POST и DELETE, а также на чтение объектов с помощью запросов GET.
Заполнитель contoso.onmicrosoft.com следует заменять на домен вашего клиента Azure Active Directory, а {objectId} — на идентификатор типа ресурса, указанный в URL-адресе.
Каждый запрос должен включать заголовки HTTP-запроса, указанные в приведенной ниже таблице.

|Заголовок запроса|Описание| |---|---| |Авторизация|Обязательный параметр. Токен носителя, выданный службой Azure Active Directory. Дополнительные сведения см. в статье Сценарии проверки подлинности в Azure AD.| |Content-Type|Обязательный параметр. Тип носителя содержимого для текста запроса, например application/json.| |Content-Length|Обязательный параметр. Длина запроса в байтах.|
Первые четыре из перечисленных ниже операций используются для управления созданием, извлечением, обновлением и удалением сущностей AdministrativeUnit. В последующих операциях используются свойства навигации members и scopedAdministrators, предназначенные для управления соответственно элементами User/Group сущности AdminstrativeUnit и набором заданных администраторов (с помощью сущности ScopedRoleMembership), имеющих административный контроль над сущностью AdministrativeUnit.

Создать административную единицу

Используется для создания новой сущности AdministrativeUnit.

Метод HTTP	URI запроса
POST	`https://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."
}

Получение административных единиц

Используется для извлечения определенной сущности AdministrativeUnit с помощью {objectId}, подмножества сущностей с помощью фильтрации по свойству displayName (см. статью Поддерживаемые запросы, фильтры и операции разбиения на страницы в API Graph Azure AD) или списка всех доступных сущностей. Приведенные ниже примеры запросов и ответов демонстрируют запросы к определенной и ко всем административным единицам соответственно.

Метод HTTP	URI запроса
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`
GET	`https://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 запроса
PATCH	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

В тексте запроса указывается одно или оба свойства сущности AdministrativeUnit:

{ 
  "displayName":"Central Region Administrators"
}

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. Текст ответа не содержит ответ OData.

Удаление административной единицы

Используется для удаления сущности AdministrativeUnit, указанной с помощью параметра {objectId}.

Метод HTTP	URI запроса
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

Текста запроса нет.

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. Текст ответа не содержит ответ OData.

Операции, описанные ниже, реализуются с помощью свойства навигации members, которое позволяет управлять элементами пользователей или групп сущности AdminstrativeUnit. Как уже говорилось, сегмент ресурса $links позволяет обходить или изменять сопоставление (или связь) между двумя ресурсами, например между сущностью administrativeUnit и ресурсом User или Group.

Добавление элементов в административную единицу

Используется для добавления элементов ресурса user или group в сущность AdministrativeUnit.

Метод HTTP	URI запроса
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta`

В этом примере в тексте запроса указан URL-адрес элемента, который нужно добавить в сущность administrativeUnit (в данном случае это ресурс users). Указывать directoryObjects в сегменте типа ресурса вместо users нельзя, поскольку сущность User наследуется из сущности DirectoryObject. Это верно и при работе с сегментом ресурса groups.

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

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. Текст ответа не содержит ответ OData.

Получение элементов административной единицы

Используется для извлечения элементов ресурса user или group из сущности AdministrativeUnit. Обратите внимание на то, что элементы можно получить с помощью любой из указанных ниже операций GET. Первая из них возвращает URL-адреса элементов, а вторая — свойства этих элементов. В обоих случаях сегмент {memberObjectId} можно указывать вне зависимости от того, что вам нужно получить — определенный элемент или набор элементов.

Метод HTTP	URI запроса
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/members/{memberObjectId}?api-version=beta`

Текста запроса нет.

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. В первом примере показан текст ответа для операции с использованием сегмента $links, предназначенный для получения всех элементов (т. е. параметр {memberObjectId} не указан) и содержащий два типа ресурсов — User и Group. Во втором показан ответ для того же примера, но без сегмента $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     
      }
   ]
}

Удаление элементов из административной единицы

Используется для удаления элементов ресурса user или group из сущности administrativeGroup. Поскольку members — это многозначное свойство навигации, URL-адрес запроса должен содержать {objectId} элемента или ссылки для удаления.

Метод HTTP	URI запроса
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta`

Текста запроса нет.

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. Текст ответа не содержит ответ OData.

Для назначения административной единицы администраторы размещаются в роли, выделенной этой административной единице. Остальные операции в этом разделе реализуются с помощью свойства навигации scopedAdministrators, которое обеспечивает управление набором администраторов, имеющих административный контроль над сущностью AdministrativeUnit, с помощью выделенной роли.

Добавление администратора с выделенной ролью в административную единицу

Используется для добавления администратора в роль, которая будет выделена administrativeUnit, с помощью сущности ScopedRoleMembership и свойства навигации scopedAdministrators. В этом примере операция включает два действия:

Заполняет новый элемент ScopedRoleMembership (НЕ представляющий собой адресуемый ресурс OData), который устанавливает связь между сущностью AdministrativeUnit, выделенной административной единице ролью DirectoryRole и элементом user с правами администратора.
Устанавливает связь свойств навигации между сущностью AdministrativeUnit и новым элементом ScopedRoleMembership.

Метод HTTP	URI запроса
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta`

В теле запроса указываются следующие свойства сущности ScopedRoleMembership:

roleObjectId — objectId требуемой роли DirectoryRole. Примечание. В настоящее время допустимы только роли HelpDeskAdministrators и UserAccountAdministrator.
roleMemberInfo — структура, которая идентифицирует административного пользователя: objectId – objectId пользователя User с правами администратора.
objectId – objectId пользователя User с правами администратора.

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

{
   "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 запроса
GET	`https://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
         }
      }            
   ]
}

Удаление администратора с выделенной ролью из административной единицы

Используется для удаления ScopedRoleMembership из ресурса administrativeUnit, заданного с помощью сегмента {scopedRoleMemberId}.

Метод HTTP	URI запроса
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

Текста запроса нет.

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. Текст ответа не содержит ответ OData.

Поддерживаемые операции — пользователи и группы

В этом разделе описываются новые поддерживаемые операции с ресурсами users и groups, которые обеспечивают поддержку ресурсов administrativeUnit.

См. полную общедоступную документацию по сущностям User и Group и операциям с ресурсами users и groups.

Для каждой из указанных ниже операций:

Субъект, выполняющий операцию, должен иметь права на чтение объектов с помощью запросов GET.
Заполнитель contoso.onmicrosoft.com следует заменять на домен вашего клиента Azure Active Directory, а {objectId} — на идентификатор типа ресурса, указанный в URL-адресе.

Каждый запрос должен включать следующие заголовки HTTP-запроса:

Заголовок запроса	Описание
Авторизация	Обязательный параметр. Токен носителя, выданный службой Azure Active Directory. Дополнительные сведения см. в статье "Сценарии проверки подлинности в Azure AD".
Тип содержимого	Обязательный параметр. Тип носителя для содержимого текста запроса, например application/json.
Длина содержимого	Обязательный параметр. Длина запроса в байтах.

Получение административных единиц, в которые входит пользователь или группа

Функция предварительного просмотра позволяет получить членство в administrativeUnits для ресурсов users и groups, используя свойство навигации memberOf в сущности DirectoryObject. Укажите сегмент ресурса users, чтобы получить членство для ресурсов users, или groups, чтобы получить членство для ресурсов groups. Укажите сегмент ресурса $links, чтобы получить URL-адреса ресурсов, или опустите его, чтобы получить свойства.

Метод HTTP	URI запроса
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/memberOf?api-version=beta`

Текста запроса нет.

Определения кода ответа см. ниже, в разделе Ссылка на HTTP-ответ. В первом примере показан текст ответа для ресурса users с сегментом $links и членством в двух типах ресурсов: DirectoryRole и AdministrativeUnit. Во втором показан ответ для того же примера, но без сегмента $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"
      }    
   ]  
}

Получение административных единиц, в которых пользователь является администратором

Используется для получения ресурсов adminstrativeUnits, в которых пользователь является администратором, с помощью свойства навигации scopedAdministratorOf в сущности User. Можно использовать любую из указанных ниже операций GET. Первая извлекает URL-адрес ресурса, а вторая возвращает свойства.

Метод HTTP	URI запроса
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta`
GET	`https://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"
      }
   ]
}```

```json
{
   "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

В этом разделе описываются новые поддерживаемые операции с ресурсами directoryRoles, которые обеспечивают поддержку ресурсов administrativeUnits.

Дополнительные сведения о сущности DirectoryRole и соответствующих операциях*** см. в полной общедоступной документации.

Для каждой из указанных ниже операций:

Субъект, выполняющий операцию, должен иметь права на чтение объектов с помощью запросов GET.
Заполнитель contoso.onmicrosoft.com следует заменять на домен вашего клиента Azure Active Directory, а {objectId} — на идентификатор типа ресурса, указанный в URL-адресе.
Каждый запрос должен содержать следующие заголовки HTTP-запросов: Request HeaderDescriptionAuthorizationRequired. Токен носителя, выданный службой Azure Active Directory. Дополнительные сведения см. в статье "Сценарии проверки подлинности в Azure AD". .Content-TypeRequired. Тип носителя для содержимого текста запроса, например application/json. Content-LengthRequired. Длина запроса в байтах.

Заголовок запроса	Описание
Авторизация	Обязательный параметр. Токен носителя, выданный службой Azure Active Directory. Дополнительные сведения см. в статье "Сценарии проверки подлинности в Azure AD".
Content-Type	Обязательный параметр. Тип носителя содержимого для текста запроса, например application/json.
Content-Length	Обязательный параметр. Длина запроса в байтах.

Получение администраторов административной единицы, выделенных определенной роли

Для назначения административной единицы администраторы размещаются в роли, выделенной этой административной единице. Эта операция позволяет получать данные о членстве администратора в выделенной роли, такие как набор ресурсов scopedRoleMemberships. Обратите внимание на то, что допустим только {objectId} ролей HelpDeskAdministrators и UserAccountAdministrator. Кроме того, сегмент {scopedRoleMemberId} можно использовать или нет в зависимости от того, что вам нужно получить — определенный ресурс или все ресурсы scopedRoleMembership.

Метод HTTP	URI запроса
GET	`https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{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
      }
   ]
}

Ссылка на HTTP-ответ

Ниже приведен список возможных кодов HTTP-ответов:

Код состояния HTTP	Код ошибки OData	Описание
200/OK	н/д	Обычный ответ на успешный запрос. Текст ответа будет содержать данные, соответствующие фильтрам, которые заданы в параметрах запроса.
201/Создано	н/д	Обычный ответ на успешный запрос POST/create. Текст ответа будет содержать данные, содержащиеся в новом ресурсе.
204/Нет содержимого	н/д	Обычный ответ на успешный запрос PATCH/update, операцию DELETE с ресурсом или запрос POST к связанному ресурсу. Текст ответа не будет содержать ответ OData.
400/Ошибочный запрос	Request_BadRequest	Это общее сообщение об ошибке, связанной с недопустимым или отсутствующим заголовком, параметром или данными в теле запроса. Эта ошибка также возникает при попытке добавить связанный ресурс, который уже существует.
401/Ошибка проверки подлинности	AuthorizationError	Отображается, если пользователь не авторизован для доступа к содержимому. Дополнительные сведения о защите вызовов, а также получении и указании маркера безопасного доступа см. в основной статье о REST AD Graph.
404/Объект не найден	Request_ResourceNotFound	Отображается, если ресурса, к которому вы пытаетесь получить доступ, не существует.
405/Недопустимый метод	Request_BadRequest	Отображается, если вы пытаетесь выполнить операцию, предназначенную для определенного ресурса, указав неверный идентификатор ресурса в URL-адресе запроса.

Дополнительные ресурсы

Дополнительные сведения об управлении административными единицами с помощью PowerShell см. в статье Управление административными единицами в Azure AD — общедоступная предварительная версия.
Дополнительные сведения о примитивных типах данных OData, предоставляемых моделью EDM, см. в статье Модель данных сущности: примитивные типы данных.
Справочник по API Graph Azure AD

Поделиться через

Административные единицы (предварительная версия) | Основные понятия API Graph

Общие сведения и необходимые компоненты

Пространство имен и наследование

Свойства

Объявленные свойства

Свойства навигации

Адресация

Поддерживаемые операции — administrativeUnits

Создать административную единицу

Получение административных единиц

Обновление административной единицы

Удаление административной единицы

Добавление элементов в административную единицу

Получение элементов административной единицы

Удаление элементов из административной единицы

Добавление администратора с выделенной ролью в административную единицу

Получение администратора с выделенной ролью в административную единицу

Удаление администратора с выделенной ролью из административной единицы

Поддерживаемые операции — пользователи и группы

Получение административных единиц, в которые входит пользователь или группа

Получение административных единиц, в которых пользователь является администратором

Поддерживаемые операции — directoryRoles

Получение администраторов административной единицы, выделенных определенной роли

Ссылка на HTTP-ответ

Дополнительные ресурсы

Дополнительные ресурсы