Consultar o Microsoft Graph usando REST

  • 3 minutos

O Microsoft Graph é uma API Web RESTful que permite acessar recursos do serviço Microsoft Cloud. Depois de registrar seu aplicativo e obter tokens de autenticação para um usuário ou serviço, você pode fazer solicitações para a API do Microsoft Graph.

A API do Microsoft Graph define a maioria de seus recursos, métodos e enumerações no namespace OData, microsoft.graph, nos metadados do Microsoft Graph. Alguns conjuntos de API são definidos em seus subnamespaces, como a API de registros de chamada, que define recursos como callRecord em microsoft.graph.callRecords.

A menos que explicitamente especificado no tópico correspondente, assuma que tipos, métodos e enumerações fazem parte do microsoft.graph namespace.

Chamar um método de API REST

Para ler ou gravar em um recurso, como um usuário ou uma mensagem de email, construa uma solicitação semelhante ao exemplo a seguir:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Os componentes de uma solicitação incluem:

  • {HTTP method} - O método HTTP usado na solicitação ao Microsoft Graph.
  • {version} - A versão da API do Microsoft Graph que seu aplicativo está usando.
  • {resource} - O recurso no Microsoft Graph que você está referenciando.
  • {query-parameters} - Opções opcionais de consulta OData ou parâmetros do método REST que personalizam a resposta.

Depois de fazer uma solicitação, uma resposta é retornada que inclui:

  • Código de status - Um código de status HTTP que indica sucesso ou falha.
  • Mensagem de resposta - Os dados solicitados ou o resultado da operação. A mensagem de resposta pode estar vazia para algumas operações.
  • nextLink - Se o seu pedido devolve vários dados, tem de o percorrer utilizando o URL devolvido em @odata.nextLink.

Métodos HTTP

O Microsoft Graph usa o método HTTP em sua solicitação para determinar o que sua solicitação está fazendo. A API suporta os seguintes métodos.

Método Description
GET Ler dados de um recurso.
POST Crie um novo recurso ou execute uma ação.
PATCH Atualize um recurso com novos valores.
PUT Substitua um recurso por um novo.
DELETE Remova um recurso.
  • Para os métodos GET CRUD e DELETE, não é necessário nenhum corpo de solicitação.
  • Os POSTmétodos , PATCH, e requerem PUT um corpo de solicitação especificado no formato JSON que contém informações adicionais. Como os valores das propriedades do recurso.

Versão

Microsoft Graph atualmente suporta duas versões: v1.0 e beta.

  • v1.0 inclui APIs geralmente disponíveis. Use a versão v1.0 para todos os aplicativos de produção.
  • beta inclui APIs que estão atualmente em visualização. Como podemos introduzir alterações significativas em nossas APIs beta, recomendamos que você use a versão beta apenas para testar aplicativos que estão em desenvolvimento; não use APIs beta em seus aplicativos de produção.

Recurso

Um recurso pode ser uma entidade ou um tipo complexo, comumente definido com propriedades. As entidades diferem dos tipos complexos sempre incluindo uma propriedade id .

Seu URL inclui o recurso com o qual você está interagindo na solicitação, como me, usuário, grupo, unidade e site. Muitas vezes, os recursos de nível superior também incluem relacionamentos, que você pode usar para acessar outros recursos, como me/messages ou me/drive. Você também pode interagir com recursos usando métodos, por exemplo, para enviar um e-mail, use me/sendMail.

Cada recurso pode exigir permissões diferentes para acessá-lo. Muitas vezes, você precisa de um nível mais alto de permissões para criar ou atualizar um recurso do que para lê-lo. Para obter detalhes sobre as permissões necessárias, consulte o tópico de referência do método.

Parâmetros de consultas

Os parâmetros de consulta podem ser opções de consulta do sistema OData ou outras cadeias de caracteres que um método aceita para personalizar sua resposta.

Você pode usar opções opcionais de consulta do sistema OData para incluir mais ou menos propriedades do que a resposta padrão. Você pode filtrar a resposta para itens que correspondem a uma consulta personalizada ou fornecer outros parâmetros para um método.

Por exemplo, adicionar o parâmetro a seguir filter restringe as mensagens retornadas com a emailAddress propriedade de jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Outros recursos

A seguir estão links para algumas ferramentas que você pode usar para criar e testar solicitações usando APIs do Microsoft Graph.