Descrição geral de operações | Conceitos da Graph API

  • Artigo

A Graph API do Azure Active Directory (AD) é um serviço em conformidade OData 3.0, que pode utilizar para ler e modificar objetos, tais como utilizadores, grupos e contactos de um inquilino. Azure AD Graph API expõe pontos finais REST que enviam pedidos de HTTP para efetuar operações de utilizar o serviço. As secções seguintes fornecem informações gerais sobre como os pedidos de formato e o que pode esperar nas respostas ao utilizar a Graph API para ler e escrever os recursos de diretório, chamar funções diretório ou ações ou executar consultas contra o diretório. Para obter mais informações sobre como efetuar os recursos de diretório de operações específicas, consulte o tópico de adequadas no referência da API do Azure AD Graph.

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.

Um pedido com êxito para a Graph API têm de ser resolvido para um ponto final válido e ser corretamente formatado, ou seja, tem de conter quaisquer cabeçalhos necessários e, se necessário, um payload JSON no corpo do pedido. A aplicação que efetua o pedido tem de incluir um token que recebeu do Azure AD que comprova que está autorizado a aceder aos recursos direcionados por pedido. A aplicação tem de ser capaz de lidar com qualquer respostas recebidas da Graph API.

As secções deste tópico irão ajudá-lo a compreender o formato de pedidos e respostas utilizadas com a Graph API.

Autenticação e autorização

Todos os pedidos para a Graph API tem de ter um token de portador emitido pelo Azure Active Directory ligado. As informações de token ativada sobre a sua aplicação, o utilizador com sessão iniciada (no caso de permissões delegadas), autenticação e as operações no diretório que a aplicação está autorizado a efetuar. Este token é efetuado no autorização cabeçalho do pedido. Por exemplo (o token de uma forma abreviada foi shortened):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

A Graph API efetua com base nos âmbitos de permissões de OAuth 2.0 presentes no token de autorização. Para obter mais informações sobre âmbitos de permissões que expõe a Graph API, consulte âmbitos de permissões do API Graph.

Para a sua aplicação autenticar com o Azure AD e chamar Graph API, tem de adicioná-lo no seu inquilino e configurá-lo para necessitarão de permissões (âmbitos de permissões de OAuth 2.0) do Windows Azure Active Directory. Para obter informações sobre como adicionar e configurar uma aplicação, consulte integrar aplicações com o Azure Active Directory.

AD do Azure utiliza o protocolo de autenticação OAuth 2.0. Pode saber mais sobre o OAuth 2.0 no Azure AD, incluindo fluxos suportados e aceder tokens no OAuth 2.0 no Azure AD.

Ponto final de endereçamento

Para executar operações com a Graph API, enviar pedidos de HTTP com um método suportado - normalmente obter, POST, PATCH, colocar ou eliminar – para um ponto final que tenha como destino de uma coleção de recursos, o serviço, uma propriedade de navegação de um recurso, e um recurso individual ou um a função ou ação expostos pelo serviço. Pontos finais são expressas como URLs.

O seguinte descreve o formato básico de um ponto final da Graph API:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Os seguintes componentes compõem o URL:

Tenha em atenção: em alguns casos, durante a leitura de coleções de recursos, os parâmetros de consulta de OData podem ser adicionados para o pedido para filtrar, ordenar e o conjunto de resultados de página. Para obter mais informações, consulte o parâmetros de consulta de OData deste tópico.

Identificador de inquilino {tenant_id}

Pode especificar o inquilino de destino de um pedido de uma das quatro formas:

  • ID de objeto por inquilino. O GUID que lhe foi atribuído quando o inquilino foi criado. Isto pode ser encontrado no objectId propriedade o TenantDetail objeto. O URL seguinte mostra como a abordar a coleção de recursos de utilizadores utilizando o ID de objeto do inquilino:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Ao verificar o nome de domínio (registado). Um dos nomes de domínio que estão registados para o inquilino. Pode encontrá-las no verifiedDomains propriedade o TenantDetail objeto. O URL seguinte mostra como a coleção de recursos de utilizadores de um inquilino com o domínio contoso.com de endereços:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Utilizando o myOrganization alias. Este alias só está disponível quando utiliza a autenticação de (3-legged) de tipo de conceder de código de autorização do OAuth; ou seja, quando utilizar um âmbito de delegado permissão. O alias não é sensível às maiúsculas e minúsculas. Substitui o domínio de inquilino ou um ID de objeto no URL. Quando é utilizado o alias, Graph API deriva de um inquilino afirmações apresentadas no token anexado ao pedido. O URL seguinte mostra como a coleção de recursos de utilizadores de um inquilino com este alias de endereço:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Utilizando o me alias. Este alias só está disponível quando utiliza a autenticação de (3-legged) de tipo de conceder de código de autorização do OAuth; ou seja, quando utilizar um âmbito de delegado permissão. O alias não é sensível às maiúsculas e minúsculas. Substitui o domínio de inquilino ou um ID de objeto no URL. Quando é utilizado o alias, Graph API deriva de um utilizador afirmações apresentadas no token anexado ao pedido. O seguinte URL para o utilizador com sessão iniciada com este alias de endereço:
    https://graph.windows.net/me?api-version=1.6.

Tenha em atenção: utilizar me alias apenas para operações de destino com o utilizador com sessão iniciada. Para obter mais informações, consulte Signed em operações de utilizador.

Caminho do recurso {resource_path}

Especificar o {resource_path} forma diferente dependendo se está a filtrar uma coleção de recursos, um recurso individual, uma propriedade de navegação de um recurso, uma função ou a ação expostos no inquilino, ou uma função ou a ação expostos num recurso.

Alvo Caminho Explicação
Metadados do serviço /$metadata Devolve o documento de metadados do serviço. O seguinte exemplo destinos metadados do serviço de utilizar o inquilino contoso.com:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Tenha em atenção: a autenticação não é necessária ler os metadados do serviço.
Coleção de recursos /{resource_collection} Destina-se uma coleção de recursos, tais como os utilizadores ou grupos no inquilino. Pode utilizar este caminho para ler os recursos na coleção e, dependendo do tipo de recurso, para criar um novo recurso no inquilino. Em muitos casos o conjunto de resultados devolvido por uma leitura pode ser mais foi refinado pela adição de parâmetros de consulta para filtrar, a ordem, ou esta página de resultados. O exemplo seguinte destina-se a coleção de utilizador:
https://graph.windows.net/myorganization/users?api-version=1.6
Único recurso /{resource_collection}/{resource_id} Destina-se um recurso específico de um inquilino, como um utilizador, contacte organizacional ou grupo. A maioria dos recursos de resource_id é o ID de objeto. Permitem a alguns recursos adicionais especificadores; Por exemplo, os utilizadores podem ser também especificados pelo nome principal de utilizador (UPN). Consoante o recurso, pode utilizar este caminho para obter as propriedades de recurso, para modificar as respetivas propriedades declaradas ou para eliminar o recurso declaradas. O exemplo seguinte destina-se o utilizador 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} Destina-se uma propriedade de navegação de um recurso específico, como o Gestor do utilizador ou as associações de grupo ou membros de um grupo. Pode utilizar este caminho para devolver o objecto ou objectos referenciados pela propriedade de navegação de destino. O exemplo seguinte destina-se o Gestor do john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Tenha em atenção: esta forma de endereçamento está disponível apenas para operações de leitura.
Propriedade de navegação (ligações) /{resource_collection}/{resource_id}/$links/{property_name} Destina-se uma propriedade de navegação de um recurso específico, como o Gestor do utilizador ou as associações de grupo ou membros de um grupo. Pode utilizar esta forma de endereçamento de leitura e modificar uma propriedade de navegação. Em operações de leitura, os objetos referenciados pela propriedade são devolvidos como um ou mais ligações no corpo da resposta. Em operações de escrita, os objetos são especificados como uma ou mais ligações no corpo do pedido. O exemplo seguinte destina-se a propriedade manager 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 inquilino /{function_name} Destina-se uma função ou a ação exposto no inquilino. As funções e as ações são normalmente invocadas com um pedido POST e podem incluir um corpo do pedido. Os seguintes destinos de exemplo a isMemberOf função:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funções ou ações expostas num recurso. /{resource_collection}/{resource_id}/{function_name} Destina-se uma função ou a ação expostos num recurso. As funções e as ações são normalmente invocadas com um pedido POST e podem incluir um corpo do pedido. Os seguintes destinos de exemplo a getMemberGroups função:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Versão da Graph API {api-version}

Utilizar o api-version parâmetro para o destino de uma versão específica da Graph API de uma operação de consulta. Este parâmetro é necessário.

O valor para o api-version parâmetro pode ser um dos seguintes:

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

Por exemplo o seguinte URL destina-se a coleção de utilizador utilizando a versão 1.6 do Graph API:

https://graph.windows.net/myorganization/users?api-version=1.6

Para obter mais informações sobre as versões e alterações de funcionalidade entre versões, consulte Versioning.

Parâmetros de consulta de OData

Em muitos casos ao ler uma coleção de recursos, pode filtrar, ordenar e a página de resultados ao anexar os parâmetros de consulta de OData ao seu pedido.

A Graph API suporta os seguintes parâmetros de consulta de Odata:

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken e página anterior

Consulte suportadas consultas, filtros e as opções de paginação para obter mais informações sobre OData suportado consultar parâmetros e as limitações a Graph API.

Cabeçalhos de pedido e resposta

A tabela seguinte mostra os cabeçalhos HTTP comuns utilizados em pedidos com a Graph API. Destina-se não ser abrangente.

Cabeçalho de pedido Descrição
Autorização Necessário. Um token de portador emitido pelo Azure Active Directory. Consulte autenticação e autorização neste tópico para obter mais informações.
Content-Type Necessário se o corpo do pedido está presente. O tipo de suporte de dados do conteúdo no corpo do pedido. Utilize a aplicação/json. Os parâmetros podem ser incluídos com o tipo de suporte de dados.
Tenha em atenção: application/atom + xml e aplicação/xml (para ligações) são suportados mas não são recomendadas ambos por motivos de desempenho e porque o suporte XML vai ser preterido numa versão futura.
Content-Length Necessário se o corpo do pedido está presente. O comprimento do pedido em bytes.

A tabela seguinte mostra os cabeçalhos HTTP comuns devolvidos nas respostas pela Graph API. Destina-se não ser abrangente.

Cabeçalho de resposta Descrição
Content-Type O tipo de suporte de dados do conteúdo no corpo da resposta. A predefinição é aplicação/json. Pedidos de fotografias em miniatura do utilizador devolverem imagem/jpeg por predefinição.
Localização Devolveu nas respostas para pedidos POST que crie um novo recurso (objeto) no diretório. Contém o URI do recurso recentemente criado.
ocp-aad-diagnostics-server-name O identificador do servidor que efetuar a operação pedida.
ocp-aad-session-key A chave que identifica a sessão atual com o serviço de diretório.

No mínimo, recomendamos que efetue o seguinte procedimento para cada pedido:

  1. Inicie sessão um carimbo de hora exata da submissão do pedido.
  2. Enviar e registar o client-request-id.
  3. Inicie o código de resposta HTTP e request-id.

Fornecer informações nesses registos vai ajudar a Microsoft a resolver problemas quando a peça ajuda ou suporte.

Corpos de pedido e resposta

Podem ser enviados corpos de pedido para pedidos POST, PATCH e PUT em: múltiplos payloads JSON ou XML. As respostas do servidor podem ser devolvidas num: múltiplos payloads JSON ou XML. Pode especificar o payload no corpos de pedido utilizando o Content-Type cabeçalho de pedido e nas respostas utilizando o Accept cabeçalho do pedido.

Recomendamos vivamente que utilize payloads JSON nos pedidos e respostas com a Graph API. Isto é por motivos de desempenho e porque o XML vai ser preterido numa versão futura.

Funcionalidades avançadas

As secções anteriores abordados a formatação do básicos pedidos e respostas com a Graph API. Funcionalidades mais avançadas podem adicionar parâmetros de cadeia de consulta adicionais ou ter pedido significativamente diferente e corpos de resposta que as operações básicas apresentadas anteriormente neste tópico.

Estas funcionalidades incluem:

  • Processamento de lote: A Graph API suporta a criação de batches. Enviar pedidos em lotes reduz ida e volta ao servidor, o que reduz a sobrecarga de rede e obter ajuda para que as operações de conclusão mais rapidamente. Para mais informações sobre o processamento em lote com a Graph API, consulte Batch processamento.
  • Consulta diferencial: A Graph API suporta a execução de consultas diferenciais. Consulta diferencial permite-lhe regressar alterações para entidades específicas de um inquilino entre pedidos emitidos em alturas diferentes. Esta funcionalidade é frequentemente utilizada para sincronizar um arquivo local com alterações de inquilino. Para obter mais informações sobre consulta diferencial com a Graph API, consulte consulta diferencial.

Recursos adicionais