Table of contents
TOC
Свернуть оглавление
Развернуть оглавление

Управление версиями | Основные понятия API Graph

Bryan Lamos|Последнее обновление: 03.09.2016
|
1 Участник

Область применения: API Graph | Azure Active Directory (AD)

В этом разделе обобщены различия между версиями сущностей и операций API Graph Azure Active Directory (AD). Используемую версию операции необходимо указывать путем включения в запрос параметра строки запроса api-version. Запросы без параметра api-version будут отклоняться с возвратом ответа (400) Неправильный запрос. Если ваша служба вызывает более старую версию операции, можно продолжать вызывать старую версию или изменить код для вызова более новой версии. Все различия в функциональных возможностях между версиями описаны в документации для сущности, на основе которой выполняется вызов.

Важно

Доступ к функциональным возможностям API Graph Azure AD можно получить и через Microsoft Graph — универсальный API, который также включает API других служб Майкрософт, таких как Outlook, OneDrive, OneNote, Планировщик и Office Graph, и позволяет получать к ним доступ через единую конечную точку с маркером единого доступа.

Начиная с API Graph Azure AD версии 1.5, значение параметра api-version задается как числовое значение в общедоступной версии. Следующий URL-адрес показывает, как запросить ресурсы верхнего уровня для клиента домена contoso.com с помощью API Graph версии 1.5: https://graph.windows.net/contoso.com?api-version=1.5. Для предыдущих версий API Graph значение параметра api-version задается как строка даты в следующем формате: ГГГГ-ММ-ДД. Следующий URL-адрес показывает, как запросить ресурсы верхнего уровня того же клиента с помощью версии 2013-11-08 API Graph: https://graph.windows.net/contoso.com?api-version=2013-11-08. Для компонентов предварительной версии значение параметра api-version задается с помощью строки "бета" следующим образом: https://graph.windows.net/contoso.com?api-version=beta.

API-интерфейс контракта, управление версиями и критические изменения

Мы будем увеличивать номер версии API для любых критических изменений в API с целью защиты клиентских приложений. Может также потребоваться увеличить версию API для некритических изменений (например, при добавлении значительных новых возможностей).

Итак, что такое критические изменения?

  • Удаление или переименование API или их параметров
  • Изменения в поведении для существующих API
  • Изменения в кодах ошибок и контрактах ошибок
  • Все, что приведет к нарушению принципа наименьшего удивления

Примечание. Добавление новых полей JSON в ответы не является критическим изменением. Разработчикам, создающим собственные прокси клиентов (такие как клиенты WCF), следует подготовить клиентские приложения к получению свойств и производных типов, которые раньше не были определены службой API Graph. Несмотря на то, что API Graph еще не совместим с OData V4 на момент написания этой статьи, в нем учтены рекомендации, описанные в разделе Модель управления версиями в спецификации OData V4.

При увеличении номера основной версии API-интерфейса (например, с 1.5 до 2.0) мы информируем, что поддержка существующих клиентов, использующих предыдущие 1.x или более ранние версии, будет прекращена и больше не будет предоставляться через 12 месяцев. Подробнее см. раздел Политика поддержки жизненного цикла Microsoft Online Services.

Поддерживаемые версии

Для API Graph были выпущены следующие версии.

Бета-версия

Функции Graph API, представленные в предварительной версии, можно найти в любом разделе Предварительные версии функций общих понятий API Graph, а также в блоге команды разработчиков Graph. Бета-версии функций требуют параметр строки запроса "api-version=beta". Когда, по мнению команды разработчиков API Graph, компонент в предварительной версии будет готов для общедоступной версии, мы добавим этот компонент к последней общедоступной версии (или в случае критического изменения это приведет к увеличению номера новой версии). Мы не даем никаких гарантий на перенос компонента предварительной версии в общедоступную версию.

Для бета-версии мы постараемся по возможности избегать критических изменений, но не можем этого гарантировать. Клиентские приложения, использующие бета-версию, должны быть готовы к периодическим критическим изменениям. См. раздел Дополнительные условия использования предварительных версий Microsoft Azure.

Версия 1.6

В этом разделе перечислены изменения для API Graph версии 1.6.

В API Graph версии 1.6 появились следующие изменения функций:

  • Добавлена поддержка для пользователей локальных учетных записей Azure Active Directory B2C. Сюда входят новые свойства сущности User и новый сложный тип SignInName для поддержки входа в B2C-клиент Azure Active Directory по локальной учетной записи. Дополнительные сведения об Azure Active Directory B2C см. в документации по Azure Active Directory B2C.

  • Добавлена поддержка обнаружения служб с помощью сущности ServiceEndpoint и свойства навигации serviceEndpoints в сущностях Application и ServicePrincipal.

  • Добавлена поддержка настраиваемого поведения приложения, которое может вызываться путем использования служб с типами AddIn и KeyValue и свойством addIns в сущностях Application и ServicePrincipal.

  • Добавлена поддержка проверки подлинности без пароля с использованием сущности TrustedCAsForPasswordlessAuth, типа CertificateAuthorityInformation и свойства trustedCAsForPasswordlessAuth в сущности TenantDetail.

  • Добавлено действие changePassword, которое можно вызывать, чтобы пользователь, вошедший в приложение, мог сменить пароль.

  • Для клиента Graph версий 2.1.x требуется API Graph версии 1.6; для клиента Graph версий 2.0.x требуется API Graph 1.5.

Изменения сущностей

СущностьОписание изменения
[Приложение]Добавлено свойство addIns, определяющее настраиваемое поведение, которое служба-клиент может использовать для вызова приложения в конкретном контексте.

Добавлено свойство навигации serviceEndpoints, которое содержит коллекцию конечных точек службы, доступных для обнаружения.
LicenseDetailНовая сущность, содержащая сведения о лицензиях пользователя.
ServiceEndpointНовая сущность, содержащая сведения об обнаружении службы.
ServicePrincipalДобавлено свойство addIns, определяющее настраиваемое поведение, которое служба-клиент может использовать для вызова приложения в конкретном контексте.

Добавлено свойство навигации serviceEndpoints, которое содержит коллекцию конечных точек службы, доступных для обнаружения.
SubscribedSkuДобавлено свойство appliesTo.
TenantDetailДобавлено свойство trustedCAsForPasswordlessAuth, содержащее набор центров сертификации, которые используются для проверки цепи доверия во время проверки подлинности без пароля.
TrustedCAsForPasswordlessAuthНовая сущность, которая представляет набор центров сертификации для проверки цепи доверия во время проверки подлинности без пароля.
[User (Пользователь)]Добавлено свойство creationType, которое позволяет указать, что пользователь является локальной учетной записью.

Добавлено свойство signInNames, содержащее коллекцию имен входа, которые используются локальной учетной записью пользователя для входа в клиент Azure Active Directory B2C. Это свойство переименовано с имени alternativeSignInNamesInfo, которое использовалось в бета-версии.

Добавлено свойство навигации licenseDetails.

Изменения сложных типов

TypeОписание изменения
AddInНовый тип, применяемый для настройки поведения, которое служба-клиент может использовать для вызова приложения в определенном контексте.
CertificateAuthorityInformationНовый тип, которая представляет центр сертификации, используемый для проверки цепи доверия во время проверки подлинности без пароля.
KeyValueНовый тип, содержащий пару "ключ-значение", которая определяет, какой параметр служба-клиент может использовать или вызывать в приложении, указанном в AddIn.
ServicePlanInfoДобавлено свойство appliesTo.

Добавлено свойство provisioningStatus.
SignInNameНовый тип для хранения информации об имени входа, которое может использоваться локальной учетной записью пользователя для входа в клиент Azure Active Directory B2C. Этот тип переименован с имени LogonIdentifier, которое применялось в бета-версии.

Изменения действий и функций

ФункцияОписание изменения
changePasswordНовое действие, которое может вызываться, чтобы пользователь, выполнивший вход в приложение, мог сменить пароль.

Версия 1,5

В этом разделе перечислены изменения для API Graph версии 1.5.

В API Graph версии 1.5 появились следующие изменения функций.

  • Пространство имен в API Graph изменилось с Microsoft.WindowsAzure.ActiveDirectory на Microsoft.DirectoryServices. Это влияет на все сущности и сложные типы, предоставляемые API Graph.

  • Добавлена поддержка расширений схемы каталога. Это позволяет добавлять объектам каталога свойства, необходимые для приложения. Следующие сущности поддерживают расширения схемы: User, Group, TenantDetail, Device, Application и ServicePrincipal. Для поддержки расширений схемы каталогов: добавлены сущность ExtensionProperty, свойство навигации extensionProperties в сущности Application, а также новая функция getAvailableExtensionProperties для получения свойств зарегистрированных расширений в поддерживаемых объектах каталога. Дополнительные сведения о расширении схемы каталога см. в статье Расширения схемы каталогов.

  • Способ, которым представляются разрешения, был изменен, и теперь он более точно соответствует концепциям OAuth 2.0, как и способ, которым разрешения представляются в других компонентах Azure. Сущность Permission была удалена и заменена на сущность OAuth2PermissionGrant. Эта сущность представляет делегированные области разрешений OAuth 2.0, которые поступают в утверждениях scope токена доступа OAuth 2.0. Кроме того, новая сущность AppRoleAssignment представляет роли приложений, которые могут быть назначены субъектам, являющимся пользователями, группами и службами. Также были добавлены два связанных сложных типа: AppRole и OAuth2Permission. Это изменение стало причиной переименования одних свойств и добавления других в следующих сущностях: Application, Group, ServicePrincipal и User.

  • Сущность Role переименована в DirectoryRole.

  • Сущность RoleTemplate переименована в DirectoryRoleTemplate.

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

Изменения сущностей

СущностьОписание изменения
[Приложение]Обновлено свойство appId путем изменения типа Edm.Guid на Edm.String.

Добавлено свойство appRoles, содержащее коллекцию ролей приложения, которые приложение может объявлять. Эти роли могут назначаться пользователям, группам или субъектам-службам.

Добавлено свойство groupMembershipClaims. Это битовая маска, настраивающая утверждение "groups", выдаваемое в токене доступа OAuth 2.0, который ожидает приложение. Значения битовой маски: 0 — нет, 1 — группы безопасности и роли Azure AD, 2 — зарезервировано и 4 — зарезервировано. Значение битовой маски 7 позволяет получить все группы безопасности, группы рассылки и роли Azure AD, членом которых является выполнивший вход пользователь.

Добавлено свойство knownClientApplications, содержащее список клиентских приложений, которые связаны с этим ресурсным приложением. Согласие на любое из известных клиентских приложений приведет к неявному согласию на ресурсное приложение через диалоговое окно объединенного согласия (показывающее области разрешений OAuth, необходимые для клиента и ресурса).

Добавлено свойство oauth2AllowImplicitFlow, указывающее, может ли это веб-приложение запрашивать неявные токены потока OAuth2.0. Значение по умолчанию — false.

Добавлено свойство oauth2AllowUrlPathMatching, указывающее, будет ли Azure AD разрешать сопоставление пути URI перенаправления со значением replyUrls приложения в рамках запросов токена OAuth 2.0. Значение по умолчанию — false.

Добавлено свойство oauth2Permissions, содержащее коллекцию областей разрешений доступа OAuth 2.0, которые веб-API (ресурс) предоставляет клиентским приложениям. Эти области разрешений могут предоставляться клиентским приложениям во время согласия.

Добавлено свойство oauth2RequiredPostResponse, которое указывает, будет ли Azure AD в рамках запросов токенов OAuth 2.0 разрешать запросы POST помимо запросов GET. Значение по умолчанию — false. Это означает, что разрешены только запросы GET.

Добавлено свойство requiredResourceAccess, указывающее ресурсы, доступ к которым требует это приложение, и набор областей разрешений OAuth и ролей приложений, которые ему необходимы в каждом из этих ресурсов. Эту предварительную настройку доступа к необходимым ресурсам выполняет взаимодействие согласия с конечным пользователем.

Добавлено свойство навигации extensionProperties, содержащее свойства расширения, связанного с приложением.
AppRoleAssignmentНовая сущность, которая используется для записи, когда пользователю или группе назначается приложение. В данном случае в результате на пользовательской панели доступа к приложению появляется плитка приложения. Эта сущность также может использоваться для предоставления другому приложению (смоделированному как субъект-служба) доступа к ресурсному приложению в определенной роли.
КонтактДобавлено свойство sipProxyAddress, указывающее IP-адрес (VOIP) по протоколу SIP для контакта.
DirectoryObjectДобавлено свойство deletionTimestamp, указывающее время удаления объекта каталога. Оно применяется только для тех объектов каталога, которые могут быть восстановлены. Сейчас поддерживается только для Application.
DirectoryRoleПереименовано с имени Role.

Добавлено свойство roleTemplateId.
DirectoryRoleTemplateПереименовано с имени RoleTemplate.
ExtensionPropertyНовая сущность, позволяющая приложению задавать и использовать ряд дополнительных свойств, которые могут добавляться объектам каталога (пользователям, группам, сведениям о клиенте, устройствам, приложениям и субъектам-службам), без необходимости внешнего источника данных для приложения.
[Группа]Добавлено свойство onPremisesSecurityIdentifier, содержащее локальный идентификатор безопасности (SID) для группы, которая была синхронизирована из локальной среды в облако.

Добавлено свойство навигации appRoleAssignments, которое указывает на набор приложений (субъектов-служб), назначенных данной группе.
OAuth2PermissionGrantНовая сущность, которая указывает делегированную область разрешений OAuth 2.0. Указанная делегированная область разрешений OAuth может запрашиваться клиентскими приложениями (с помощью коллекции requiredResourceAccess), вызывающими это ресурсное приложение. Заменяет сущность Permission, удаленную из этой версии.
РазрешениеПереименовано в OAuth2PermissionGrant.
РольПереименована в DirectoryRole.
RoleTemplateПереименован в DirectoryRoleTemplate.
ServicePrincipalДобавлено свойство appDisplayName, которое задает отображаемое имя, предоставляемое связанным приложением.

Добавлено свойство appRoleAssignmentRequired, указывающее, нужно ли AppRoleAssignment пользователю или группе перед тем, как Azure AD будет выдавать приложению токен пользователя или доступа.

Добавлено свойство appRoles, содержащее роли приложений, предоставляемые связанным приложением. Дополнительные сведения см. в определении свойства appRoles сущности Application.

Добавлено свойство oauth2Permissions, содержащее разрешения OAuth 2.0, предоставляемые связанным приложением. Дополнительные сведения см. в определении свойства oauth2Permisions сущности Application.

Добавлено свойство preferredTokenSigningKeyThumbprint. Зарезервировано для внутреннего использования. Не записывайте это свойство и не используйте его иным образом. Может быть удалено в будущих версиях.

Добавлено свойство навигации appRoleAssignedTo, которое указывает на набор приложений, назначенных субъекту-службе.

Добавлено свойство навигации appRoleAssignments, которое указывает на набор субъектов (пользователей, групп и субъектов-служб), назначенных данному субъекту-службе.

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

Удалено свойство навигации permissions.
TenantDetailУдалено свойство tenantType.
[User (Пользователь)]Добавлено свойство onPremisesSecurityIdentifier, содержащее локальный идентификатор безопасности (SID) для пользователя, который был синхронизирован из локальной среды в облако.

Добавлено свойство sipProxyAddress, указывающее IP-адрес (VOIP) по протоколу SIP для пользователя.

Добавлено свойство навигации appRoleAssignments, которое указывает на набор приложений (субъектов-служб), назначенных данному пользователю.

Добавлено свойство навигации oauth2PermissionGrants, которое указывает на набор разрешений олицетворения пользователя OAuth 2.0, связанный с этим пользователем.

Удалено свойство навигации permissions.

Изменения сложных типов

TypeОписание изменения
AppRoleНовый тип, определяющий роли приложений, которые могут запрашиваться клиентскими приложениями, вызывающими это приложение, или использоваться для назначения приложения пользователям или группам в одной из указанных ролей приложений.
OAuth2PermissionНовый тип, представляющий область разрешений OAuth 2.0. Указанная делегированная область разрешений OAuth 2.0 может запрашиваться клиентскими приложениями (с помощью коллекции requiredResourceAccess), вызывающими это ресурсное приложение.
RequiredResourceAccessНовый тип, определяющий набор областей разрешений OAuth 2.0 и ролей приложений в рамках указанного ресурса, доступ к которому требует приложение.
ResourceAccessНовый тип, представляющий разрешение, которое требует приложение.

Изменения действий и функций

ФункцияОписание изменения
getAvailableExtensionPropertiesНовая функция, возвращающая полный список свойств расширений, которые были зарегистрированы в каталоге. Свойства расширения могут быть зарегистрированы для следующих сущностей: User, Group, Device, TenantDetail, Application и ServicePrincipal.
getMemberObjectsНовая функция, возвращающая все объекты Group и DirectoryRole, транзитивным членом которых является субъект, представляющий пользователя, контакт, группу или службу.
Функция getObjectsByObjectIdsНовая функция, возвращающая объекты каталога, указанные в списке идентификаторов объектов. Можно также указать, какие коллекции ресурсов (пользователей, групп и т. д.) нужно найти, задав необязательный параметр types.
восстановление из копииНовое действие службы, которое позволяет восстановить удаленное приложение.

Версия 08.11.2013

В этом разделе перечислены изменения для API Graph версии 2013-11-08.

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

Изменения сущностей

СущностьОписание изменения
[Приложение]Добавлено свойство навигации owners, которое указывает на набор объектов каталога, являющихся владельцами приложения. Владельцы — это набор не являющихся администраторами пользователей, которым разрешено изменять данный объект. Наследуется от DirectoryObject.
DeviceConfigurationНовая сущность, представляющая конфигурацию для устройства.
DirectoryObjectДобавлено свойство навигации createdOnBehalfOf, которое указывает на объект каталога, от имени которого был создан этот объект.

Добавлено свойство навигации createdObjects, которое указывает на набор объектов каталога, созданных текущим объектом.

Добавлено свойство навигации owners, которое указывает на набор объектов каталога, являющихся владельцами текущего объекта. Владельцы — это набор не являющихся администраторами пользователей, которым разрешено изменять данный объект.

Добавлено свойство навигации ownedObjects, которое указывает на набор объектов каталога, принадлежащих текущему объекту.

Внимание! Сущности, производные от DirectoryObject, наследуют его свойства, в том числе свойства навигации.
[Группа]Добавлено свойство навигации owners, которое указывает на набор объектов каталога, являющихся владельцами группы. Владельцы — это набор не являющихся администраторами пользователей, которым разрешено изменять данный объект. Наследуется от DirectoryObject.
РольДобавлено свойство навигации ownedObjects, которое указывает на набор объектов каталога, принадлежащих роли. Наследуется от DirectoryObject. Сущность Role переименована в DirectoryRole с версией 1.5. Дополнительные сведения о сущности Role см. в разделе DirectoryRole.
ServicePrincipalДобавлено свойство appOwnerTenantID.

Добавлено свойство autheniticationPolicy. Зарезервировано для внутреннего использования. Не используйте. Удалено в версии 1.5.

Добавлено свойство навигации createdObjects, которое указывает на набор объектов каталога, созданных субъектом-службой. Наследуется от DirectoryObject.

Добавлено свойство навигации owners, которое указывает на набор объектов каталога, являющихся владельцами субъекта-службы. Владельцы — это набор не являющихся администраторами пользователей, которым разрешено изменять данный объект. Наследуется от DirectoryObject.

Добавлено свойство навигации ownedObjects, которое указывает на набор объектов каталога, принадлежащих субъекту-службе. Наследуется от DirectoryObject.
[User (Пользователь)]Добавлено свойство immutableId, связывающее локальную учетную запись пользователя Active Directory с его объектом-пользователем Azure AD. Это свойство должно быть указано при создании новой учетной записи пользователя в Graph, если для свойства пользователя userPrincipalName (UPN) применяется федеративный домен.

Добавлено свойство userType, являющееся строковым значением, которое может использоваться для классификации типов пользователей в вашем каталоге, например "Член" и "Гость".

Добавлено свойство навигации createdObjects, которое указывает на набор объектов каталога, созданных пользователем. Наследуется от DirectoryObject.

Добавлено свойство навигации ownedObjects, которое указывает на набор объектов каталога, принадлежащих пользователю. Наследуется от DirectoryObject.

Изменения сложных типов

TypeОписание изменения
ServicePrincipalAuthenticationPolicyЗарезервировано для внутреннего использования. Не используйте. Удалено в версии 1.5.

Изменения действий и функций

ФункцияОписание изменения
assignLicenseНовое действие службы, которое обновляет пользователя путем добавления или удаления списка лицензий.

Версия 05.04.2013

Это базовая версия API Graph.

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

© 2017 Microsoft