Consultar o Microsoft Graph usando REST

  • 3 minutos

O Microsoft Graph é uma API Web RESTful que permite acessar recursos de serviço do 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 APIs são definidos em seus subnamespaces, como a API de registros de chamadas que define recursos como callRecord em microsoft.graph.callRecords.

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

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 seguinte exemplo:

{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 para o Microsoft Graph.
  • {version} - a versão da API do Microsoft Graph que seu aplicativo está usando.
  • {resource} - o recurso no Microsoft Graph ao qual você está fazendo referência.
  • {query-parameters} - opções de consulta OData opcionais ou parâmetros do método REST que personalizam a resposta.

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

  • Código de status - um código de status HTTP que indica sucesso ou falha.
  • Mensagem de resposta - os dados que você solicitou ou o resultado da operação. A mensagem de resposta pode estar vazia para algumas operações.
  • nextLink - se sua solicitação retornar muitos dados, você precisará percorrê-la usando a URL retornada 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 dá suporte aos métodos a seguir.

Método Descrição
GET Ler dados de um recurso.
POST Crie um novo recurso ou executar uma ação.
PATCH Atualizar um recurso com novos valores.
PUT Substituir um recurso por um novo.
DELETE Remover um recurso.
  • Para os métodos CRUD GET e DELETE, nenhum corpo de solicitação é necessário.
  • Os métodos POST, PATCH e PUT exigem um corpo de solicitação, especificado no formato JSON, que contenha informações adicionais. Por exemplo, os valores das propriedades do recurso.

Versão

O Microsoft Graph atualmente dá suporte a 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 versão prévia. Como podemos introduzir alterações recentes em nossas APIs beta, recomendamos que você use a versão beta somente para testar os 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, normalmente definido com propriedades. As entidades diferem dos tipos complexos por sempre incluir uma propriedade de id.

Sua URL inclui o recurso com o qual você está interagindo na solicitação, como me, usuário, grupo, unidade e site. Geralmente, os recursos de nível superior também incluem relações, 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 email, use me/sendMail .

Cada recurso pode exigir permissões diferentes para acessá-lo. Muitas vezes, você precisará 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, confira o tópico de referência do método.

Parâmetros de consulta

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 filter a seguir restringe as mensagens retornadas com a propriedade emailAddress de jon@contoso.com.

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

Outros recursos

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