Visão geral das operações | Conceitos da API do Graph
A API do Graph do Azure AD (Active Directory) é um serviço compatível com o OData 3.0 que você pode usar para ler e modificar objetos, como usuários, grupos e contatos em um locatário. A API do Azure AD Graph expõe pontos de extremidade REST a que você envia solicitações HTTP para executar as operações usando o serviço. As seções a seguir fornecem informações gerais sobre como formatar solicitações e o que esperar nas respostas quando você usa a API do Graph para ler e gravar recursos do diretório, chamar funções ou ações do diretório ou executar consultas nele. Para obter informações mais detalhadas sobre como executar operações específicas nos recursos do diretório, consulte o tópico relacionado às operações em questão na Azure AD Graph API reference (Referência da API do Azure AD Graph).
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.
Uma solicitação bem-sucedida para a API do Graph deve ser dirigida a um ponto de extremidade válido e precisa ser bem formatada, ou seja, deve conter os cabeçalhos obrigatórios e, se necessário, um conteúdo JSON no corpo da solicitação. O aplicativo que faz a solicitação deve incluir um token recebido do Azure AD que prova que ele está autorizado a acessar os recursos a que a solicitação é direcionada. O aplicativo deve ser capaz de lidar com quaisquer respostas recebidas da API do Graph.
As seções neste tópico ajudarão você a entender o formato das solicitações e as respostas usadas com a API do Graph.
Autenticação e autorização
Cada solicitação à API do Graph deve ter um token de portador emitido pelo Azure Active Directory anexado. O token transmite informações sobre seu aplicativo, o usuário conectado (no caso de permissões delegadas), a autenticação e as operações que seu aplicativo está autorizado a executar no diretório. Esse token é carregado no cabeçalho Authorization da solicitação. Por exemplo (o token foi reduzido para fins de brevidade):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
A API do Graph executa a autorização com base nos escopos de permissões OAuth 2.0 presentes no token. Para obter mais informações sobre os escopos de permissão que a API do Graph expõe, consulte Graph API Permission Scopes (Escopos de permissão da API do Graph).
Para que seu aplicativo seja autenticado no Azure AD e chame a API do Graph, você deve adicioná-lo ao seu locatário e configurá-lo para solicitar permissões (escopos de permissões OAuth 2.0) ao Microsoft Azure Active Directory. Para obter informações sobre como adicionar e configurar um aplicativo, consulte Integrating Applications with Azure Active Directory (Integrando aplicativos ao Azure Active Directory).
O Azure AD usa o protocolo de autenticação OAuth 2.0. Saiba mais sobre o OAuth 2.0 no Azure AD, incluindo tokens de acesso e fluxos com suporte, em OAuth 2.0 no Azure AD.
Endereçamento de ponto de extremidade
Para executar operações com a API do Graph, você envia solicitações HTTP com um método com suporte - normalmente, GET, POST, PATCH, PUT ou DELETE - para um ponto de extremidade que tem como destino o serviço, uma coleção de recursos, um recurso individual, uma propriedade de navegação de um recurso ou uma função ou ação exposta pelo serviço. Pontos de extremidade são expressos como URLs.
O seguinte descreve o formato básico de um ponto de extremidade de API do Graph:
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
Os componentes a seguir compõem a URL:
- Raiz do serviço: a raiz do serviço para todas as solicitações da API do Graph é
https://graph.windows.net. - Identificador do locatário {tenant_id}: o identificador do locatário a que a solicitação é dirigida.
- Caminho do recurso {resource_path}: o caminho para o recurso - por exemplo, um usuário ou um grupo – a que a solicitação é dirigida.
- Versão da API do Graph {api_version}: a versão da API do Graph a que a solicitação é dirigida. É expressa como um parâmetro de consulta e é obrigatória.
Observação: em alguns casos, durante a leitura de coleções de recursos, parâmetros de consulta do OData podem ser adicionados à solicitação para filtrar, ordenar e paginar o conjunto de resultados. Para obter mais informações, consulte a seção Parâmetros de consulta OData neste tópico.
Identificador do locatário {tenant_id}
Você pode especificar o locatário de destino de uma solicitação de quatro maneiras:
Pela ID do objeto de locatário. Um GUID que foi atribuído quando o locatário foi criado. Pode ser encontrado na propriedade objectId do objeto TenantDetail. A URL a seguir mostra como tratar a coleção de recursos dos usuários usando a ID do objeto de locatário:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.Por nome de domínio verificado (registrado). Um dos nomes de domínio que são registrados para o locatário. Eles podem ser encontrados na propriedade verifiedDomains do objeto TenantDetail. A URL a seguir mostra como tratar a coleção de recursos dos usuários de um locatário que tem o domínio contoso.com:
https://graph.windows.net/contoso.com/users?api-version=1.6.Usando o alias
myOrganization. Este alias está disponível somente ao usar a autenticação do tipo Concessão de código de autorização OAuth (de base tripla). Isto é, ao usar um escopo de permissão delegado. O alias não diferencia maiúsculas de minúsculas. Ele substitui a ID de objeto ou o domínio de locatário na URL. Quando o alias é usado, a Graph API deriva o locatário das reivindicações apresentadas no token anexado à solicitação. A URL a seguir mostra como tratar a coleção de recursos de usuários de um locatário usando este alias:
https://graph.windows.net/myorganization/users?api-version=1.6.Usando o alias
me. Este alias está disponível somente ao usar a autenticação do tipo Concessão de código de autorização OAuth (de base tripla). Isto é, ao usar um escopo de permissão delegado. O alias não diferencia maiúsculas de minúsculas. Ele substitui a ID de objeto ou o domínio de locatário na URL. Quando o alias é usado, a Graph API deriva o usuário das reivindicações apresentadas no token anexado à solicitação. A URL a seguir para tratar o usuário conectado usando este alias:https://graph.windows.net/me?api-version=1.6.
Observação: você usa o alias me somente para operações de destino relacionadas ao usuário conectado. Para obter mais informações, consulte Signed-in User Operations (Operações de usuários conectados).
Caminho do recurso {resource_path}
Você especificará o {resource_path} de formas diferentes se tiver como alvo uma coleção de recursos, um recurso individual, uma propriedade de navegação de um recurso, uma função ou ação exposta no locatário ou uma função ou ação exposta em um recurso.
| Destino | Caminho | Explicação |
|---|---|---|
| Metadados de serviço | /$metadata |
Retorna o documento de metadados do serviço. O exemplo a seguir tem como destino metadados de serviço que usam o locatário contoso.com: https://graph.windows.net/contoso.com/$metadata?api-version=1.6 Observação: nenhuma autenticação é necessária para ler os metadados de serviço. |
| Coleção de recursos | /{resource_collection} |
Tem como alvo uma coleção de recursos, como usuários ou grupos no locatário. Você pode usar esse caminho para ler recursos na coleção e, dependendo do tipo de recurso, criar um novo recurso no locatário. Em muitos casos, o conjunto de resultados retornado por uma leitura pode ser ainda mais refinado por meio do acréscimo de parâmetros de consulta para filtrar, organizar ou paginar os resultados. O exemplo a seguir tem como destino a coleção de usuários: https://graph.windows.net/myorganization/users?api-version=1.6 |
| Recurso único | /{resource_collection}/{resource_id} |
Tem como destino um recurso específico em um locatário, como um usuário, contato organizacional ou grupo. Para a maioria dos recursos, resource_id é a ID de objeto. Alguns recursos permitem especificadores adicionais. Por exemplo, os usuários também podem ser especificados pelo nome UPN. Dependendo do recurso, você pode usar esse caminho para obter as propriedades declaradas do recurso, modificar suas propriedades declaradas ou excluir o recurso. O exemplo a seguir tem como destino o usuário john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| Propriedade de navegação (objetos) | /{resource_collection}/{resource_id}/{property_name} |
Tem como destino uma propriedade de navegação de um recurso específico, como o gerente ou as associações de grupo de um usuário ou os membros de um grupo. Você pode usar esse caminho para retornar o objeto ou objetos referenciados pela propriedade de navegação de destino. O exemplo a seguir tem como destino o gerente de john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6 Observação: essa forma de endereçamento está disponível apenas para leituras. |
| Propriedade de navegação (links) | /{resource_collection}/{resource_id}/$links/{property_name} |
Tem como destino uma propriedade de navegação de um recurso específico, como o gerente ou as associações de grupo de um usuário ou os membros de um grupo. Você pode usar essa forma de endereçamento para ler e modificar uma propriedade de navegação. Em leituras, os objetos referenciados pela propriedade são retornados como um ou mais links no corpo da resposta. Em gravações, os objetos são especificados como um ou mais links no corpo da solicitação. O exemplo a seguir tem como destino a propriedade do gerente de john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6 |
| Funções ou ações expostas no locatário | /{function_name} |
Tem como destino uma função ou ação exposta no locatário. Ações e funções normalmente são invocadas com uma solicitação POST e podem incluir um corpo de solicitação. O exemplo a seguir tem como destino a função isMemberOf: https://graph.windows.net/myorganization/isMemberOf?api-version=1.6. |
| Funções ou ações expostas em um recurso. | /{resource_collection}/{resource_id}/{function_name} |
Tem como destino uma função ou ação exposta em um recurso. Ações e funções normalmente são invocadas com uma solicitação POST e podem incluir um corpo de solicitação. O exemplo a seguir tem como destino a função getMemberGroups: https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6. |
Versão da API do Graph {api-version}
Você usa o parâmetro de consulta api-version para direcionar uma operação para uma versão específica da API do Graph. Esse parâmetro é necessário.
O valor do parâmetro api-version pode ser:
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
Por exemplo, a seguinte URL destina-se à coleção de usuários que usa a API do Graph versão 1.6:
https://graph.windows.net/myorganization/users?api-version=1.6
Para obter mais informações sobre as versões e as alterações de recursos entre versões, consulte Versioning (Controle de versões).
Parâmetros de consulta OData
Em muitos casos, quando lê uma coleção de recursos, você pode filtrar, classificar e paginar o conjunto de resultados anexando parâmetros de consulta OData à sua solicitação.
A API do Graph dá suporte aos seguintes parâmetros de consulta OData:
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken e previous-page
Para obter mais informações sobre os parâmetros de consulta OData com suporte e suas limitações na API do Graph, consulte Supported Queries, Filters, and Paging Options (Opções de consultas, filtros e paginação com suporte).
Cabeçalhos de solicitação e resposta
A tabela a seguir mostra cabeçalhos HTTP comuns usados em solicitações com a API do Graph. Não é destinada a ser completa.
| Cabeçalho de solicitação | Descrição |
|---|---|
| Authorization | Obrigatório. Um token de portador emitido pelo Active Directory do Azure. Consulte Autenticação e autorização neste tópico para obter mais informações. |
| Content-Type | Necessário se o corpo da solicitação estiver presente. O tipo de mídia do conteúdo do corpo da solicitação. Use application/json. Podem ser incluídos parâmetros com o tipo de mídia. Observação: application/atom+xml e application/xml (para links) têm suporte, mas não são recomendados por motivos de desempenho e porque o suporte para XML será preterido em uma versão futura. |
| Content-Length | Necessário se o corpo da solicitação estiver presente. O comprimento da solicitação em bytes. |
A tabela a seguir mostra cabeçalhos HTTP comuns retornados em respostas pela API do Graph. Não é destinada a ser completa.
| Cabeçalho de resposta | Descrição |
|---|---|
| Content-Type | O tipo de mídia do conteúdo no corpo da resposta. O padrão é application/json. Solicitações de fotos em miniatura do usuário retornam image/jpeg por padrão. |
| Local | Retornados em respostas a solicitações POST que criam um novo recurso (objeto) no diretório. Contém o URI do recurso recém-criado. |
| ocp-aad-diagnostics-server-name | O identificador do servidor que executou a operação solicitada. |
| ocp-aad-session-key | A chave que identifica a sessão atual no serviço de diretório. |
No mínimo, recomendamos que você faça o seguinte para cada solicitação:
- Registre um carimbo de data/hora preciso do envio da solicitação.
- Envie e registre o
client-request-id. - Registre o código da resposta HTTP e
request-id.
Fornecer informações nos logs ajudará a Microsoft a solucionar problemas quando você pedir ajuda ou suporte.
Corpos de solicitação e resposta
Corpos de solicitação para solicitações PUT, PATCH e POST podem ser enviados em conteúdos JSON ou XML. As respostas do servidor podem ser retornadas em conteúdos JSON ou XML. Você pode especificar o conteúdo nos corpos de solicitação usando o cabeçalho de solicitação Content-Type e nas respostas usando o cabeçalho de solicitação Accept.
É altamente recomendável que você use conteúdos JSON em solicitações e respostas com a API do Graph. Recomendamos isso por motivos de desempenho e porque o XML será preterido em uma versão futura.
Recursos avançados
As seções anteriores discutem a formatação das solicitações e respostas básicas com a API do Graph. Recursos mais avançados podem acrescentar mais parâmetros de cadeia de caracteres de consulta ou ter corpos de solicitação e resposta significativamente diferentes das operações básicas mencionadas neste tópico.
Esses recursos incluem:
- Processamento em lotes: a API do Graph dá suporte ao processamento em lotes. Enviar solicitações em lotes reduz as viagens de ida e volta para o servidor, o que reduz a sobrecarga de rede e ajuda suas operações a serem concluídas mais rapidamente. Para obter mais informações sobre o processamento em lotes com a API do Graph, consulte Batch Processing (Processamento em lotes).
- Consulta diferencial: a API do Graph dá suporte à execução de consultas diferenciais. A consulta diferencial permite retornar alterações feitas em entidades específicas em um locatário entre solicitações emitidas em momentos diferentes. Normalmente, esse recurso é usado para sincronizar um repositório local com alterações no locatário. Para obter mais informações sobre a consulta diferencial com a API do Graph, consulte Differential Query (Consulta diferencial).