Use as APIs REST do Outlook de um suplemento do Outlook

O namespace Office.context.mailbox.item fornece acesso a vários dos campos comuns das mensagens e dos compromissos. No entanto, em alguns cenários, um suplemento pode precisar acessar dados que não são expostos pelo namespace. Por exemplo, o suplemento pode depender de propriedades personalizadas definidas por um aplicativo externo ou ela precisa pesquisar na caixa de correio do usuário pelas mensagens do mesmo remetente. Nessas situações, as APIs REST do Outlook é o método recomendado para recuperar as informações.

Importante

Preterimento de pontos de extremidade do Outlook REST v2.0 e beta

Os pontos de extremidade REST v2.0 e beta do Outlook serão totalmente preteridos em 31 de março de 2024. No entanto, suplementos hospedados no AppSource podem usar o serviço REST até que o suporte estendido termine para o Outlook 2019 em 14 de outubro de 2025. O tráfego desses suplementos é identificado automaticamente para isenção. Essa isenção também se aplica a novos suplementos desenvolvidos após a data de descomissionamento.

Embora os suplementos possam usar o serviço REST até 2025, incentivamos você a migrar seus suplementos para usar o Microsoft Graph. Para obter diretrizes, confira Comparar pontos de extremidade da API REST do Microsoft Graph e do Outlook.

Obter um token de acesso

As APIs REST exigem um token portador no cabeçalho Authorization. Normalmente, os aplicativos usam fluxos de OAuth2 para recuperar um token. No entanto, os suplementos podem recuperar um token sem implementar o OAuth2 usando o novo método Office.context.mailbox.getCallbackTokenAsync introduzido no conjunto de requisitos da caixa de correio 1.5.

Ao definir a opção isRest como true, você poderá solicitar um token compatível com APIs REST.

Permissões de suplementos e escopo do token

É importante levar em consideração o nível de acesso que seu suplemento precisará com as APIs REST. Na maioria dos casos, o token retornado por getCallbackTokenAsync fornecerá acesso somente leitura ao item atual. Isso é verdadeiro mesmo se o suplemento especificar o nível de permissão do item de leitura/gravação em seu manifesto.

Se o suplemento exigirá acesso de gravação ao item atual ou a outros itens na caixa de correio do usuário, seu suplemento deverá especificar a permissão de caixa de correio de leitura/gravação. nível em seu manifesto. Nesse caso, o token retornado conterá acesso de leitura/gravação às mensagens, aos eventos e aos contatos do usuário.

Exemplo

Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
  if (result.status === "succeeded") {
    const accessToken = result.value;

    // Use the access token.
    getCurrentItem(accessToken);
  } else {
    // Handle the error.
  }
});

Obter a ID do item

Para recuperar o item atual pela REST, o suplemento precisará da ID do item, formatada corretamente para REST. Isto é obtido pela propriedade Office.context.mailbox.item.itemId, mas algumas verificações devem ser feitas para garantir que seja uma ID formatada para REST.

• No Outlook em dispositivos móveis, o valor retornado por é uma ID formatada por Office.context.mailbox.item.itemId REST e pode ser usado como está.
• Em outros clientes do Outlook, o valor retornado por Office.context.mailbox.item.itemId é uma ID formatada para EWS e deve ser convertida usando o método Office.context.mailbox.convertToRestId.
• Também é necessário converter a ID do anexo em uma ID com formato REST para usá-la. As IDs devem ser convertidas porque as IDs EWS podem conter valores não seguros para URL que causarão problemas ao REST.

O suplemento pode determinar em qual cliente do Outlook ele será carregado verificando a propriedade Office.context.mailbox.diagnostics.hostName.

Exemplo

function getItemRestId() {
  if (Office.context.mailbox.diagnostics.hostName === 'OutlookIOS') {
    // itemId is already REST-formatted.
    return Office.context.mailbox.item.itemId;
  } else {
    // Convert to an item ID for API v2.0.
    return Office.context.mailbox.convertToRestId(
      Office.context.mailbox.item.itemId,
      Office.MailboxEnums.RestVersion.v2_0
    );
  }
}

Obter a URL da API REST

A informação final que seu suplemento precisa para chamar a API REST é o nome do host que deve usar para enviar solicitações de API. Estas informações estão na propriedade Office.context.mailbox.restUrl.

Exemplo

// Example: https://outlook.office.com
const restHost = Office.context.mailbox.restUrl;

Chamar a API

Depois que seu suplemento tiver o token de acesso, a ID do item e a URL da API REST, ele poderá passar essas informações para um serviço de back-end que chama a API REST ou pode chamá-la diretamente usando o AJAX. O exemplo a seguir chama a API REST do Email do Outlook para obter a mensagem atual.

Importante

Para implantações locais do Exchange, as solicitações do lado do cliente usando a AJAX ou bibliotecas semelhantes falham porque o CORS não tem suporte nessa configuração de servidor.

function getCurrentItem(accessToken) {
  // Get the item's REST ID.
  const itemId = getItemRestId();

  // Construct the REST URL to the current item.
  // Details for formatting the URL can be found at
  // https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-messages.
  const getMessageUrl = Office.context.mailbox.restUrl +
    '/v2.0/me/messages/' + itemId;

  $.ajax({
    url: getMessageUrl,
    dataType: 'json',
    headers: { 'Authorization': 'Bearer ' + accessToken }
  }).done(function(item){
    // Message is passed in `item`.
    const subject = item.Subject;
    ...
  }).fail(function(error){
    // Handle error.
  });
}

Confira também

• Confira um exemplo que chama as APIs REST de um suplemento do Outlook em command-demo no GitHub.
• As APIs REST do Outlook também estão disponíveis por meio do ponto de extremidade do Microsoft Graph, mas existem algumas diferenças importantes, inclusive como o suplemento obtém um token de acesso. Saiba mais em API REST do Outlook pelo Microsoft Graph.