Controlo de versões | Conceitos da Graph API
Aplica-se a: Graph API | Azure Active Directory (AD)
Este tópico resume as diferenças de versão para entidades da Graph API do Azure Active Directory (AD) e as operações. Tem de especificar a versão de uma operação que pretende utilizar, incluindo o api-version parâmetro de cadeia no seu pedido de consulta. Pedidos sem um api-version parâmetro será rejeitado e devolver um (400) incorretos pedem resposta. Se o serviço de uma versão anterior de uma operação, pode optar por continuar a chamar a versão mais antiga ou modificar o código para chamar uma versão mais recente. Todas as diferenças de funcionalidade entre versões são indicadas na documentação para a entidade no qual está a efetuar a chamada.
Importante
Recomendamos vivamente que utilize Microsoft Graph em vez do AD Graph API do Azure para aceder aos recursos do Azure Active Directory. A nossa esforços de desenvolvimento são agora concentrated no Microsoft Graph e estão a ser planeados sem melhoramentos adicionais para AD Graph API do Azure. Existem um número muito limitado de cenários para o qual AD Graph API do Azure ainda poderá ser apropriado; Para obter mais informações, consulte o Microsoft Graph ou o Azure AD Graph blogue no Dev Center do Office.
Começando com o Azure AD Graph API versão 1.5, o api-version valor do parâmetro para versões de disponibilidade geral (DG) está especificado como um valor numérico. O URL seguinte mostra como consultar os recursos de nível superior para o inquilino domínio contoso.com ao utilizar a Graph API versão 1.5: https://graph.windows.net/contoso.com?api-version=1.5. Para versões anteriores do Graph API, o api-version valor do parâmetro for especificado como uma cadeia de data no seguinte formato: aaaa-MM-DD. O URL seguinte mostra como consultar os recursos de nível superior do mesmo inquilino com a versão de 2013-11-08 da Graph API: https://graph.windows.net/contoso.com?api-version=2013-11-08. Para funcionalidades de pré-visualização, o api-version valor do parâmetro for especificado utilizando a cadeia "beta" da seguinte forma: https://graph.windows.net/contoso.com?api-version=beta.
Contrato de API, controlo de versões e alterações de última hora
Iremos irá incrementar o número de versão de API para quaisquer alterações à API, para proteger as aplicações cliente. Iremos podem optar por aumentar a versão da API para alterações de sem quebra demasiado (por exemplo, se adicionamos alguns significativamente grandes novas capacidades).
Por isso, o que constitui uma alteração inovadora?
- Remover ou mudar o nome de parâmetros APIs ou a API
- Alterações ao comportamento de uma API existente
- Alterações de códigos de erro & contratos de falhas
- Tudo o que seria viola o princípio de menos Astonishment
Tenha em atenção: A adição de novos campos JSON para respostas não constituem uma alteração inovadora. Para programadores que geram as suas próprias proxies de cliente (como clientes do WCF) a nossa documentação de orientação é que as aplicações de cliente devem estar preparadas para receber as propriedades e os tipos derivados não anteriormente definidos pelo serviço Graph API. Embora a Graph API ainda não é compatível com o momento desta redação de OData V4, ainda segue as instruções descritas no secção de controlo de versões do modelo na especificação do OData V4.
Quando é incrementar a versão principal da API (por exemplo a partir de 1.5 para 2.0), iremos são sinalização que todos os suporte para os clientes existentes anteriores 1. x ou versões anteriores a utilizar será preterido e já não é suportado depois de 12 meses. Consulte o política de ciclo de vida de suporte do Microsoft Online Services para obter mais detalhes.
Versões suportadas
As versões seguintes foram lançadas para a Graph API.
Beta de versão
As funcionalidades da Graph API atualmente em pré-visualização podem ser encontradas no funcionalidades de pré-visualização secção no conceitos Graph API ou no blogue da equipa do gráfico. Funcionalidades de beta requerem o "api-version = beta" parâmetro de cadeia de consulta. Quando a equipa da Graph API Deteta que uma funcionalidade de pré-visualização está preparada para DG, iremos adicionar essa funcionalidade para a última versão GA (ou se o constitui uma alteração inovadora que isto resulta num novo número de versão incrementados). Iremos tornar não garante que uma funcionalidade de pré-visualização será promovida para depois da disponibilidade geral
Para a versão beta, voltaremos a tentar evitar quaisquer alterações quanto possíveis, mas não podemos irá garanti-lo. Aplicações de cliente a utilizar a versão beta devem esperar alterações ocasionalmente. Consulte suplementares os termos de utilização para a pré-visualizações do Microsoft Azure.
Versão 1.6
Esta secção lista as alterações para a Graph API versão 1.6.
Versão de API do gráfico 1.6 apresenta as seguintes alterações de funcionalidade:
Suporte adicionado para utilizadores de conta local do Azure Active Directory B2C. Isto envolve a novas propriedades de utilizador entidade e um novo tipo de complexo SignInName para suportar a conta local início de sessão para os inquilinos do Azure Active Directory B2C. Para mais informações sobre o Azure Active Directory B2C, consulte o documentação do Azure Active Directory B2C.
Foi adicionado suporte para a deteção de serviço com o ServiceEndpoint entidade e a serviceEndpoints propriedade de navegação no aplicação e ServicePrincipal entidades.
Foi adicionado suporte para o comportamento de aplicações personalizadas que pode ser invocado por utilizar os serviços com o suplemento e KeyValue tipos e addIns propriedade o aplicação e ServicePrincipal entidades.
Foi adicionado suporte para a autenticação de palavra-passe sem com o TrustedCAsForPasswordlessAuth entidade, o CertificateAuthorityInformation tipo e o trustedCAsForPasswordlessAuth propriedade o TenantDetail entidade.
Adicionar o changePassword ação, o que pode ser chamada para permitir que o utilizador com sessão iniciada alterar a palavra-passe.
Gráfico de versões de cliente 2.1.x requerem Graph API versão 1.6; Versões de cliente 2.0.x requerem Graph API 1.5 da Graph.
Alterações de entidade
| Entidade | Descrição de alteração |
|---|---|
| aplicação | Adicionar o addIns propriedade, que define o comportamento personalizado que pode utilizar um serviço de consumo para chamar uma aplicação específica contextos. Adicionar o serviceEndpoints propriedade de navegação que contém a coleção de pontos finais de serviço que estão disponíveis para a deteção. |
| LicenseDetail | Nova entidade que contém os detalhes de licenciamento para um utilizador. |
| ServiceEndpoint | Nova entidade que contém as informações de deteção do serviço. |
| ServicePrincipal | Adicionar o addIns propriedade, que define o comportamento personalizado que pode utilizar um serviço de consumo para chamar uma aplicação específica contextos. Adicionar o serviceEndpoints propriedade de navegação que contém a coleção de pontos finais de serviço que estão disponíveis para a deteção. |
| SubscribedSku | Adicionar o appliesTo propriedade. |
| TenantDetail | Adicionar o trustedCAsForPasswordlessAuth propriedade, que contém o conjunto de autoridades de certificação utilizadas para validar a cadeia de fidedignidade ao efetuar a autenticação sem palavra-passe. |
| TrustedCAsForPasswordlessAuth | Nova entidade que representa um conjunto de autoridades de certificação para validar a cadeia de fidedignidade ao efetuar a autenticação sem palavra-passe. |
| utilizador | Adicionar o creationType propriedade, o que é utilizada para indicar que o utilizador é uma conta local. Adicionar o signInNames propriedade, que contém a coleção de nomes de início de sessão utilizado por um utilizador de conta local para iniciar sessão para um inquilino do Azure Active Directory B2C. Esta propriedade é mudada da alternativeSignInNamesInfo na versão beta. Adicionar o licenseDetails propriedade de navegação. |
Alterações do tipo complexo
| Tipo | Descrição de alteração |
|---|---|
| suplemento | Novo tipo utilizado para definir o comportamento personalizado que pode utilizar um serviço de consumo para chamar uma aplicação específica contextos. |
| CertificateAuthorityInformation | Novo tipo que representa uma autoridade de certificação utilizada ao validar a cadeia de fidedignidade ao efetuar a autenticação sem palavra-passe. |
| KeyValue | Novo tipo que contém um par chave-valor que define um parâmetro que um serviço de consumo pode utilizar ou chamar uma aplicação especificada num suplemento. |
| ServicePlanInfo | Adicionar o appliesTo propriedade. Adicionar o provisioningStatus propriedade. |
| SignInName | Tipo de novo para armazenar informações sobre um nome de início de sessão pode ser utilizado por um utilizador de conta local para iniciar sessão para um inquilino do Azure Active Directory B2C. Este tipo é mudado da LogonIdentifier na versão beta. |
Alterações de ação e a função
| Função | Descrição de alteração |
|---|---|
| changePassword | Nova ação que pode ser chamado para permitir que o utilizador com sessão iniciada alterar a palavra-passe. |
Versão 1.5
Esta secção lista as alterações para a Graph API versão 1.5.
Versão de API do gráfico 1.5 apresenta as seguintes alterações de funcionalidade:
O espaço de nomes do esquema da Graph API foi alterado de Microsoft.WindowsAzure.ActiveDirectory para Microsoft.DirectoryServices. Este procedimento afeta todas as entidades e tipos complexos expostos pelo Graph API.
Foi adicionado suporte para extensões de esquema de diretório. Isto permite-lhe adicionar propriedades que são necessários para a aplicação para objetos de diretório. As seguintes entidades suportam extensões de esquema: utilizador, grupo, TenantDetail, dispositivo, aplicação, e ServicePrincipal. Para suportar as extensões de esquema de diretório: o ExtensionProperty entidade foi adicionada, o extensionProperties foi adicionada à propriedade de navegação do aplicaçãoentidade e uma nova função getAvailableExtensionProperties, foi adicionada para devolver as propriedades de extensão registado de suportadas objetos de diretório. Para obter mais informações sobre como expandir o esquema de diretório, consulte extensões de esquema de diretório.
A forma no qual são representadas permissões foi alterado e é mais estreitamente alinhado com conceitos de OAuth 2.0, bem como com as permissões de forma são representados no outros componentes do Azure. O permissão entidade foi removida e foi substituída com o OAuth2PermissionGrant entidade. Esta entidade representa delegados âmbitos de permissões de OAuth 2.0 que chegam a uma afirmação de âmbito de token de acesso de OAuth 2.0. Além disso, a nova AppRoleAssignment entidade representa funções da aplicação que podem ser atribuídas a utilizadores, grupos e principais de serviço. Dois relacionadas com tipos complexos também foram adicionados: função de aplicação e OAuth2Permission. Esta alteração tem precipitated mudar o nome de algumas propriedades e adicionar outros as seguintes entidades: aplicação, grupo, ServicePrincipale utilizador.
O função entidade é mudada para DirectoryRole.
O RoleTemplate entidade é mudada para DirectoryRoleTemplate.
As tabelas seguintes listam as entidades, tipos complexos e as funções que foram adicionadas, alterado ou removido para esta versão.
Alterações de entidade
| Entidade | Descrição de alteração |
|---|---|
| aplicação | Atualizar o appId propriedade da Edm.Guid para EDM. Adicionar o appRoles propriedade, que contém a coleção de funções de aplicação que pode declarar uma aplicação. Estas funções podem ser atribuídas a utilizadores, grupos ou principais de serviço. Adicionar o groupMembershipClaims propriedade, o que é uma máscara de bits que configura a afirmação "grupos" emitida num utilizador ou um token de acesso de OAuth 2.0 que espera da sua aplicação. Os valores de máscara de bits são: 0: None, 1: grupos de segurança e funções do Azure AD, 2: reservado e 4: reservado. Definir a máscara de bits para 7 obter todos os grupos de segurança, grupos de distribuição e funções do Azure AD que o utilizador com sessão iniciada é membro. Adicionar o knownClientApplications propriedade, que contém uma lista de aplicações cliente que estão associadas a esta aplicação de recursos. Consentimento para qualquer uma das aplicações cliente conhecidos resultará na implícito consentimento para a aplicação de recursos através de uma caixa de diálogo de consentimento combinado (que mostra os âmbitos de permissões de OAuth de que o cliente e o recurso). Adicionar o oauth2AllowImplicitFlow propriedade, o que especifica se esta aplicação web pode pedir tokens de fluxo implícito OAuth2.0. A predefinição é falsa. Adicionar o oauth2AllowUrlPathMatching propriedade, o que especifica se, como parte de pedidos de token de OAuth 2.0, do Azure AD irá permitir caminho correspondente do URI de redirecionamento contra replyUrls da aplicação. A predefinição é falso. Adicionar o oauth2Permissions propriedade, que contém a coleção de âmbitos de permissões de OAuth 2.0 que expõe web de aplicação de API (recurso) para aplicações cliente. Estes âmbitos de permissões podem ser concedidos a aplicações de cliente durante a autorização. Adicionar o oauth2RequiredPostResponse propriedade, o que especifica se, como parte de pedidos de token de OAuth 2.0, do Azure AD irá permitir pedidos POST, por oposição a pedidos GET. Predefinição é falso, que especifica que apenas GET pedidos serão permitidas. Adicionar o requiredResourceAccess propriedade, o que especifica os recursos que esta aplicação requer o acesso e o conjunto de âmbitos de permissões de OAuth e funções da aplicação que necessita em cada um desses recursos. Nesta pré-configuração de acesso a recursos necessários unidades a experiência de consentimento do utilizador final. Adicionar o extensionProperties propriedade de navegação que contém as propriedades de extensão associadas à aplicação. |
| AppRoleAssignment | Nova entidade que é utilizada para registar quando um utilizador ou grupo é atribuída a uma aplicação. Neste caso, irá resultar no mosaico aplicação que mostra a cópia de segurança no painel de acesso de aplicação do utilizador. Esta entidade também pode ser utilizada para conceder acesso de aplicação (modelada como um principal de serviço) outra a uma aplicação de recursos numa função específica. |
| Contact | Adicionar o sipProxyAddress propriedade, o que especifica a voz através de endereço (SIP) do protocolo de início de sessão do IP (VOIP) para o contacto. |
| DirectoryObject | Adicionar o deletionTimestamp propriedade, o que indica o tempo no qual foi eliminado um objeto de diretório. Aplica-se apenas a esses objetos de diretório que podem ser restaurados. Atualmente isto apenas é suportado para aplicação. |
| DirectoryRole | Cujo nome foi alterado de função. Adicionar o roleTemplateId propriedade |
| DirectoryRoleTemplate | Cujo nome foi alterado de RoleTemplate. |
| ExtensionProperty | Nova entidade que permite que uma aplicação definir e utilizar um conjunto de propriedades adicionais que podem ser adicionados objetos de diretório (utilizadores, grupos, os detalhes de inquilino, dispositivos, aplicações e principais do serviço) sem a aplicação que requerem um arquivo de dados externas. |
| grupo | Adicionar o onPremisesSecurityIdentifier propriedade, que contém o identificador de segurança (SID) no local para o grupo que foi sincronizado no local para a nuvem. Adicionar o appRoleAssignments propriedade de navegação, que aponta para o conjunto de aplicações (principais do serviço) atribuído a este grupo. |
| OAuth2PermissionGrant | Nova entidade que especifica um OAuth2.0 delegado âmbito de permissão. O OAuth especificado pode ser solicitado delegado permissão âmbito por aplicações cliente (através de requiredResourceAccess coleção) chamar esta aplicação de recursos. Substitui o permissão entidade é removida nesta versão. |
| Permissão | Cujo nome foi alterado para OAuth2PermissionGrant. |
| Função | Cujo nome foi alterado para DirectoryRole. |
| RoleTemplate | Cujo nome foi alterado para DirectoryRoleTemplate. |
| ServicePrincipal | Adicionar o appDisplayName propriedade, o que especifica o nome a apresentar exposto pela aplicação associada. Adicionar o appRoleAssignmentRequired propriedade, o que especifica se um AppRoleAssignment para um utilizador ou grupo, será necessário antes do Azure AD irá emitir um token de acesso de utilizador ou para a aplicação. Adicionar o appRoles propriedade, que contém as funções de aplicação expostas pela aplicação associada. Para obter mais informações, consulte o appRoles definição de propriedade de aplicação entidade. Adicionar o oauth2Permissions propriedade, que contém as permissões de OAuth 2.0 expostas pela aplicação associada. Para obter mais informações, consulte o oauth2Permisions definição de propriedade de aplicação entidade. Adicionar o preferredTokenSigningKeyThumbprint propriedade. Reservado para utilização interna apenas. Não escrever ou dependem caso contrário, esta propriedade. Pode ser removida em versões futuras. Adicionar o appRoleAssignedTo propriedade de navegação, que aponta para o conjunto de aplicações que o principal de serviço está atribuído. Adicionar o appRoleAssignments propriedade de navegação, que aponta para o conjunto de principais (utilizadores, grupos e principais do serviço) que estão atribuídos a este principal de serviço. Adicionar o oauth2PermissionGrants propriedade de navegação, que aponta para o conjunto de concede de representação do utilizador associada este principal de serviço. Remover o permissões propriedade de navegação |
| TenantDetail | Remover a propriedade tenantType. |
| utilizador | Adicionar o onPremisesSecurityIdentifier propriedade, que contém o identificador de segurança (SID) no local para o utilizador que foi sincronizado no local para a nuvem. Adicionar o sipProxyAddress propriedade, o que especifica a voz através de endereço (SIP) do protocolo de início de sessão do IP (VOIP) para o utilizador. Adicionar o appRoleAssignments propriedade de navegação, que aponta para o conjunto de aplicações (principais do serviço) atribuído a este utilizador. Adicionar o oauth2PermissionGrants propriedade de navegação, que aponta para o conjunto de OAuth 2.0 utilizador representação concede associado a este utilizador. Remover o permissões propriedade de navegação. |
Alterações do tipo complexo
| Tipo | Descrição de alteração |
|---|---|
| função de aplicação | Novo tipo de que especifica funções da aplicação que podem ser solicitadas por aplicações cliente chamar esta aplicação, ou que pode ser utilizada para atribuir a aplicação a utilizadores ou grupos de uma das funções de aplicação especificada. |
| OAuth2Permission | Novo tipo que representa um âmbito de permissões de OAuth 2.0. O âmbito de permissões de OAuth 2.0 especificado pode ser solicitado por aplicações cliente (através de requiredResourceAccess coleção) chamar esta aplicação de recursos. |
| RequiredResourceAccess | Novo tipo de que especifica o conjunto de âmbitos de permissões de OAuth 2.0 e funções de aplicação sob o recurso especificado que esta aplicação requer o acesso. |
| ResourceAccess | Novo tipo que representa uma permissão que esta aplicação requer. |
Alterações de ação e a função
| Função | Descrição de alteração |
|---|---|
| getAvailableExtensionProperties | Nova função que devolve a lista completa das propriedades de extensão que foram registados num diretório. As propriedades de extensão podem ser registadas para as seguintes entidades: utilizador, grupo, dispositivo, TenantDetail, aplicação, e ServicePrincipal. |
| getMemberObjects | Nova função devolve todas as grupo e DirectoryRole objetos que um utilizador, contacto, grupo ou principal de serviço transitively é um membro do. |
| getObjectsByObjectIds | Nova função que devolve os objetos de diretório especificados uma lista de IDs de objeto. Também pode especificar as coleções de recursos (utilizadores, grupos, etc.) devem ser pesquisadas, especificando o opcional tipos parâmetro. |
| restore | Nova ação de serviço que permite que uma aplicação eliminada para serem restaurados. |
Versão 2013-11-08
Esta secção lista as alterações para a Graph API versão 2013-11-08.
As tabelas seguintes listam as entidades, tipos complexos e as funções que foram adicionadas, alterado ou removido para esta versão.
Alterações de entidade
| Entidade | Descrição de alteração |
|---|---|
| aplicação | Adicionar o proprietários propriedade de navegação, que aponta para o conjunto de objetos de diretório que são proprietários da aplicação. Os proprietários são um conjunto de utilizadores de não administrador que têm permissão para modificar este objeto. Herdado de DirectoryObject. |
| DeviceConfiguration | Nova entidade que representa a configuração para um dispositivo. |
| DirectoryObject | Adicionar o createdOnBehalfOf propriedade de navegação, que aponta para o diretório de objeto que este objeto foi criado no nome de. Adicionar o createdObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que foram criados pelo objecto actual. Adicionar o proprietários propriedade de navegação, 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 utilizadores de não administrador que têm permissão para modificar este objeto. Adicionar o ownedObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que é proprietário do objeto atual. Importante: entidades que derivem de DirectoryObject herdar as respetivas propriedades e poderão herdar as respetivas propriedades de navegação. |
| grupo | Adicionar o proprietários propriedade de navegação, 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 utilizadores de não administrador que têm permissão para modificar este objeto. Herdado de DirectoryObject. |
| Função | Adicionar o ownedObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que é proprietário de função. Herdado de DirectoryObject. O função entidade foi mudada para DirectoryRole a partir da versão 1.5. Para obter informações sobre função, consulte DirectoryRole. |
| ServicePrincipal | Adicionar o appOwnerTenantID propriedade. Adicionar o autheniticationPolicy propriedade. Reservado para utilização interna apenas. Não utilize. Removida na versão 1.5. Adicionar o createdObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que foram criadas no principal de serviço. Herdado de DirectoryObject. Adicionar o proprietários propriedade de navegação, que aponta para o conjunto de objetos de diretório que são proprietários do principal de serviço. Os proprietários são um conjunto de utilizadores de não administrador que têm permissão para modificar este objeto. Herdado de DirectoryObject. Adicionar o ownedObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que é proprietário principal de serviço. Herdado de DirectoryObject. |
| utilizador | Adicionar o immutableId propriedade, o que associa uma conta de utilizador do Active Directory no local para o respetivo objeto de utilizador do Azure AD. Esta propriedade tem de ser especificada quando criar uma nova conta de utilizador no gráfico, se estiver a utilizar um domínio federado para o utilizador userPrincipalName propriedade (UPN). Adicionar o userType propriedade, o que é um valor de cadeia que pode ser utilizado para classificar os tipos de utilizador no diretório, tais como "Membro" e "Convidado". Adicionar o createdObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que foram criados pelo utilizador. Herdado de DirectoryObject. Adicionar o ownedObjects propriedade de navegação, que aponta para o conjunto de objetos de diretório que pertencem ao utilizador. Herdado de DirectoryObject. |
Alterações do tipo complexo
| Tipo | Descrição de alteração |
|---|---|
| ServicePrincipalAuthenticationPolicy | Reservado para utilização interna apenas. Não utilize. Removida na versão 1.5. |
Alterações de ação e a função
| Função | Descrição de alteração |
|---|---|
| assignLicense | Nova ação de serviço que atualiza um utilizador com uma lista de licenças para adicionar e/ou a remover. |
Versão 2013-04-05
Esta é a versão da base da Graph API.