Controle de versão | Conceitos da API do Graph
Aplica-se a: API do Graph | Azure AD (Active Directory)
Este tópico resume as diferenças de versão entre as entidades e operações da API do Graph do Azure AD (Active Directory). Você deve especificar a versão de uma operação a ser usada, incluindo o parâmetro de cadeia de caracteres de consulta api-version em sua solicitação. As solicitações sem um parâmetro api-version serão descartadas e retornarão uma resposta (400) Solicitação incorreta. Se seu serviço chamar uma versão anterior de uma operação, você poderá escolher continuar chamando a versão anterior ou modificar seu código para chamar uma versão mais recente. As diferenças na funcionalidade entre versões são descritas na documentação para a entidade na qual você está realizando a chamada.
Importante
Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.
Começando com a versão 1.5 da API do Azure AD Graph, o valor do parâmetro api-version para versões de GA (Disponibilidade geral) é especificado como um valor numérico. A URL a seguir mostra como consultar os recursos de nível superior para o domínio de locatário contoso.com usando a API do Graph versão 1.5: https://graph.windows.net/contoso.com?api-version=1.5. Para versões anteriores da API do Graph, o valor do parâmetro api-version é especificado como uma cadeia de caracteres de data no seguinte formato: AAAA-MM-DD. A URL a seguir mostra como consultar os recursos de nível superior do mesmo locatário usando a versão 2013-11-08 da API do Graph: https://graph.windows.net/contoso.com?api-version=2013-11-08. Para recursos de visualização, o valor do parâmetro api-version é especificado usando a cadeia de caracteres "beta" da seguinte forma: https://graph.windows.net/contoso.com?api-version=beta.
Contrato de API, controle de versão e alterações interruptivas
Iremos incrementar o número de versão da API para quaisquer alterações interruptivas na API, a fim de proteger os aplicativos clientes. Podemos optar por incrementar a versão da API para alterações não interruptivas também (por exemplo, se formos adicionar alguns recursos novos muito grandes).
Portanto, o que constitui uma alteração interruptiva?
- Removendo ou renomeando APIs ou parâmetros de API
- Alterações no comportamento de uma API existente
- Alterações nos códigos de erro & contratos de falha
- Tudo o que violaria o Princípio da menor surpresa
Observação: o acréscimo de novos campos JSON às respostas não constitui uma alteração interruptiva. Para desenvolvedores que geram seus próprios proxies de cliente (como clientes do WCF) nossa orientação é que seus aplicativos clientes devem estar preparados para receber propriedades e tipos derivados não definidos previamente pelo serviço do Graph API. Embora a API do Graph ainda não seja compatível com o OData V4 no momento da redação deste artigo, ela ainda segue as diretrizes descritas na seção Model Versioning (Controle de versão do modelo) nas especificações do OData V4.
Quando incrementamos a versão principal da API (por exemplo, de 1.5 a 2.0), estamos sinalizando que todo o suporte para os clientes existentes que usam versões anteriores a 1.x ou versões anteriores será preterido e não haverá mais suporte após 12 meses. Consulte Microsoft Online Services Support Lifecycle Policy (Políticas do Ciclo de Vida do Suporte do Microsoft Online Services) para obter mais detalhes.
Versões com suporte
As versões a seguir foram liberadas para a Graph API.
Versão beta
Os recursos da API do Graph que estão em visualização no momento podem ser encontrados na seção Recursos de visualização nos Conceitos da API do Graph ou no Blog da equipe do Graph. Recursos beta requerem o parâmetro de cadeia de caracteres de consulta "api-version=beta". Quando a equipe do Graph API acreditar que um recurso de visualização está pronto para GA, iremos adicionar esse recurso à versão mais recente do GA (ou se ele constituir uma alteração interruptiva, isso resultaria em um novo número de versão incrementado). Não oferecemos nenhuma garantia de que um recurso de visualização será promovido a GA.
Para obter a versão beta, vamos tentar evitar quaisquer alterações interruptivas tanto quanto possível, mas não podemos garantir isso. Aplicativos clientes que usam a versão beta devem esperar alterações interruptivas de tempos em tempos. Consulte os Supplemental Terms of Use for Microsoft Azure Previews (Termos Complementares de Uso para Visualizações do Microsoft Azure).
Versão 1.6
Esta seção lista as alterações da API do Graph versão 1.6.
A API do Graph versão 1.6 apresenta as seguintes alterações de recursos:
Adicionado suporte para usuários de conta local do Azure Active Directory B2C. Isso envolve novas propriedades na entidade User e um novo tipo complexo SignInName para dar suporte entrada com conta local para locatários do Azure Active Directory B2C. Para obter mais informações sobre o Azure Active Directory B2C, consulte a Documentação de Azure Active Directory B2C.
Adicionado suporte para descoberta de serviço com a entidade ServiceEndpoint e a propriedade de navegação serviceEndpoints nas entidades Application e ServicePrincipal.
Adicionado suporte para comportamento de aplicativo personalizado que pode ser invocado pelo uso de serviços com os tipos AddIn e KeyValue e a propriedade addIns nas entidades Application e ServicePrincipal.
Adicionado suporte para autenticação sem senha com a entidade TrustedCAsForPasswordlessAuth, o tipo CertificateAuthorityInformation e a propriedade trustedCAsForPasswordlessAuth na entidade TenantDetail.
Adicionada a ação changePassword, que pode ser chamada para permitir que o usuário conectado altere sua senha.
Os Clientes Graph versões 2.1.x exigem a API do Graph versão 1.6. Clientes Graph versões 2.0.x exigem a API do Graph 1.5.
Alterações de entidade
| Entidade | Descrição da alteração |
|---|---|
| Application | Adicionada a propriedade addIns, que define o comportamento personalizado que um serviço consumidor pode usar para chamar um aplicativo em contextos específicos. Adicionada a propriedade de navegação serviceEndpoints, que contém a coleção de pontos de extremidade de serviço que estão disponíveis para descoberta. |
| LicenseDetail | Nova entidade que contém detalhes da licença de um usuário. |
| ServiceEndpoint | Nova entidade que contém informações de descoberta de serviço. |
| ServicePrincipal | Adicionada a propriedade addIns, que define o comportamento personalizado que um serviço consumidor pode usar para chamar um aplicativo em contextos específicos. Adicionada a propriedade de navegação serviceEndpoints, que contém a coleção de pontos de extremidade de serviço que estão disponíveis para descoberta. |
| SubscribedSku | Adicionada a propriedade appliesTo. |
| TenantDetail | Adicionada a propriedade trustedCAsForPasswordlessAuth, que contém o conjunto de autoridades de certificação usado para validar a cadeia confiável ao executar a autenticação sem senha. |
| TrustedCAsForPasswordlessAuth | Nova entidade que representa um conjunto de autoridades de certificação para validar a cadeia confiável ao executar a autenticação sem senha. |
| User | Adicionada a propriedade creationType, que é usada para indicar que o usuário é uma conta local. Adicionada a propriedade signInNames, que contém a coleção de nomes de entrada usados por um usuário de conta local para entrar em um locatário do Azure Active Directory B2C. Esta propriedade foi renomeada de alternativeSignInNamesInfo na versão beta. Adicionada a propriedade de navegação licenseDetails. |
Alterações de tipo complexo
| Tipo | Descrição da alteração |
|---|---|
| AddIn | Novo tipo usado para definir o comportamento personalizado que um serviço consumidor pode usar para chamar um aplicativo em contextos específicos. |
| CertificateAuthorityInformation | Novo tipo que representa uma autoridade de certificação usada para validar a cadeia confiável ao executar a autenticação sem senha. |
| KeyValue | Novo tipo que contém um par chave-valor que define um parâmetro que um serviço consumidor pode usar ou chamar em um aplicativo especificado em um AddIn. |
| ServicePlanInfo | Adicionada a propriedade appliesTo. Adicionada a propriedade provisioningStatus. |
| SignInName | Novo tipo usado para manter informações sobre um nome de entrada que pode ser usado por um usuário de conta local para entrar em um locatário do Azure Active Directory B2C. Esse tipo foi renomeado de LogonIdentifier na versão beta. |
Alterações de ação e função
| Função | Descrição da alteração |
|---|---|
| changePassword | Nova ação que pode ser chamada para permitir que o usuário conectado altere sua senha. |
Versão 1.5
Essa seção lista as alterações para a Graph API versão 1.5.
A versão da Graph API 1.5 apresenta as seguintes alterações de recurso:
O namespace do esquema da API do Graph mudou de Microsoft.WindowsAzure.ActiveDirectory para Microsoft.DirectoryServices. Isso afeta todas as entidades e tipos complexos expostos pela Graph API.
Foi adicionado suporte para extensões de esquema de diretório. Isso permite adicionar propriedades que são exigidas por seu aplicativo para objetos de diretório. As seguintes entidades dão suporte a extensões do esquema: User, Group, TenantDetail, Device, Application e ServicePrincipal. Para dar suporte a extensões de esquema de diretório: a entidade ExtensionProperty foi adicionada, a propriedade de navegação extensionProperties foi adicionada à entidade Application e uma nova função, getAvailableExtensionProperties, foi adicionada para retornar as propriedades de extensão registradas dos objetos de diretório com suporte. Para obter mais informações sobre como estender o esquema de diretório, consulte Directory schema extensions (Extensões de esquema de diretório).
A maneira na qual as permissões são representadas mudou e está mais estreitamente alinhada com os conceitos do OAuth 2.0, e também com o modo que as permissões são representadas em outros componentes do Azure. A entidade Permission foi removida e substituída pela entidade OAuth2PermissionGrant. Essa entidade representa os escopos de permissões OAuth 2.0 delegados que chegam a uma declaração de escopo do token de acesso OAuth 2.0. Além disso, a nova entidade AppRoleAssignment representa funções do aplicativo que podem ser atribuídas a usuários, grupos e entidades de serviço. Dois tipos complexos relacionados também foram adicionados: AppRole e OAuth2Permission. Essa alteração originou a necessidade de renomear algumas propriedades e adicionar outras às seguintes entidades: Application, Group, ServicePrincipal e User.
A entidade Role foi renomeada para DirectoryRole.
A entidade RoleTemplate foi renomeada para DirectoryRoleTemplate.
As tabelas a seguir listam as entidades, tipos complexos e funções que foram adicionados, alterados ou removidos dessa versão.
Alterações de entidade
| Entidade | Descrição da alteração |
|---|---|
| Application | Atualizada a propriedade appId de Edm.Guid para Edm.String. Adicionada a propriedade appRoles, que contém a coleção de funções de aplicativo que um aplicativo pode declarar. Essas funções podem ser atribuídas a usuários, grupos ou entidades de serviço. Adicionada a propriedade groupMembershipClaims, que é um bitmask que configura a declaração "groups" emitida em um token de acesso OAuth 2.0 ou do usuário que seu aplicativo espera. Os valores de bitmask são: 0: nenhum, 1: grupos de segurança e funções do Azure AD, 2: reservado e 4: reservado. Definição da bitmask para 7 obterá todos os grupos de segurança, grupos de distribuição e funções do AD do Azure ao qual o usuário conectado é membro. Adicionada a propriedade knownClientApplications, que contém uma lista de aplicativos cliente que estão vinculados ao aplicativo do recurso. Consentimento para qualquer um dos aplicativos cliente conhecidos resultará em consentimento implícito ao aplicativo de recurso por meio de uma caixa de diálogo de consentimento combinados (mostrando os escopos de permissão OAuth exigidos pelo cliente e pelo recurso). Adicionada a propriedade oauth2AllowImplicitFlow, que especifica se esse aplicativo Web pode solicitar tokens de fluxo implícito do OAuth2.0. O padrão é false. Adicionada a propriedade oauth2AllowUrlPathMatching, que especifica se, como parte das solicitações de token do OAuth 2.0, o Azure AD permitirá uma correspondência de caminho do URI de redirecionamento em relação aos replyUrls do aplicativo. O padrão é false. Adicionada a propriedade oauth2Permissions, que contém a coleção de escopos de permissões OAuth 2.0 que o aplicativo de API Web (recurso) expõe para aplicativos cliente. Os escopos de permissões podem ser concedidos a aplicativos cliente durante a autorização. Adicionada a propriedade oauth2RequiredPostResponse, que especifica se, como parte das solicitações de token do OAuth 2.0, o Azure AD permitirá solicitações POST em vez de solicitações GET. O padrão é false, o que especifica que somente solicitações GET serão permitidas. Adicionada a propriedade requiredResourceAccess, que especifica os recursos a que esse aplicativo requer acesso e o conjunto de escopos de permissões OAuth e funções de aplicativo de que ele precisa em cada um desses recursos. Essa configuração prévia de acesso aos recursos necessários conduz a experiência de consentimento do usuário final. Adicionada a propriedade de navegação extensionProperties, que contém as propriedades de extensão associadas ao aplicativo. |
| AppRoleAssignment | A nova entidade é usada para registrar quando um usuário ou grupo é atribuído a um aplicativo. Nesse caso, resultará em um bloco de aplicativo mostrando o painel de acesso de aplicativo do usuário. Essa entidade também pode ser usada para conceder acesso de outro aplicativo (modelado como uma entidade de serviço) a um aplicativo de recursos em uma função específica. |
| Contact | Adicionada a propriedade sipProxyAddress, que especifica o endereço do protocolo SIP VoIP do contato. |
| DirectoryObject | Adicionada a propriedade deletionTimestamp, que indica a hora em que um objeto de diretório foi excluído. Só se aplica aos objetos de diretório que podem ser restaurados. No momento, só há suporte para Application. |
| DirectoryRole | Renomeado de Role. Adicionada a propriedade roleTemplateId |
| DirectoryRoleTemplate | Renomeado de RoleTemplate. |
| ExtensionProperty | Nova entidade que permite que um aplicativo defina e use um conjunto de propriedades adicionais que pode ser adicionado aos objetos de diretório (usuários, grupos, detalhes do locatário, dispositivos, aplicativos e entidades de serviço) sem o aplicativo exigir um armazenamento de dados externo. |
| Group | Adicionada a propriedade onPremisesSecurityIdentifier, que contém o SID (identificador de segurança) local para o grupo que foi sincronizado do local para a nuvem. Adicionada a propriedade de navegação appRoleAssignments, que aponta para o conjunto de aplicativos (entidades de serviço) a que o grupo é atribuído. |
| OAuth2PermissionGrant | Nova entidade que especifica um escopo de permissão delegado para OAuth2.0. O escopo de permissão delegado OAuth pode ser solicitado por aplicativos clientes (por meio da coleção requiredResourceAccess) que chamam o aplicativo do recurso. Substitui a entidade Permission, que foi removida dessa versão. |
| Permission | Renomeada para OAuth2PermissionGrant. |
| Função | Renomeada para DirectoryRole. |
| RoleTemplate | Renomeado para DirectoryRoleTemplate. |
| ServicePrincipal | Adicionada a propriedade appDisplayName, que especifica o nome de exibição exposto pelo aplicativo associado. Adicionada a propriedade appRoleAssignmentRequired, que especifica se um AppRoleAssignment para um usuário ou grupo é necessário antes que o Azure AD emita um token de usuário ou de acesso para o aplicativo. Adicionada a propriedade appRoles, que contém as funções de aplicativo expostas pelo aplicativo associado. Para obter mais informações, consulte a definição da propriedade appRoles na entidade Application. Adicionada a propriedade oauth2Permissions, que contém as permissões de OAuth 2.0 expostas pelo aplicativo associado. Para obter mais informações, consulte a definição da propriedade oauth2Permisions na entidade Application. Adicionada a propriedade preferredTokenSigningKeyThumbprint. Reservado somente para uso interno. Não gravar ou caso contrário se basear nessa propriedade. Pode ser removido em versões futuras. Adicionada a propriedade de navegação appRoleAssignedTo, que aponta para o conjunto de aplicativos ao qual a entidade de serviço está atribuída. Adicionada a propriedade de navegação appRoleAssignments, que aponta para o conjunto de entidades (entidades de serviço, usuários e grupos) que são atribuídas a essa entidade de serviço. Adicionada a propriedade de navegação oauth2PermissionGrants, que aponta para o conjunto de concessões de representação de usuário associado a essa entidade de serviço. Removida a propriedade de navegação permissions |
| TenantDetail | Removida a propriedade tenantType. |
| User | Adicionada a propriedade onPremisesSecurityIdentifier, que contém o SID (identificador de segurança) local para o usuário que foi sincronizado do local para a nuvem. Adicionada a propriedade sipProxyAddress, que especifica o endereço do protocolo SIP VoIP do usuário. Adicionada a propriedade de navegação appRoleAssignments, que aponta para o conjunto de aplicativos (entidades de serviço) a que o usuário é atribuído. Adicionada a propriedade de navegação oauth2PermissionGrants, que aponta para o conjunto de concessões de representação de usuário OAuth 2.0 associado ao usuário. Removida a propriedade de navegação permissions. |
Alterações de tipo complexo
| Tipo | Descrição da alteração |
|---|---|
| AppRole | Novo tipo que especifica as funções de aplicativo que podem ser solicitadas por aplicativos cliente para chamar esse aplicativo ou que podem ser usadas para atribuir o aplicativo aos usuários ou grupos em uma das funções do aplicativo especificado. |
| OAuth2Permission | Novo tipo que representa um escopo de permissão OAuth 2.0. O escopo de permissão OAuth 2.0 especificado pode ser solicitado por aplicativos clientes (por meio da coleção requiredResourceAccess) que chamam esse aplicativo de recurso. |
| RequiredResourceAccess | Novo tipo que especifica o conjunto de escopos de permissão OAuth 2.0 e funções de aplicativo sob o recurso especificado ao qual este aplicativo requer acesso. |
| ResourceAccess | Novo tipo que representa uma permissão que esse aplicativo requer. |
Alterações de ação e função
| Função | Descrição da alteração |
|---|---|
| getAvailableExtensionProperties | Nova função que retorna a lista completa de propriedades de extensão que foram registradas em um diretório. Propriedades de extensão podem ser registradas para as seguintes entidades: User, Group, Device, TenantDetail, Application e ServicePrincipal. |
| getMemberObjects | Nova função que retorna todos os objetos Group e DirectoryRole de que um usuário, contato, grupo ou entidade de serviço é membro temporariamente. |
| getObjectsByObjectIds | Nova função que retorna os objetos de diretório especificados em uma lista de IDs de objeto. Você também pode especificar quais coleções de recursos (usuários, grupos etc.) devem ser pesquisadas especificando o parâmetro opcional types. |
| restore | Nova ação de serviço que permite que um aplicativo excluído seja restaurado. |
Versão 08-11-2013
Esta seção lista as alterações para a Graph API versão 2013-11-08.
As tabelas a seguir listam as entidades, tipos complexos e funções que foram adicionados, alterados ou removidos dessa versão.
Alterações de entidade
| Entidade | Descrição da alteração |
|---|---|
| Application | Adicionada a propriedade de navegação owners, que aponta para o conjunto de objetos de diretório que são proprietários do aplicativo. Os proprietários são um conjunto de usuários não administradores que têm permissão para modificar esse objeto. Herdado de DirectoryObject. |
| DeviceConfiguration | Nova entidade que representa a configuração de um dispositivo. |
| DirectoryObject | Adicionada a propriedade de navegação createdOnBehalfOf, que aponta para o objeto de diretório em nome do qual esse objeto foi criado. Adicionada a propriedade de navegação createdObjects, que aponta para o conjunto de objetos de diretório criados pelo objeto atual. Adicionada a propriedade de navegação owners, que aponta para o conjunto de objetos de diretório que são proprietários do objeto atual. Os proprietários são um conjunto de usuários não administradores que têm permissão para modificar esse objeto. Adicionada a propriedade de navegação ownedObjects, que aponta para o conjunto de objetos de diretório que são de propriedade do objeto atual. Importante: Entidades que derivam de DirectoryObject herdam suas propriedades e pode herdam suas propriedades de navegação. |
| Group | Adicionada a propriedade de navegação owners, que aponta para o conjunto de objetos de diretório que são proprietários do grupo. Os proprietários são um conjunto de usuários não administradores que têm permissão para modificar esse objeto. Herdado de DirectoryObject. |
| Função | Adicionada a propriedade de navegação ownedObjects, que aponta para o conjunto de objetos de diretório que são de propriedade da função. Herdado de DirectoryObject. A entidade Role foi renomeada para DirectoryRole começando na versão 1.5. Para obter mais informações sobre Role, consulte DirectoryRole. |
| ServicePrincipal | Adicionada a propriedade appOwnerTenantID. Adicionada a propriedade autheniticationPolicy. Reservado somente para uso interno. Não use. Removido na versão 1.5. Adicionada a propriedade de navegação createdObjects, que aponta para o conjunto de objetos de diretório criados pela entidade de serviço. Herdado de DirectoryObject. Adicionada a propriedade de navegação owners, que aponta para o conjunto de objetos de diretório que são proprietários da entidade de serviço. Os proprietários são um conjunto de usuários não administradores que têm permissão para modificar esse objeto. Herdado de DirectoryObject. Adicionada a propriedade de navegação ownedObjects, que aponta para o conjunto de objetos de diretório que são de propriedade da entidade de serviço. Herdado de DirectoryObject. |
| User | Adicionada a propriedade immutableId, que associa uma conta de usuário do Active Directory local ao seu objeto de usuário do Azure AD. Essa propriedade deve ser especificada ao criar uma nova conta de usuário no Graph se você estiver usando um domínio federado para a propriedade userPrincipalName (UPN) do usuário. Adicionada a propriedade userType, que é um valor de cadeia de caracteres que pode ser usado para classificar os tipos de usuário em seu diretório, como "Member" e "Guest". Adicionada a propriedade de navegação createdObjects, que aponta para o conjunto de objetos de diretório criados pelo usuário. Herdado de DirectoryObject. Adicionada a propriedade de navegação ownedObjects, que aponta para o conjunto de objetos de diretório que são de propriedade do usuário. Herdado de DirectoryObject. |
Alterações de tipo complexo
| Tipo | Descrição da alteração |
|---|---|
| ServicePrincipalAuthenticationPolicy | Reservado somente para uso interno. Não use. Removido na versão 1.5. |
Alterações de ação e função
| Função | Descrição da alteração |
|---|---|
| assignLicense | Nova ação de serviço que atualiza um usuário com uma lista de licenças para adicionar e/ou remover. |
Versão 05-04-2013
Essa é a versão base da Graph API.