Use as APIs REST do Outlook de um suplemento do Outlook

Os pontos de extremidade da API REST v2.0 do Outlook foram preteridos. Para o desenvolvimento de novos suplementos, use a API REST do Microsoft Graph . Este artigo aborda a abordagem da API REST para suplementos existentes que ainda não foram migrados para o Microsoft Graph.

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 de 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 que seu suplemento especifique o nível de permissão de 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, o suplemento deverá especificar o nível de permissão da caixa de correio de leitura/gravação 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. Isso é obtido da itemId propriedade (MessageRead, AppointmentRead), mas algumas verificações devem ser feitas para garantir que seja uma ID formatada em REST.

• No Outlook em dispositivos móveis, o valor retornado por é uma ID formatada no Office.context.mailbox.item.itemId REST e pode ser usado no estado em que se encontra.
• 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://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

• Usar a API REST do Microsoft Graph de um suplemento do Outlook
• Autenticação e autorização em suplementos do Outlook
• Habilitar o SSO em um Suplemento do Office usando a autenticação de aplicativo aninhado