Visão geral do uso das APIs REST do Outlook

  • Artigo

Dica

Experimente as chamadas REST de exemplo no Explorador do Graph. Você pode usar sua própria conta ou uma de nossas contas de teste. Depois que terminar de explorar a API, volte para esta etapa e selecione sua plataforma favorita à esquerda. Vamos percorrer as etapas para escrever um aplicativo simples a fim de recuperar mensagens da sua caixa de entrada.

Se sua plataforma preferencial não estiver listada, continue lendo esta página. Revisitaremos o mesmo conjunto de etapas usando as solicitações HTTP.

O objetivo deste guia é percorrer o processo de chamar a API de Email do Outlook para recuperar mensagens no Office 365 e no Outlook.com. Diferentemente dos guias de introdução específicos de plataforma, este guia se concentra em solicitações e respostas OAuth e REST. Ele abordará a sequência de solicitações e respostas que um aplicativo usa para autenticar e recuperar as mensagens.

Este tutorial usará o Microsoft Graph para chamar a API de email. A Microsoft recomenda usar o Microsoft Graph para acessar email, calendário e contatos do Outlook. Você deverá usar as APIs do Outlook diretamente (via https://outlook.office.com/api) somente se precisar de um recurso que não está disponível nos pontos de extremidade do Graph.

Com as informações deste guia, você pode fazer a implementação em qualquer linguagem ou plataforma capaz de enviar solicitações HTTP.

Usar OAuth2 para autenticar

Para chamar a API Mail, o aplicativo requer um token de acesso da plataforma de identidade da Microsoft. Use um dos fluxos OAuth 2.0 com suporte para obter um token de acesso.

Chamando a API de Email

Depois que o aplicativo obtém um token de acesso, ele está pronto para chamar a API de Email. A Referência da API de Email tem todos os detalhes. Já que esse aplicativo está recuperando mensagens, ele usará uma solicitação HTTP GET para a URL https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages. Isso recuperará as mensagens da caixa de entrada.

Refinamento da solicitação

Os aplicativos podem controlar o comportamento de solicitações GET usando parâmetros de consulta OData. É recomendável que os aplicativos usem esses parâmetros para limitar o número de resultados retornados e limitar os campos retornados para cada item. Vejamos um exemplo.

Pense em um aplicativo que exibe as mensagens em uma tabela. A tabela exibe apenas o assunto, o remetente e a data e hora em que a mensagem foi recebida. A tabela exibe um máximo de 25 linhas e deve estar classificada de modo que a mensagem recebida mais recentemente esteja na parte superior.

Para conseguir isso, o aplicativo usa os seguintes parâmetros de consulta:

  • O parâmetro $select é usado para especificar somente os campos subject, from e receivedDateTime.
  • O parâmetro $top é usado para especificar no máximo 25 itens.
  • O parâmetro $orderby é usado para classificar os resultados pelo campo receivedDateTime.

Isso resulta na solicitação a seguir.

Solicitação à API de Email para mensagens na caixa de entrada

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA

Resposta da API de Email

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

Agora que você viu como fazer chamadas à API de Email, pode usar a referência de API para criar outros tipos de chamada que seu aplicativo tenha que fazer. No entanto, tenha em mente que seu aplicativo precisa ter as permissões apropriadas configuradas no registro de aplicativo para as chamadas feitas.