Управление версиями | Основные понятия API Graph
В этом разделе обобщены различия между версиями сущностей и операций API Graph Azure Active Directory (AD). Используемую версию операции необходимо указывать путем включения в запрос параметра строки запроса api-version. Запросы без параметра api-version будут отклоняться с возвратом ответа (400) Неправильный запрос. Если ваша служба вызывает более старую версию операции, можно продолжать вызывать старую версию или изменить код для вызова более новой версии. Все различия в функциональных возможностях между версиями описаны в документации для сущности, на основе которой выполняется вызов.
Важно!
Для доступа к ресурсам 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 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 для поддержки входа в клиент Azure Active Directory B2C под локальной учетной записью. Дополнительные сведения об 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.
Изменения сущностей
| Сущность | Описание изменения |
|---|---|
| Application | Добавлено свойство addIns, определяющее настраиваемое поведение, которое служба-клиент может использовать для вызова приложения в конкретном контексте. Добавлено свойство навигации serviceEndpoints, которое содержит коллекцию конечных точек службы, доступных для обнаружения. |
| LicenseDetail | Новая сущность, содержащая сведения о лицензиях пользователя. |
| ServiceEndpoint | Новая сущность, содержащая сведения об обнаружении службы. |
| ServicePrincipal | Добавлено свойство addIns, определяющее настраиваемое поведение, которое служба-клиент может использовать для вызова приложения в конкретном контексте. Добавлено свойство навигации serviceEndpoints, которое содержит коллекцию конечных точек службы, доступных для обнаружения. |
| SubscribedSku | Добавлено свойство appliesTo. |
| TenantDetail | Добавлено свойство trustedCAsForPasswordlessAuth, содержащее набор центров сертификации, которые используются для проверки цепи доверия во время проверки подлинности без пароля. |
| TrustedCAsForPasswordlessAuth | Новая сущность, которая представляет набор центров сертификации для проверки цепи доверия во время проверки подлинности без пароля. |
| [User (Пользователь)] | Добавлено свойство creationType, которое позволяет указать, что пользователь является локальной учетной записью. Добавлено свойство signInNames, содержащее коллекцию имен входа, которые используются локальной учетной записью пользователя для входа в клиент Azure Active Directory B2C. Это свойство переименовано с имени alternativeSignInNamesInfo, которое использовалось в бета-версии. Добавлено свойство навигации licenseDetails. |
Изменения сложных типов
| Тип | Описание изменения |
|---|---|
| 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.
В следующих таблицах перечислены сущности, сложные типы и функции, которые были добавлены, изменены или удалены в этом выпуске.
Изменения сущностей
| Сущность | Описание изменения |
|---|---|
| Application | Обновлено свойство 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. |
Изменения сложных типов
| Тип | Описание изменения |
|---|---|
| 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. |
| [восстановление из копии] | Новое действие службы, которое позволяет восстановить удаленное приложение. |
Версия 2013-11-08
В этом разделе перечислены изменения для API Graph версии 2013-11-08.
В следующих таблицах перечислены сущности, сложные типы и функции, которые были добавлены, изменены или удалены в этом выпуске.
Изменения сущностей
| Сущность | Описание изменения |
|---|---|
| Application | Добавлено свойство навигации 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. |
Изменения сложных типов
| Тип | Описание изменения |
|---|---|
| ServicePrincipalAuthenticationPolicy | Зарезервировано для внутреннего использования. Не использовать. Удалено в версии 1.5. |
Изменения действий и функций
| Функция | Описание изменения |
|---|---|
| assignLicense | Новое действие службы, которое обновляет пользователя путем добавления или удаления списка лицензий. |
Версия 2013-04-05
Это базовая версия API Graph.