Comparar os pontos de extremidade das APIs REST do Microsoft Graph e do Outlook

  • Artigo

As APIs REST do Outlook estão disponíveis no Microsoft Graph e no ponto de extremidade da API do Outlook (https://outlook.office.com/api). Geralmente, as APIs fornecem a mesma funcionalidade e usam os mesmos tipos de recursos.

Observação

As APIs REST do Outlook foram descontinuadas.

Os pontos de extremidade REST do Outlook serão totalmente desativados em março de 2024. Migre aplicativos existentes para usar o Microsoft Graph. Isso não inclui o público de token OAuth2 conforme descrito em Autenticar uma conexão IMAP, POP ou SMTP usando OAuth.

Qual ponto de extremidade devo usar?

Use o Microsoft Graph, o Outlook REST v2.0 está em seu caminho para desativar. O ponto de extremidade do Microsoft Graph permite acessar o Outlook e muitos outros serviços e recursos, incluindo outros serviços do Office 365, Enterprise Mobility + Security e Windows 10. Escolher o ponto de extremidade do Microsoft Graph permite que seu aplicativo obtenha um token de acesso que pode fornecer acesso a dados do Outlook e a outros recursos, sem a necessidade de fazer várias solicitações de token.

Diferenças de recursos

Alguns recursos podem estar atualmente disponíveis somente no ponto de extremidade do Outlook ou apenas em versão beta no Microsoft Graph.

Observação

Trabalhamos constantemente para incorporar todos os recursos disponíveis no ponto de extremidade do Outlook ao Microsoft Graph. Verifique periodicamente se esta lista foi atualizada.

Recurso Diferença entre pontos de extremidade
Tarefas do Outlook O acesso às tarefas dos usuários no Microsoft Graph está disponível por meio da API To Do
Notificações avançadas A API do Outlook permite aos desenvolvedores solicitar que campos específicos sejam incluídos na notificação de carga usando o parâmetro $select. Atualmente, o Microsoft Graph dá suporte a esse recurso somente no ponto de extremidade beta, planejando liberá-lo para v1.0 em breve.
Notificações de streaming A API do Outlook tem suporte para streaming de notificações na visualização, no ponto de extremidade beta. O Microsoft Graph não dá suporte a esse recurso e ele não faz parte do roteiro.

Mover o ponto de extremidade do Outlook para o Microsoft Graph

As APIs são muito semelhantes no ponto de extremidade do Microsoft Graph e no ponto de extremidade do Outlook. No entanto, há algumas diferenças que devem ser reconhecidas, especialmente se você estiver migrando para o Microsoft Graph ou usando os dois pontos de extremidade no mesmo aplicativo.

Versões da API

A API do Microsoft Graph oferece duas versões: v1.0 e beta, enquanto o Outlook oferece v1.0, v2.0 e beta. O Microsoft Graph v1.0 corresponde ao Outlook v2.0, e o Microsoft Graph beta corresponde ao Outlook beta.

Escopos OAuth

Embora os pontos de extremidade do Microsoft Graph e do Outlook dependam dos tokens emitidos pelo Azure AD, e as permissões usadas forem as mesmas, a forma na qual o aplicativo solicita essas permissões é ligeiramente diferente para cada ponto de extremidade.

Ponto de extremidade OAuth2 v2 do Azure

Aplicativos que usam o ponto de extremidade v2.0 do Azure AD para OAuth2 solicitam escopos de permissão no parâmetro scope em uma solicitação de token ou autenticação.

  • Para o Microsoft Graph, os aplicativos especificam permissões com o prefixo https://graph.microsoft.com/. Por exemplo, um aplicativo pode solicitar a permissão Mail.Read incluindo https://graph.microsoft.com/Mail.Read no parâmetro scope.
  • Para o ponto de extremidade do Outlook, os aplicativos especificam permissões com o prefixo https://outlook.office.com/. Por exemplo, um aplicativo pode solicitar a permissão Mail.Read incluindo https://outlook.office.com/Mail.Read no parâmetro scope.

Observação

Se um domínio não estiver incluído em um escopo, o Microsoft Graph será assumido por padrão.

Os tokens emitidos para um ponto de extremidade não são válidos para o outro. Além disso, você não pode combinar permissões para um ponto de extremidade com permissões para o outro em uma única solicitação.

O ponto de extremidade do Azure AD v2.0 só dá suporte ao fluxo de credenciais de cliente para o ponto de extremidade do Microsoft Graph. Aplicativos que precisem usar um token somente para aplicativo com o ponto de extremidade do Outlook devem usar o ponto de extremidade v1.0 do Azure AD.

Ponto de extremidade OAuth2 v1 do Azure

Aplicativos que usem o ponto de extremidade v1.0 do Azure AD especificam as permissões necessárias durante o registro do aplicativo no Portal do Azure.

  • Para o Microsoft Graph, escolha a API do Microsoft Graph ao adicionar permissões obrigatórias.
  • Para o ponto de extremidade do Outlook, escolha a API do Exchange Online do Office 365 ao adicionar permissões obrigatórias.

Nomes de propriedade de recursos

Os recursos são praticamente os mesmos entre o Microsoft Graph e o Outlook. No entanto, os dois pontos de extremidade lidam de forma diferente com a capitalização de nomes de propriedade. O Microsoft Graph usa camelCase para nomes de propriedades, enquanto o Outlook usa PascalCase. Para fazer traduções entre os dois programas, é preciso converter a capitalização. Os nomes de propriedades que são alterados são especificados na tabela abaixo.

Por exemplo, o recurso de mensagens do Microsoft Graph define propriedades como subject, from e receivedDateTime. No ponto de extremidade do Outlook, essas propriedades são nomeadas Subject, From e ReceivedDateTime.

Nomes de propriedades alterados

Os nomes de propriedades a seguir são diferentes entre o Microsoft Graph e o Outlook.

Tipo de recurso Propriedade do Microsoft Graph Propriedade Outlook
contact mobilePhone MobilePhone1

Acompanhar alterações (sincronização)

Os dois pontos de extremidade suportam conjuntos de consultas para alterações em relação a um estado de sincronização. Embora a funcionalidade seja a mesma, os métodos são um pouco diferentes.

Sobre o ponto de extremidade do Microsoft Graph, as alterações são consultadas usando consultas delta. Isso é implementado como uma função delta no conjunto.

No ponto de extremidade do Outlook, as alterações são consultadas adicionando um cabeçalho para consultas de conjunto de recursos normais.

Envio em lote

Ambos os pontos de extremidade oferecem suporte de lotes até 20 solicitações separadas em uma solicitação HTTP.

O processamento em lotes do Microsoft Graph codifica várias solicitações de API em um corpo JSON com um tipo de conteúdo de application/json.

Além do formato de corpo JSON, o processamento em lotes de ponto de extremidade do Outlook também dá suporte ao formato de corpo de várias partes com um tipo de conteúdo multipart/mixed.

Exemplo: recuperação de uma mensagem

Vejamos um exemplo simples. Neste cenário, um aplicativo Web solicita uma lista de mensagens na caixa de entrada do usuário.

Microsoft Graph

Primeiro, o aplicativo pede o logon do usuário para autorizar o aplicativo. Como o aplicativo usa o escopo do Microsoft Graph Mail.Read, a URL de autorização é da seguinte forma:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Assim que o aplicativo tiver um token de acesso, enviará a seguinte solicitação:

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

O servidor retorna esta resposta:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

Primeiro, o aplicativo pede o logon do usuário para autorizar o aplicativo. Como o aplicativo usa o escopo do Outlook https://outlook.office.com/Mail.Read, a URL de autorização é a seguinte:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Assim que o aplicativo tiver um token de acesso, enviará a seguinte solicitação:

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

O servidor retorna esta resposta:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}