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.

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.

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://video2.skills-academy.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.