Comparar os pontos de extremidade das APIs REST do Microsoft Graph e do Outlook
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.
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.
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. |
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.
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
.
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.
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ãoMail.Read
incluindohttps://graph.microsoft.com/Mail.Read
no parâmetroscope
. - 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ãoMail.Read
incluindohttps://outlook.office.com/Mail.Read
no parâmetroscope
.
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.
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.
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
.
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 |
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.
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
.
Vejamos um exemplo simples. Neste cenário, um aplicativo Web solicita uma lista de mensagens na caixa de entrada do usuário.
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"
}
}
}
]
}
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"
}
}
}
]
}