Usar las API de REST de Outlook desde un complemento de Outlook

Los puntos de conexión de la API de REST v2.0 de Outlook están en desuso. Para desarrollar nuevos complementos, use la API REST de Microsoft Graph en su lugar. En este artículo se describe el enfoque de API de REST para los complementos existentes que aún no se han migrado a Microsoft Graph.

Obtener un token de acceso

Las API de REST de Outlook necesitan un token de portador en el encabezado Authorization. Normalmente, las aplicaciones usan flujos de OAuth2 para recuperar un token. Sin embargo, los complementos pueden recuperar un token sin implementar OAuth2 mediante el nuevo método Office.context.mailbox.getCallbackTokenAsync introducido en el conjunto de requisitos de buzón 1.5.

Al establecer la opción isRest en true, puede solicitar un token compatible con las API de REST.

Agregar permisos y ámbito del token

Es importante tener en cuenta el nivel de acceso que necesitará el complemento mediante las API de REST. En la mayoría de los casos, el token que se ha devuelto mediante getCallbackTokenAsync, proporcionará acceso de solo lectura únicamente al elemento actual. Esto es así incluso si el complemento especifica el nivel de permiso de elemento de lectura y escritura en su manifiesto.

Si el complemento va a requerir acceso de escritura al elemento actual u otros elementos del buzón del usuario, el complemento debe especificar el nivel de permiso de buzón de lectura y escritura en su manifiesto. En este caso, el token devuelto contendrá acceso de lectura y escritura a los contactos, eventos y mensajes del usuario.

Ejemplo

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.
  }
});

Obtener el identificador de elemento

Para recuperar el elemento actual mediante REST, el complemento necesitará el identificador del elemento, con un formato adecuado para REST. Esto se obtiene de la itemId propiedad (MessageRead, AppointmentRead), pero se deben realizar algunas comprobaciones para asegurarse de que es un identificador con formato REST.

• En Outlook para dispositivos móviles, el valor devuelto por Office.context.mailbox.item.itemId es un identificador con formato REST y se puede usar tal cual.
• En otros clientes de Outlook, el valor devuelto por Office.context.mailbox.item.itemId es un id. con formato para EWS y tiene que convertirse con el método Office.context.mailbox.convertToRestId.
• Tenga en cuenta que debe convertir también el ID de datos adjuntos a un ID con formato REST para usarlo. El motivo por el que se deben convertir los id. es que los ID de EWS pueden contener valores seguros sin direcciones URL que provocarán problemas para REST.

El complemento puede determinar qué cliente de Outlook está cargado al comprobar la propiedad Office.context.mailbox.diagnostics.hostName.

Ejemplo

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
    );
  }
}

Obtener la dirección URL de la API de REST

La última información que el complemento necesita para llamar a la API de REST es el nombre de host que debe usar para enviar solicitudes de API. Esta información se encuentra en la propiedad Office.context.mailbox.restUrl.

Ejemplo

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

Llamar a la API

Cuando el complemento tenga el token de acceso, el identificador del elemento y la dirección URL de la API de REST, podrá pasar esa información a un servicio de back-end que llame a la API de REST o llamarla directamente con AJAX. En el ejemplo siguiente se llama a la API de REST de Correo de Outlook para obtener el mensaje actual.

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.
  });
}

Vea también

• Usar la API REST de Microsoft Graph desde un complemento de Outlook
• Autenticación y autorización en los complementos de Outlook
• Habilitar SSO en un complemento de Office mediante la autenticación de aplicaciones anidadas