Usar a API REST do Outlook (beta)

  • Artigo

Aplica-se a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Observação

Use o Microsoft Graph para criar cenários mais ricos para os serviços do Microsoft 365, incluindo o Outlook. Descubra como fazer a transição para a API REST baseada no Microsoft Graph do Outlook.

A API REST do Outlook inclui os seguintes subconjuntos para permitir acesso aos dados da caixa de correio dos usuários no Office 365, no Hotmail.com, no Live.com, no MSN.com, no Outlook.com e no Passport.com.

A tabela abaixo lista a primeira versão em que a funcionalidade principal de cada subconjunto foi disponibilizada. Observe que dentro de um subconjunto poderão ser adicionados novos recursos e APIs em uma versão posterior.

Subconjunto da API Versões disponíveis
Envio em lote de várias chamadas de API v2.0, beta
API de Calendário v2.0, v1.0, beta
API de Contatos v2.0, v1.0, beta
API de Extensões de dados v2.0, beta
API de Propriedades estendidas v2.0, beta
API de Email v2.0, v1.0, beta
API de Notificações por Push v2.0, beta
API de Notificações de streaming (versão prévia) beta
API de Pessoas beta
API de Tarefas v2.0, beta
API da Foto do usuário v2.0, beta

Observação

O restante deste artigo descreve informações comuns aplicáveis ​​a todos os subconjuntos da API REST do Outlook. Para simplificar a referência, o restante deste artigo usa o Outlook.com para incluir contas nos domínios Hotmail.com, Live.com, MSN.com, Outlook.com e Passport.com.

Registrar e autenticar seu aplicativo

Seu aplicativo deve efetuar o registro e autenticar o usuário para usar a API REST do Outlook para ter acesso aos dados de caixa de correio de um usuário:

  1. Primeiro, registre seu aplicativo para obter acesso à API REST do Outlook. Assim você pode implementar as chamadas de API no aplicativo.

  2. Em tempo de execução, obtenha autorização do usuário e faça solicitações REST à API para acessar a caixa de correio do usuário.

Atualmente, existem duas abordagens para lidar com o registro do aplicativo e a autorização do usuário:

Ponto de extremidade de autenticação do AD do Azure v2

O ponto de extremidade de autenticação do Azure AD v2 simplifica a criação de um aplicativo que funcione com tanto com as contas organizacionais quanto com as contas pessoais da Microsoft. Ele permite que usuários do trabalho, da escola e de contas pessoais façam login com um único botão.

Este modelo de programação convergido é a abordagem mais recente e é composto dos seguintes procedimentos:

Essa abordagem oferece uma experiência de usuário contínua de registro do aplicativo e autorização do usuário para obter os tokens de acesso aos dados da caixa de correio dos usuários no Office 365 e/ou no Outlook.com. Se você estiver desenvolvendo um aplicativo para o Outlook.com, precisa usar essa abordagem.

Em vez de solicitar permissões durante o registro do aplicativo, o ponto de extremidade de autenticação v2 permite que você solicite as permissões necessárias dinamicamente com base nas ações do usuário em tempo de execução.

Esse modelo de programação convergente consiste em vários componentes, portanto, se você usar um componente, deverá usar os outros também.

Para saber mais, consulte exemplos de como começar, e Como autenticar as APIs do Office 365 e do Outlook.com usando o ponto de extremidade de autenticação v2.

Importante

Ao criar ou atualizar um aplicativo, certifique-se de que ele pode manipular as caixas de correio do Outlook.com já habilitadas para acesso pela API REST do Outlook e também aquelas que estão aguardando para serem habilitadas. Saiba mais sobre como testar e lidar com esses cenários no Outlook.com.

Registro e autenticação usando o Azure AD e OAuth

Essa é uma abordagem anterior para acessar dados de caixa de correio apenas no Office 365. Se você planeja acessar dados no Outlook.com ou criar um novo aplicativo do Office 365, deve usar o ponto de extremidade de autenticação v2.

Por enquanto, para acessar os dados da caixa de correio do Office 365, você pode continuar registrando um aplicativo no Azure AD como antes, especificando as permissões no escopo apropriado que seu aplicativo requer. Em tempo de execução, seu aplicativo pode continuar usando o Azure AD e OAuth para autenticar solicitações de aplicativos. Você pode encontrar detalhes em Conceitos de autenticação de aplicativos do Office 365. Você deve ter um plano de atualização.

Com essa abordagem, você pode optar por acessar a API REST do Outlook chamando-a diretamente em seus aplicativos do Office 365 ou usando as bibliotecas de cliente do Office 365.

Plano de atualização

O ponto de extremidade de autenticação v2 foi promovido da versão prévia para o status Disponibilidade Geral (GA) para desenvolvedores do Outlook e do Outlook.com.

Se você tiver um aplicativo em produção que acesse os dados da caixa de correio do Office 365 ou se estiver criando um novo aplicativo para o Office 365 ou para o Outlook.com, planeje usar o ponto de extremidade de autenticação v2 junto com o ponto de extremidade mais recente do Outlook (https://outlook.office.com/, veja abaixo) para escrever apenas um conjunto de códigos para os usuários organizacionais do Office 365 e pessoais do Outlook.com.

Se você tiver um aplicativo em produção que usa a API do Windows Live para acessar os dados da caixa de correio do Outlook.com, será necessário reescrever o aplicativo para usar o ponto de extremidade de autenticação v2 e a API REST do Outlook. Como a API do Windows Live está sendo preterida para o Outlook.com e as caixas de correio dos usuários do Outlook.com estão sendo habilitadas para a API REST do Outlook, esses usuários receberão mensagens de erro HTTP 404 ao tentar executar aplicativos que acessam a API do Windows Live.

Por outro lado, a API REST do Outlook abre novas oportunidades—você pode escolher dentre uma lista de linguagens, como Node, Python, Swift, Java e assim por diante, gravar o aplicativo uma vez e capturar usuários do Outlook.com e do Office 365 na internet e em dispositivos iOS, Android ou Windows.

Observação

Se você pretende que seu aplicativo em produção continue acessando apenas dados da caixa de correio do Outlook.com, pode continuar usando os mesmos escopos do Windows Live para acessar a maior parte da API REST do Outlook. Para mais informações, consulte Como usar escopos do Windows Live e a API REST do Outlook para acessar dados da caixa de correio do Outlook.com.

Não importa qual a sua abordagem para efetuar o registro do aplicativo e a autorização do usuário, ou se o seu aplicativo acessa os dados da caixa de correio do Office 365 ou do Outlook.com. O ponto de extremidade mais recente do Outlook REST está em produção e você pode começar a usá-lo em suas chamadas REST à API assim que estiver pronto:

https://outlook.office.com/api/{version}/{user_context}

O ponto de extremidade REST do Outlook continuará funcionando por um tempo apenas para os dados da caixa de correio do Office 365:

https://outlook.office365.com/api/{version}/{user_context}

Veja mais sobre ações REST suportadas, pontos de extremidade e versões abaixo.

Importante

  • A autorização básica não é mais suportada pelo ponto de extremidade da API REST do Outlook https://outlook.office.com. Use o ponto de extremidade de autenticação v2 ou o Azure AD para operações de autorização e autenticação para um aplicativo que usa o novo ponto de extremidade da API REST do Outlook.
  • Para um obter desempenho ideal ao usar o novo ponto de extremidade REST do Outlook, adicione um cabeçalho x-AnchorMailbox para cada solicitação e configure-o com o endereço de email do usuário. Por exemplo: x-AnchorMailbox:john@contoso.com
  • Como a habilitação das caixas de correio no Outlook.com para a API REST do Outlook é feita ao longo do tempo, sua conta do Outlook.com pode demorar um pouco para ser habilitada. Para testar seu aplicativo acessando dados em caixas de correio do Outlook.com que já tiverem sido habilitadas, você poderá solicitar uma conta nova e ativada de visualização de desenvolvedor do Outlook.com enviando um e-mail para outlookdev@microsoft.com.
  • Se o seu aplicativo acessa dados da caixa de correio do Outlook.com, ele deve lidar com cenários em que a caixa de correio do usuário ainda não foi habilitada para a API REST do Outlook. Nessas situações, você receberá uma mensagem erro como essa ao fazer uma solicitação REST:
    • Erro HTTP: 404
    • Código de erro: MailboxNotEnabledForRESTAPI ou MailboxNotSupportedForRESTAPI
    • Mensagem de erro: “A API REST ainda não é suportada para esta caixa de correio.
  • Para exemplos de código que usam o ponto de extremidade de autenticação v2, consulte dev.outlook.com.

Como usar escopos do Windows Live e a API REST do Outlook para acessar dados da caixa de correio do Outlook.com

Se o seu aplicativo em produção para o Outlook.com usar escopos do Windows Live e você não pretende acessar dados da caixa de correio do Office 365, pode continuar usando esses escopos do Windows Live com a maior parte da API REST do Outlook. A tabela abaixo mostra como os escopos do Windows Live são mapeados para os escopos da API REST do Outlook. Observe que não há um mapeamento direto do escopo do Windows Live para o Mail.Read; seu aplicativo pode usar wl.imap para acessar as operações da API REST do Outlook que exigem o Mail.Read.

Escopos do Windows Live Escopos da API REST do Outlook
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

Ações e pontos de extremidade REST suportados

Para interagir com a API REST do Outlook, você deve enviar solicitações HTTP que usem um método suportado: GET, POST, PATCH ou DELETE. O corpo das solicitações POST e PATCH e as respostas do servidor são enviados em conteúdo JSON.

Os nomes de recursos de URL e os parâmetros de consulta não diferenciam maiúsculas de minúsculas. No entanto, os valores que você atribui, as IDs de entidade e outros valores codificados em base64 diferenciam maiúsculas e minúsculas.

Todas as solicitações da API REST do Outlook usam o seguinte formato de URL raiz:

https://outlook.office.com/api/{version}/{user_context}

Com a autorização apropriada do usuário, a API REST nessa URL raiz fornece acesso aos dados de caixa de correio no Office 365 e no Outlook.com. O restante deste artigo descreve a API REST neste ponto de extremidade.

Se você tem o código que usa a URL raiz pré-existente https://outlook.office365.com/api/{version}/{user_context}, seu código continuará funcionando por algum tempo para o Office 365, mas você deve planejar alternar para a nova URL raiz.

Importante

Para um desempenho ideal, ao fazer uma solicitação REST usando a nova URL raiz, adicione um cabeçalho x-AnchorMailbox e configure-o com o endereço de email do usuário. Além disso, você deve tratar os casos em que a caixa de correio de um usuário do Outlook.com ainda não foi habilitada para a API REST do Outlook - teste os códigos de erro MailboxNotEnabledForRESTAPI e MailboxNotSupportedForRESTAPI. Veja mais informações aqui.

Notas para desenvolvedores na China

Versões suportadas da API

{version} representa a versão da API REST do Outlook na URL raiz especificada. Você pode especificar um dos seguintes valores:

  • v1.0. Esta é a versão mais antiga no status de disponibilidade geral (GA) e pode ser usada no código de produção. Um exemplo de URL é http://outlook.office.com/api/v1.0/me/events.

  • v2.0. Essa versão também está no status GA e pode ser usada no código de produção. Um exemplo de URL é http://outlook.office.com/api/v2.0/me/events. Essa versão inclui alterações que podem fazer a versão v1.0 deixar de funcionar e conjuntos de API adicionais que foram aperfeiçoados e promovidos da versão prévia para o status GA.

  • beta. Esta é uma versão prévia e não deve ser usada no código em produção. Um exemplo de URL é http://outlook.office.com/api/beta/me/events. Esta versão inclui as APIs mais recentes em GA, bem como conjuntos de API adicionais que estão em versão prévia e podem ser alterados antes da finalização.

A maioria das operações REST na API REST do Outlook é suportada e se comporta da mesma maneira descrita nas versões listadas acima.

Usuário de destino

Com exceção da API REST de Foto de usuário, {user_context} é o usuário conectado, pois as solicitações da API REST do Outlook são sempre executadas em nome do usuário atual.

Para a API REST de Foto de usuário, {user_context} pode ser o usuário conectado ou um usuário especificado por um ID de usuário.

Independentemente do conjunto de API REST do Outlook, você pode especificar o {user_context} em solicitações REST de uma das seguintes formas:

  • Com o atalho me: /api/{version}/me. A URL raiz ficaria https://outlook.office.com/api/{version}/me.

  • Com o formato users/{upn} para passar o UPN ou um endereço de proxy do usuário conectado, como: /api/beta/users/sadie@contoso.com. Neste exemplo, a URL raiz ficaria https://outlook.office.com/api/beta/users/sadie@contoso.com.

  • Com o formato users/{AAD_userId@AAD_tenandId}, utilizando o ID do usuário e o ID do locatário no Azure Active Directory. Por exemplo, users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77. A URL raiz ficaria https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

O uso é uma questão de preferência.

Nas respostas do servidor, o contexto do usuário é identificado neste formato: users/{AAD_userId@AAD_tenandId}.

Acessando o item em uma coleção

A API REST do Outlook oferece suporte a duas formas de especificar um item em uma coleção de entidades. Eles são avaliados de forma idêntica, portanto, o uso é uma questão de preferência.

  • No segmento da URL após a coleção, por exemplo: /api/{version}/me/events/AAMkAGI3...

  • Entre parênteses como uma cadeia de caracteres entre aspas, por exemplo: /api/{version}/me/events('AAMkAGI3...')

Uso de uma biblioteca cliente para acessar a API REST do Outlook

As bibliotecas de cliente da API do Office 365 tornam mais fácil interagir com a API REST:

Elas ajudam a gerenciar os tokens de autenticação e simplificam o código necessário para consultar e consumir dados no Office 365.

Término da utilização do ponto de extremidade em versão prévia

Se você já estiver usando https://outlook.office.com/api ou https://outlook.office365.com/api como URL raiz
para acessar a API REST do Outlook, essa desativação não afetará o seu código. Continue lendo se você ainda estiver usando o ponto de extremidade da versão prévia https://outlook.office365.com/ews/odata.

A API REST do Outlook foi movida da versão prévia para a versão v1.0 em disponibilidade geral em outubro de 2014. Para concluir essa transição, encerramos o antigo ponto de extremidade em versão prévia https://outlook.office365.com/ews/odata em 15 de outubro de 2015.

Exigimos que todos os aplicativos e serviços usando o ponto de extremidade antigo https://outlook.office365.com/ews/odata se mudassem para https://outlook.office.com/api/v1.0 até 15 de outubro de 2015. A versão v1.0 é o ponto de extremidade de disponibilidade geral mínima (GA) a ser usado até essa data.

Como alternativa, você pode usar preferencialmente o ponto de extremidade v2.0 em GA (https://outlook.office.com/api/v2.0) ou o ponto de extremidade em versão prévia (https://outlook.office.com/api/beta) para testar as APIs mais recentes em versão prévia. Lembre-se que, em geral, as APIs em versão prévia podem ser alteradas antes da finalização. Se você usá-las, esteja preparado para verificar os recursos no seu aplicativo e fazer as alterações apropriadas. Quando as APIs em versão prévia forem finalizadas, você também poderá acessar essas melhorias em um ponto de extremidade em GA.

Próximas etapas

Prossiga para usar a API REST do Outlook: