Usar a API do Microsoft Graph

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

Espaço de nomes (namespace) OData

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

A menos que especificado explicitamente no tópico correspondente, considere tipos, métodos e enumerações fazem parte do espaço de nomes microsoft.graph.

Método de chamada à API REST

Para ler de ou gravar em um recurso como um usuário ou uma mensagem de email, você constrói uma solicitação semelhante ao visto abaixo:

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

Os componentes de uma solicitação incluem:

• {Método HTTP} – O método HTTP usado na solicitação para o Microsoft Graph.
• {versão} – A versão da API do Microsoft Graph que seu aplicativo está usando.
• {recurso} – O recurso no Microsoft Graph ao qual você está fazendo referência.
• {Parâmetros-da-consultas} –Opções de consulta OData opcionais ou parâmetros do método REST que personalizam a resposta.
• {cabeçalhos} – Solicitar cabeçalhos que personalizam a solicitação. Pode ser opcional ou obrigatório dependendo da API.

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

• Código de status – um código de status HTTP que indica o sucesso ou o fracasso. Para obter detalhes sobre os códigos de erro HTTP, veja Erros.
• Mensagem de resposta – Os dados solicitados ou o resultado da operação. A mensagem de resposta pode estar vazia para algumas operações.
• @odata.nextLink - Se sua solicitação retornar muitos dados, você precisará fazer a página usando a URL retornada em @odata.nextLink. Para obter detalhes, veja Paginação.
• Cabeçalhos de resposta – informações adicionais sobre a resposta, como o tipo de conteúdo retornado e a id de solicitação que você pode usar para correlacionar a resposta à solicitação.

Métodos HTTP

O Microsoft Graph usa o método HTTP em sua solicitação para determinar o que sua solicitação está fazendo. Dependendo do recurso, a API pode dar suporte a operações, incluindo ações, funções ou operações CRUD descritas abaixo.

• Nos métodos CRUD, GET e DELETE, nenhum corpo de solicitação é obrigatório.
• Os métodos POST, PATCH e PUT precisam de um corpo de solicitação, normalmente especificado em formato JSON que contém informações adicionais, como os valores das propriedades do recurso.

Versão

O Microsoft Graph atualmente é compatível com duas versões: v1.0 e beta.

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

Estamos sempre buscando comentários sobre nossas APIs beta. Para fornecer comentários ou solicitar recursos, consulte nosso fórum de ideias sobre a Plataforma para Desenvolvedores do Microsoft 365.

Para saber mais sobre as versões da API, veja Suporte e controle de versão.

Recurso

Um recurso pode ser uma entidade ou tipo complexo, normalmente definido com propriedades. As entidades são diferentes de tipos complexos, incluindo sempre uma propriedade de id.

Sua URL incluirá um ou mais recursos com que você está interagindo na solicitação, como me, usuário, grupo, unidade e site. Frequentemente, cada um dos recursos de nível superior também inclui relações, que podem ser usadas para acessar recursos adicionais, como me/messages ou me/drive. Você também pode interagir com os recursos usando métodos; por exemplo, para enviar um email, use me/sendMail. Para mais informações, confira Acessar dados e métodos ao navegar no Microsoft Graph.

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 lê-lo. Para obter detalhes sobre as permissões necessárias, consulte o tópico de referência do método.

Para obter detalhes sobre permissões, veja Referência de permissões.

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 a resposta.

Use parâmetros de consulta do sistema OData para incluir mais ou menos propriedades do que a resposta padrão, filtrar a resposta para itens que correspondem a uma consulta personalizada ou oferecem parâmetros adicionais para um método.

Por exemplo, adicionar o seguinte parâmetro de filter restringe as mensagens retornadas para apenas aquelas com a propriedade de emailAddress do jon@contoso.com.

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

Para obter mais informações sobre as opções de consulta OData, confira Usar parâmetros de consulta para personalizar respostas.

Com exceção das opções de consulta OData, alguns métodos exigem valores de parâmetro especificados como parte da URL da consulta. Por exemplo, é possível obter uma coleção de eventos ocorridos durante um período de tempo no calendário de um usuário, consultando a relação calendarView de um usuárioe especificando o período dos valores startDateTime e endDateTime como parâmetros da consulta:

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Cabeçalhos

O Microsoft Graph dá suporte a cabeçalhos padrão HTTP e cabeçalhos personalizados.

APIs específicas podem exigir que cabeçalhos adicionais sejam incluídos na solicitação. Por outro lado, o Microsoft Graph sempre retornará cabeçalhos obrigatórios, como o request-id cabeçalho na resposta, ou alguns cabeçalhos podem ser específicos para algumas APIs ou funcionalidades, por exemplo, o Retry-After cabeçalho é incluído quando seu aplicativo atinge limites de limitação; ou o Location cabeçalho incluído para operações de longa execução.

Os cabeçalhos são insensíveis a casos, conforme definido no rfc 9110 , a menos que especificado explicitamente caso contrário.

Ferramentas para interagir com o Microsoft Graph

Explorador do Graph

O Explorador do Graph é uma ferramenta baseada na Web que você pode usar para criar e testar solicitações usando as APIs do Microsoft Graph. Você pode acessar o Explorador do Graph em: https://developer.microsoft.com/graph/graph-explorer.

Você pode acessar os dados de demonstração sem fazer logon, ou pode fazer logon em um locatário de sua preferência. Use as etapas a seguir para criar a solicitação:

1. Selecione o método HTTP.
2. Selecione a versão da API que você deseja usar.
3. Digite a consulta na caixa de texto da solicitação.
4. Selecione Executar consulta.

O exemplo a seguir mostra uma solicitação que retorna informações sobre usuários no locatário da demonstração:

Os exemplos de consultas são fornecidos no Explorador do Graph para permitir que você execute solicitações comuns mais rapidamente. Para ver os exemplos disponíveis, selecione mostrar mais exemplos. Selecione Ativado para o conjunto de exemplos que deseja ver e, depois de fechar a janela de seleção, você deverá ver uma lista de solicitações predefinidas.

Um código de status e uma mensagem são exibidos depois que uma solicitação é enviada, e a resposta é exibida na guia Visualização de resposta.

Postman

O Postman é uma ferramenta que você pode usar para criar e testar solicitações usando as APIs do Microsoft Graph. Você pode baixar o Postman em: https://www.getpostman.com/. Para interagir com o Microsoft Graph no Postman, use a coleção do Microsoft Graph.

Para obter mais informações, confira Usar o Postman com a API do Microsoft Graph.

Próximas etapas

Você está pronto para começar a trabalhar com o Microsoft Graph. Experimente o Início rápido, ou comece a usar um de nossos SDKs e exemplos de código.