Table of contents

Visão geral das operações | Conceitos da API do GraphOperations overview | Graph API concepts

Jimaco Brannian|Última Atualização: 19/06/2018
|
2 Colaboradores

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.The Azure Active Directory (AD) Graph API is an OData 3.0 compliant service that you can use to read and modify objects such as users, groups, and contacts in a tenant.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.Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service.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.The following sections provide general information about how to format requests and what to expect in responses when you use the Graph API to read and write directory resources, call directory functions or actions, or perform queries against the directory.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).For more detailed information about performing specific operations directory resources, see the appropriate operations topic in the Azure AD Graph API reference.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os 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 implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento 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 adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou 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.

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.A successful request to the Graph API must be addressed to a valid endpoint and be well-formatted, that is, it must contain any required headers and, if necessary, a JSON payload in the request body.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.The app making the request must include a token received from Azure AD that proves that it is authorized to access the resources targeted by the request.O aplicativo deve ser capaz de lidar com quaisquer respostas recebidas da API do Graph.The app must be able to handle any responses received from the Graph API.

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.The sections in this topic will help you understand the format of requests and responses used with the Graph API.

Autenticação e autorização Authentication and authorization

Cada solicitação à API do Graph deve ter um token de portador emitido pelo Azure Active Directory anexado.Every request to the Graph API must have a bearer token issued by Azure Active Directory attached.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.The token carries information about your app, the signed-in user (in the case of delegated permissions), authentication, and the operations on the directory that your app is authorized to perform.Esse token é carregado no cabeçalho Authorization da solicitação.This token is carried in the Authorization header of the request.Por exemplo (o token foi reduzido para fins de brevidade):For example (the token has been shortened for brevity):

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.The Graph API performs authorization based on OAuth 2.0 permission scopes present in the 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).For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

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.In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows 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).For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

O Azure AD usa o protocolo de autenticação OAuth 2.0.Azure AD uses the OAuth 2.0 authentication protocol.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.You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

Endereçamento de ponto de extremidade Endpoint addressing

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.To perform operations with the Graph API, you send HTTP requests with a supported method - typically GET, POST, PATCH, PUT, or DELETE -- to an endpoint that targets the service, a resource collection, an individual resource, a navigation property of a resource, or a function or action exposed by the service.Pontos de extremidade são expressos como URLs.Endpoints are expressed as URLs.

O seguinte descreve o formato básico de um ponto de extremidade de API do Graph:The following describes the basic format of a Graph API endpoint:

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

Os componentes a seguir compõem a URL:The following components comprise the URL:

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.Note: In some cases, when reading resource collections, OData query parameters can be added to the request to filter, order, and page the result set.Para obter mais informações, consulte a seção Parâmetros de consulta OData neste tópico.For more information, see the OData query parameters section in this topic.

Identificador do locatário {tenant_id} Tenant identifier {tenant_id}

Você pode especificar o locatário de destino de uma solicitação de quatro maneiras:You can specify the target tenant of a request in one of four ways:

  • Pela ID do objeto de locatário.By tenant object ID.Um GUID que foi atribuído quando o locatário foi criado.The GUID that was assigned when the tenant was created.Pode ser encontrado na propriedade objectId do objeto TenantDetail.This can be found in the objectId property of the TenantDetail object.A URL a seguir mostra como tratar a coleção de recursos dos usuários usando a ID do objeto de locatário:The following URL shows how to address the users resource collection by using the tenant object ID:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Por nome de domínio verificado (registrado).By verified (registered) domain name.Um dos nomes de domínio que são registrados para o locatário.One of the domain names that are registered for the tenant.Eles podem ser encontrados na propriedade verifiedDomains do objeto TenantDetail.These can be found in the verifiedDomains property of the TenantDetail object.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:The following URL shows how to address the users resource collection of a tenant that has the domain contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Usando o alias myOrganization.By using the myOrganization alias.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.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.O alias não diferencia maiúsculas de minúsculas.The alias is not case sensitive.Ele substitui a ID de objeto ou o domínio de locatário na URL.It replaces the object ID or tenant domain in the URL.Quando o alias é usado, a Graph API deriva o locatário das reivindicações apresentadas no token anexado à solicitação.When the alias is used, Graph API derives the tenant from the claims presented in the token attached to the request.A URL a seguir mostra como tratar a coleção de recursos de usuários de um locatário usando este alias:The following URL shows how to address the users resource collection of a tenant using this alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.https://graph.windows.net/myorganization/users?api-version=1.6.

  • Usando o alias me.By using the me alias.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.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.O alias não diferencia maiúsculas de minúsculas.The alias is not case sensitive.Ele substitui a ID de objeto ou o domínio de locatário na URL.It replaces the object ID or tenant domain in the URL.Quando o alias é usado, a Graph API deriva o usuário das reivindicações apresentadas no token anexado à solicitação.When the alias is used, Graph API derives the user from the claims presented in the token attached to the request.A URL a seguir para tratar o usuário conectado usando este alias:The following URL to address the signed-in user using this alias:
    https://graph.windows.net/me?api-version=1.6.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.Note: You use me alias solely to target operations against the signed-in user.Para obter mais informações, consulte Signed-in User Operations (Operações de usuários conectados).For more information, see Signed-in User Operations.

Caminho do recurso {resource_path} Resource path {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.You specify the {resource_path} differently depending on whether you are targeting a resource collection, an individual resource, a navigation property of a resource, a function or action exposed on the tenant, or a function or action exposed on a resource.

DestinoTargetCaminhoPathExplicaçãoExplanation
Metadados de serviçoService Metadata/$metadataRetorna o documento de metadados do serviço.Returns the service metadata document.O exemplo a seguir tem como destino metadados de serviço que usam o locatário contoso.com:The following example targets service metadata using the contoso.com tenant:
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.Note: No authentication is necessary to read the service metadata.
Coleção de recursosResource collection/{resource_collection}Tem como alvo uma coleção de recursos, como usuários ou grupos no locatário.Targets a resource collection, such as users or groups in the tenant.Você pode usar esse caminho para ler recursos na coleção e, dependendo do tipo de recurso, criar um novo recurso no locatário.You can use this path to read resources in the collection, and, depending on the resource type, to create a new resource in the tenant.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.In many cases the result set returned by a read can be further refined by the addition of query parameters to filter, order, or page the results.O exemplo a seguir tem como destino a coleção de usuários:The following example targets the user collection:
https://graph.windows.net/myorganization/users?api-version=1.6
Recurso únicoSingle resource/{resource_collection}/{resource_id}Tem como destino um recurso específico em um locatário, como um usuário, contato organizacional ou grupo.Targets a specific resource in a tenant, such as a user, organizational contact, or group.Para a maioria dos recursos, resource_id é a ID de objeto.For most resources the resource_id is the object ID.Alguns recursos permitem especificadores adicionais. Por exemplo, os usuários também podem ser especificados pelo nome UPN.Some resources allow additional specifiers; for example, users can be also specified by user principal name (UPN).Dependendo do recurso, você pode usar esse caminho para obter as propriedades declaradas do recurso, modificar suas propriedades declaradas ou excluir o recurso.Depending on the resource, you can use this path to get the declared properties of the resource, to modify its declared properties, or to delete the resource.O exemplo a seguir tem como destino o usuário john@contoso.com:The following example targets the user john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Propriedade de navegação (objetos)Navigation property (objects)/{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.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Você pode usar esse caminho para retornar o objeto ou objetos referenciados pela propriedade de navegação de destino.You can use this path to return the object or objects referenced by the target navigation property.O exemplo a seguir tem como destino o gerente de john@contoso.com:The following example targets the manager of 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.Note: This form of addressing is only available for reads.
Propriedade de navegação (links)Navigation property (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.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Você pode usar essa forma de endereçamento para ler e modificar uma propriedade de navegação.You can use this form of addressing to both read and modify a navigation property.Em leituras, os objetos referenciados pela propriedade são retornados como um ou mais links no corpo da resposta.On reads, the objects referenced by the property are returned as one or more links in the response body.Em gravações, os objetos são especificados como um ou mais links no corpo da solicitação.On writes, the objects are specified as one or more links in the request body.O exemplo a seguir tem como destino a propriedade do gerente de john@contoso.com:The following example targets the manager property of 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árioFunctions or actions exposed on the tenant/{function_name}Tem como destino uma função ou ação exposta no locatário.Targets a function or action exposed at the tenant.Ações e funções normalmente são invocadas com uma solicitação POST e podem incluir um corpo de solicitação.Functions and actions are typically invoked with a POST Request and may include a request body.O exemplo a seguir tem como destino a função isMemberOf:The following example targets the isMemberOf function:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funções ou ações expostas em um recurso.Functions or actions exposed on a resource./{resource_collection}/{resource_id}/{function_name}Tem como destino uma função ou ação exposta em um recurso.Targets a function or action exposed on a resource.Ações e funções normalmente são invocadas com uma solicitação POST e podem incluir um corpo de solicitação.Functions and actions are typically invoked with a POST Request and may include a request body.O exemplo a seguir tem como destino a função getMemberGroups:The following example targets the getMemberGroups function:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Versão da API do Graph {api-version} Graph API version {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.You use the api-version query parameter to target a specific version of the Graph API for an operation.Esse parâmetro é necessário.This parameter is required.

O valor do parâmetro api-version pode ser:The value for the api-version parameter can be one of the following:

  • "beta""beta"
  • "1.6""1.6"
  • "1.5""1.5"
  • "2013/11/08""2013/11/08"
  • "2013/04/05""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:For example the following URL targets the user collection using Graph API version 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).For more information about versions and feature changes between versions, see Versioning.

Parâmetros de consulta OData OData query parameters

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.In many cases when you read a collection of resources, you can filter, sort, and page the result set by attaching OData query parameters to your request.

A API do Graph dá suporte aos seguintes parâmetros de consulta OData:The Graph API supports the following Odata query parameters:

  • $filter$filter
  • $batch$batch
  • $expand$expand
  • $orderby$orderby
  • $top$top
  • $skiptoken e previous-page$skiptoken and 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).See Supported Queries, Filters, and Paging Options for more information about supported OData query parameters and their limitations in the Graph API.

Cabeçalhos de solicitação e resposta Request and response headers

A tabela a seguir mostra cabeçalhos HTTP comuns usados em solicitações com a API do Graph.The following table shows common HTTP headers used in requests with the Graph API.Não é destinada a ser completa.It is not meant to be comprehensive.

Cabeçalho de solicitaçãoRequest HeaderDescriçãoDescription
AuthorizationAuthorizationObrigatório.Required.Um token de portador emitido pelo Active Directory do Azure.A bearer token issued by Azure Active Directory.Consulte Autenticação e autorização neste tópico para obter mais informações.See Authentication and Authorization in this topic for more information.
Content-TypeContent-TypeNecessário se o corpo da solicitação estiver presente.Required if request body is present.O tipo de mídia do conteúdo do corpo da solicitação.The media type of the content in the request body.Use application/json.Use application/json.Podem ser incluídos parâmetros com o tipo de mídia.Parameters may be included with the media type.
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.Note: application/atom+xml and application/xml (for links) are supported but are not recommended both for performance reasons and because support for XML will be deprecated in a future release.
Content-LengthContent-LengthNecessário se o corpo da solicitação estiver presente.Required if request body is present.O comprimento da solicitação em bytes.The length of the request in bytes.

A tabela a seguir mostra cabeçalhos HTTP comuns retornados em respostas pela API do Graph.The following table shows common HTTP headers returned in responses by the Graph API.Não é destinada a ser completa.It is not meant to be comprehensive.

Cabeçalho de respostaResponse HeaderDescriçãoDescription
Content-TypeContent-TypeO tipo de mídia do conteúdo no corpo da resposta.The media type of the content in the response body.O padrão é application/json.The default is application/json.Solicitações de fotos em miniatura do usuário retornam image/jpeg por padrão.Requests for user thumbnail photos return image/jpeg by default.
LocalLocationRetornados em respostas a solicitações POST que criam um novo recurso (objeto) no diretório.Returned in responses to POST requests that create a new resource (object) in the directory.Contém o URI do recurso recém-criado.Contains the URI of the newly created resource.
ocp-aad-diagnostics-server-nameocp-aad-diagnostics-server-nameO identificador do servidor que executou a operação solicitada.The identifier for the server that performed the requested operation.
ocp-aad-session-keyocp-aad-session-keyA chave que identifica a sessão atual no serviço de diretório.The key that identifies the current session with the directory service.

No mínimo, recomendamos que você faça o seguinte para cada solicitação:At a minimum, we recommend you do the following for each request:

  1. Registre um carimbo de data/hora preciso do envio da solicitação.Log an accurate time stamp of the request submission.
  2. Envie e registre o client-request-id.Send and log the client-request-id.
  3. Registre o código da resposta HTTP e request-id.Log the HTTP response code and request-id.

Fornecer informações nos logs ajudará a Microsoft a solucionar problemas quando você pedir ajuda ou suporte.Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

Corpos de solicitação e respostaRequest and response bodies

Corpos de solicitação para solicitações PUT, PATCH e POST podem ser enviados em conteúdos JSON ou XML.Request bodies for POST, PATCH, and PUT requests can be sent in JSON or XML payloads.As respostas do servidor podem ser retornadas em conteúdos JSON ou XML.Server responses can be returned in JSON or XML payloads.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.You can specify the payload in request bodies by using the Content-Type request header and in responses by using the Accept request header.

É 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.We strongly recommend that you use JSON payloads in requests and responses with the Graph API. This is both for performance reasons and because XML will be deprecated in a future release.

Recursos avançadosAdvanced features

As seções anteriores discutem a formatação das solicitações e respostas básicas com a API do Graph.The preceding sections discussed the formatting of basic requests and responses with the Graph API.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.More advanced features may add additional query string parameters or have significantly different request and response bodies than the basic operations discussed previously in this topic.

Esses recursos incluem:These features include:

  • Processamento em lotes: a API do Graph dá suporte ao processamento em lotes.Batch Processing: The Graph API supports batching.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.Sending requests in batches reduces round trips to the server, which reduces network overhead and helps your operations complete more quickly.Para obter mais informações sobre o processamento em lotes com a API do Graph, consulte Batch Processing (Processamento em lotes).For more information about batch processing with the Graph API, see Batch Processing.
  • Consulta diferencial: a API do Graph dá suporte à execução de consultas diferenciais.Differential Query: The Graph API supports performing differential queries.A consulta diferencial permite retornar alterações feitas em entidades específicas em um locatário entre solicitações emitidas em momentos diferentes.Differential query allows you to return changes to specific entities in a tenant between requests issued at different times.Normalmente, esse recurso é usado para sincronizar um repositório local com alterações no locatário.This feature is often used to sync a local store with changes on the tenant.Para obter mais informações sobre a consulta diferencial com a API do Graph, consulte Differential Query (Consulta diferencial).For more information about differential query with the Graph API, see Differential Query.

Recursos adicionais Additional resources

© 2018 Microsoft