API do Graph do Active Directory do AzureAzure Active Directory Graph API

Importante

É altamente recomendável usar o Microsoft Graph em vez da API do Azure AD Graph para acessar recursos do Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Nossos esforços de desenvolvimento agora estão concentrados no Microsoft Graph e não há planejamento de novas melhorias para a API do Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser apropriada; para obter mais informações, consulte a postagem no blog Microsoft Graph ou o Azure AD Graph no Centro de Desenvolvimento do Office.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Este artigo se aplica à API do Graph do Azure Active Directory.This article applies to Azure AD Graph API. Para obter informações semelhantes relacionadas a API do Microsoft Graph, consulte usar a API do Graph.For similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

A API do Graph do Active Directory do Azure fornece acesso programático ao AD do Azure por meio de pontos de extremidade da API REST.The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. Aplicativos podem usar a API do Microsoft Azure AD Graph para realizar operações CRUD (criar, ler, atualizar e excluir) nos objetos e dados do diretório.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Por exemplo, a API do Microsoft Azure AD Graph fornece suporte às seguintes operações comuns para um objeto de usuário:For example, Azure AD Graph API supports the following common operations for a user object:

  • Criar um novo usuário em um diretórioCreate a new user in a directory
  • Obter propriedades detalhadas do usuário, como seus gruposGet a user’s detailed properties, such as their groups
  • Atualizar as propriedades do usuário, como sua localização e o número de telefone, ou alterar sua senhaUpdate a user’s properties, such as their location and phone number, or change their password
  • Verificar a associação de grupo do usuário para acesso baseado em funçãoCheck a user’s group membership for role-based access
  • Desabilitar uma conta de usuário ou excluí-la totalmenteDisable a user’s account or delete it entirely

Além disso, você pode executar operações semelhantes em outros objetos, como grupos e aplicativos.Additionally, you can perform similar operations on other objects such as groups and applications. Para chamar a API do Microsoft Azure AD Graph em um diretório, o aplicativo deve estar registrado no Microsoft Azure AD.To call Azure AD Graph API on a directory, your application must be registered with Azure AD. O aplicativo também deve ter acesso concedido para API do Microsoft Azure AD Graph.Your application must also be granted access to Azure AD Graph API. Esse acesso é normalmente obtido por meio de um fluxo de consentimento do usuário ou administrador.This access is normally achieved through a user or admin consent flow.

Para começar a usar a API do Graph do Azure Active Directory, consulte o guia de início rápido da API do Graph do Azure AD ou exiba a documentação de referência da API do Graph do Azure AD interativa.To begin using the Azure Active Directory Graph API, see the Azure AD Graph API quickstart guide, or view the interactive Azure AD Graph API reference documentation.

RecursosFeatures

API do Microsoft Azure AD Graph fornece os seguintes recursos:Azure AD Graph API provides the following features:

  • Pontos de extremidade da API REST: a API do Microsoft Azure AD Graph é um serviço RESTful composto por pontos de extremidade acessados por meio de solicitações HTTP padrão.REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. A API do Microsoft Azure AD Graph fornece suporte a tipos de conteúdo XML ou JavaScript Object Notation (JSON) para solicitações e respostas.Azure AD Graph API supports XML or Javascript Object Notation (JSON) content types for requests and responses. Para saber mais, consulte Referência da API REST do Graph do Azure AD.For more information, see Azure AD Graph REST API reference.
  • Autenticação com Microsoft Azure AD: cada solicitação à API do Microsoft Azure AD Graph deve ser autenticada com o anexo de um JSON Web Token (JWT) no cabeçalho de Autorização da solicitação.Authentication with Azure AD: Every request to Azure AD Graph API must be authenticated by appending a JSON Web Token (JWT) in the Authorization header of the request. Esse token é adquirido ao fazer uma solicitação ao ponto de extremidade do AD do Azure e fornecer credenciais válidas.This token is acquired by making a request to Azure AD’s token endpoint and providing valid credentials. Você pode usar o fluxo de credenciais de cliente OAuth 2.0 ou o fluxo de concessão do código de autorização para adquirir um token para chamar o Graph.You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. Para obter mais informações, veja OAuth 2.0 no AD do Azure.For more information, OAuth 2.0 in Azure AD.
  • RBAC (Autorização baseada em função): grupos de segurança são usados para executar a RBAC na API do Microsoft Azure AD Graph.Role-Based Authorization (RBAC): Security groups are used to perform RBAC in Azure AD Graph API. Por exemplo, se você quiser determinar se um usuário tem acesso a um recurso específico, o aplicativo poderá chamar a operação Verificar associação de grupo (transitiva), que retornará verdadeiro ou falso.For example, if you want to determine whether a user has access to a specific resource, the application can call the Check group membership (transitive) operation, which returns true or false.
  • Consulta diferencial: consulta diferencial permite controlar as alterações em um diretório entre dois períodos de tempo sem precisar fazer consultas frequentes à API do Microsoft Azure AD Graph.Differential Query: Differential query allows you to track changes in a directory between two time periods without having to make frequent queries to Azure AD Graph API. Este tipo de solicitação retornará apenas as alterações feitas entre a solicitação de consulta diferencial anterior e a solicitação atual.This type of request will return only the changes made between the previous differential query request and the current request. Para saber mais, leia Consulta diferencial da API do Graph Azure AD.For more information, see Azure AD Graph API differential query.
  • Extensões de diretório: é possível adicionar propriedades personalizadas a objetos de diretório sem exigir um armazenamento de dados externo.Directory Extensions: You can add custom properties to directory objects without requiring an external data store. Por exemplo, se o aplicativo exigir uma propriedade de ID do Skype para cada usuário, você poderá registrar a nova propriedade no diretório e estará disponível para uso em cada objeto de usuário.For example, if your application requires a Skype ID property for each user, you can register the new property in the directory and it will be available for use on every user object. Para obter mais informações, consulte Extensões de esquema do diretório da API do Graph do Azure AD.For more information, see Azure AD Graph API directory schema extensions.
  • Protegido pelos escopos de permissão: a API do Microsoft Azure AD Graph expõe escopos de permissão que permitem acesso seguro aos dados do Microsoft Azure AD usando o OAuth 2.0.Secured by permission scopes: Azure AD Graph API exposes permission scopes that enable secure access to Azure AD data using OAuth 2.0. Isso fornece suporta a uma variedade de tipos de aplicativo cliente, incluindo:It supports a variety of client app types, including:

    • interfaces de usuário que recebem acesso delegado aos dados por meio de autorização do usuário conectado (delegado)user interfaces that are given delegated access to data via authorization from the signed-in user (delegated)
    • aplicativos de serviço/daemon que funcionam em segundo plano sem que um usuário conectado esteja presente e use o controle de acesso baseado em função definido pelo aplicativoservice/daemon applications that operate in the background without a signed-in user being present and use application-defined role-based access control

      Ambas as permissões delegadas e de aplicativo representam um privilégio exposto pela API do Microsoft Azure AD Graph e podem ser solicitadas pelos aplicativos clientes por meio dos recursos de permissões de registro do aplicativo no Portal do Azure.Both delegated and application permissions represent a privilege exposed by the Azure AD Graph API and can be requested by client applications through application registration permissions features in the Azure portal. Escopos de permissão da API do Graph do Azure AD fornecem informações sobre o que está disponível para uso pelo aplicativo cliente.Azure AD Graph API permission scopes provides information on what's available for use by your client application.

CenáriosScenarios

A API do Microsoft Azure AD Graph habilita muitos cenários de aplicativos.Azure AD Graph API enables many application scenarios. A seguir, os cenários mais comuns:The following scenarios are the most common:

  • Aplicativo de linha de negócios (único locatário): neste cenário, um desenvolvedor corporativo trabalha para uma organização que tem uma assinatura do Office 365.Line of Business (Single Tenant) Application: In this scenario, an enterprise developer works for an organization that has an Office 365 subscription. O desenvolvedor está criando um aplicativo da Web que interage com o Azure AD para executar tarefas, como atribuir uma licença a um usuário.The developer is building a web application that interacts with Azure AD to perform tasks such as assigning a license to a user. Essa tarefa exige acesso à API do Graph do Azure AD, portanto, o desenvolvedor registra o aplicativo de locatário único no Azure AD e configura as permissões de leitura e gravação da API do Graph do Azure AD.This task requires access to the Azure AD Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for Azure AD Graph API. Em seguida, o aplicativo é configurado para usar suas próprias credenciais ou as do usuário de login atual para adquirir um token para chamar a API do Graph do Azure AD.Then the application is configured to use either its own credentials or those of the currently sign-in user to acquire a token to call the Azure AD Graph API.
  • Software como um aplicativo de serviço (multilocatário): nesse cenário, um fornecedor de software independente (ISV) está desenvolvendo um aplicativo da Web multilocatário hospedado que fornece recursos de gerenciamento de usuário para outras organizações que usam o Azure AD.Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing a hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. Esses recursos exigem acesso a objetos de diretório, portanto, o aplicativo precisa chamar a API do Graph do Azure AD.These features require access to directory objects, so the application needs to call the Azure AD Graph API. O desenvolvedor registra o aplicativo no Microsoft Azure AD, configura para exigir as permissões de leitura e gravação para a API do Microsoft Azure AD Graph e habilita o acesso externo para que outras organizações possam concordar com o uso do aplicativo em seu diretório.The developer registers the application in Azure AD, configures it to require read and write permissions for Azure AD Graph API, and then enables external access so that other organizations can consent to use the application in their directory. Quando um usuário de outra organização autentica o aplicativo pela primeira vez, é mostrada uma caixa de diálogo de consentimento com as permissões que o aplicativo está solicitando.When a user in another organization authenticates to the application for the first time, they are shown a consent dialog with the permissions the application is requesting. Conceder consentimento dará o aplicativo às permissões solicitadas para a API do Microsoft Azure AD Graph no diretório do usuário.Granting consent will then give the application those requested permissions to Azure AD Graph API in the user’s directory. Para saber mais sobre a estrutura de consentimento, consulte Visão geral da estrutura de consentimento.For more information on the consent framework, see Overview of the consent framework.

Próximas etapasNext steps

Para começar a usar a API do Graph do Azure Active Directory, consulte os tópicos a seguir:To begin using the Azure Active Directory Graph API, see the following topics: