Расширения схемы каталогов | Общие понятия API Graph

Статья
21.10.2021

В этом разделе рассматриваются расширения каталогов в API Graph Azure AD, которые можно использовать для добавления свойств объектам каталогов без внешнего хранилища данных. Например, если бизнес-приложению организации требуется идентификатор Skype для каждого пользователя в каталоге, для регистрации нового свойства skypeId в объекте User каталога можно использовать API Graph, а затем записать значение в новое свойство для определенного пользователя. Это раздел поможет вам понять ограничения на расширения каталогов, узнать, как они регистрируются в каталоге, и посмотреть примеры их использования в API Graph.

Важно!

Для доступа к ресурсам 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.

Типы данных расширений

Расширения можно регистрировать только с помощью версии API Graph 1.5 или более поздней. Можно регистрировать следующие типы свойств.

Тип свойства	Примечания
Двоичные	Максимум 256 байтов.
Логическое значение
DateTime	Указывается в формате ISO 8601. Данные хранятся в формате UTC.
Целое число	32-разрядное значение.
LargeInteger	64-разрядное значение.
Строка	Максимум 256 символов.

Типы свойств, указанные выше, можно регистрировать в следующих объектах каталога.

[User (Пользователь)]
Группа
TenantDetail
[Устройство]
[Приложение]
ServicePrincipal

Понимание процесса регистрации расширения

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

Свойства расширения регистрируются в объекте Application в каталоге разработчика. После того, как пользователь или администратор соглашается с приложением в каталоге разработчика, это свойство добавляется в тип целевого каталога и сразу становится доступным в каталоге разработчика. Если пользователь или администратор другой организации предоставляет согласие многопользовательскому приложению, свойства расширения становятся сразу доступными в типе целевого каталога в каталоге другой организации.

Если организация соглашается предоставить приложению с зарегистрированными расширениями разрешения "только для чтения", свойства все равно станут доступными в каталоге другой организации. Кроме того, свойства расширения доступны в любом согласившемся приложении организации, а не только в приложении, в котором они зарегистрированы. Другие согласившиеся приложения в этой организации могут читать или записывать значения для нового свойства расширения, если у них достаточно разрешений.

При удалении приложения или разрешения в каталоге другой организации свойство расширения становится недоступным в объекте целевого каталога. Если расширение удаляется приложением, оно также становится недоступным в объекте целевого каталога. При добавлении дополнительных свойств расширения многопользовательским приложением после предоставления согласия эти свойства также станут сразу доступны в каталоге другой организации.

Примечание. Если значением свойства расширения является объект и это свойство становится недоступным в каталоге соответствующего объекта, это свойство продолжает учитываться в ограничении на 100 значений свойства расширения. Значение заданного свойства не будет учитываться только в том случае, если задать ему нулевое значение напрямую. Сделать это нельзя, если свойство расширения недоступно.

Пример сценария

Рассмотрим следующий сценарий. Litware — независимый поставщик программного обеспечения, который разработал приложение SaaS для использования другой организацией. Для этого приложения требуется свойство расширения skypeId в объекте User. Сначала Litware регистрирует приложение в собственном каталоге, а затем вызывает API Graph для регистрации свойства расширения в объекте Application, после чего свойство становится доступным в объектах User в каталоге Litware. Наконец, Litware делает приложение многопользовательским, чтобы его можно было использовать в других организациях.

Contoso хочет использовать приложение SaaS Litware, и пользователь или администратор Contoso предоставляет согласие на приложение. После этого приложение регистрируется в каталоге Contoso, а свойства расширения, зарегистрированные для приложения каталогом Litware, сразу становятся доступны в каталоге Contoso. Поскольку каталог Litware в приложении зарегистрировал свойство расширения skypeId для объекта User, это свойство становится доступным для объектов User в каталоге Contoso. Приложение Litware или другие согласившиеся приложения в каталоге Contoso получают доступ к новому свойству в соответствии с разрешениями, настроенными для этого приложения в каталоге Contoso. Это означает, что в соответствии с предоставленными им разрешениями приложения могут записывать значение свойства расширения для одного или нескольких пользователей в каталоге. Только пользователи, для которых было записано значение skypeId, вернут это свойство соответствующего объекта User. Ситуация сохранится, пока свойству skypeId не будет присвоено значение null. После этого объект User соответствующего пользователя перестанет возвращать это свойство.

Пример запросов REST для расширений каталогов

Следующий пример запросов показывает, как регистрировать, просматривать, записывать, читать, фильтровать и отменять регистрацию расширений в вашем каталоге. Замените заполнитель &ltapplicationObjectId&gt на идентификатор объекта зарегистрированного приложения. Это значение можно получить следующим образом:

Перейдите по адресу https://graphexplorer.cloudapp.net/, щелкните ссылку Войти в правом верхнем углу, а затем войдите с помощью учетных данных учетной записи администратора в каталоге вашей организации.
После входа щелкните URL-адрес в текстовом поле ресурса (рядом с кнопкой GET), выберите URL-адрес, который заканчивается на applications/, и нажмите кнопку GET или клавишу Enter.
Найдите в результатах нужную запись приложения и скопируйте ее значение objectId, аналогичное следующему: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

В этом разделе приводятся примеры запросов для следующих операций:

Регистрация расширения
Просмотр зарегистрированных расширений
Запись значения расширения
Удаление значения расширения
Чтение значения расширения
Фильтрация значения расширения
Отмена регистрации расширения

Полные примеры с использованием свойств расширения см. в следующих примерах Azure AD на Github:

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" и следующее сообщение: "Размер объекта превысил предельное значение". "Уменьшите число значений и повторите запрос".

Удаление значения расширения

Следующий пример запроса удаляет значение расширения, ранее назначенное для свойства расширения skypeId в объекте User с помощью установки значения 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 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"
}

Отмена регистрации расширения

Следующий пример запроса отменяет регистрацию свойства расширения путем выполнения операции 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 значений свойств расширения, API Graph выдаст ответ 403 Запрещено с кодом ошибки "Directory_ResourceSizeExceeded" и следующее сообщение: "Размер объекта превысил предельное значение". "Уменьшите число значений и повторите запрос".
Если разработчик отменяет регистрацию свойства расширения (удаляет его) из приложения, это свойство расширения мгновенно становится недоступным в каталоге разработчика, а также в каталогах, в отношении которых приложению было предоставлено согласие.
Если приложение удаляется из каталога разработчика, все свойства расширения, зарегистрированные для этого приложения, мгновенно становятся недоступными в каталоге разработчика, а также в каталогах, в отношении которых приложению было предоставлено согласие.
Если многопользовательскому приложению предоставляется согласие в каталоге, а затем регистрация приложения в этом каталоге отменяется (например, администратором на портале управления Azure), все свойства расширений, зарегистрированные для этого приложения, мгновенно становятся недоступными в каталоге.
Чтобы удалить значение свойства расширения из объекта каталога, необходимо присвоить этому свойству значение null. Если для объекта каталога задано значение свойства расширения и это свойство по какой-либо из указанных выше причин становится недоступным в каталоге, оно перестает отображаться в объекте такого каталога. При этом оно по-прежнему учитывается в ограничении на 100 значений свойств расширений для этого объекта. Пока доступность свойства расширения не будет восстановлена (например, в некоторых случаях при повторном предоставлении согласия), значение не станет доступным для чтения или записи.

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

Справочник по API Graph Azure AD