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

El espacio de nombres Office.context.mailbox.item proporciona acceso a muchos de los campos comunes de mensajes y citas. Sin embargo, en algunos escenarios, es posible que un complemento tenga que acceder a datos que no están expuestos por el espacio de nombres. Por ejemplo, el complemento puede basarse en propiedades personalizadas que establece una aplicación externa, o necesita buscar el buzón del usuario para obtener mensajes del mismo remitente. En estos escenarios, las API de REST de Outlook es el método recomendado para recuperar la información.

Importante

Desuso de los puntos de conexión rest de Outlook v2.0 y beta

Los puntos de conexión rest de Outlook v2.0 y beta quedarán totalmente en desuso el 31 de marzo de 2024. Sin embargo, los complementos hospedados en AppSource y de publicación privada pueden usar el servicio REST hasta que finalice el soporte extendido para Outlook 2019 el 14 de octubre de 2025. El tráfico de estos complementos se identifica automáticamente para la exención. Esta exención también se aplica a los nuevos complementos desarrollados después de la fecha de retirada.

Aunque los complementos pueden usar el servicio REST hasta 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph. Para obtener instrucciones, consulte Comparación de puntos de conexión de LA API REST de Microsoft Graph y Outlook.

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 cierto incluso si el complemento especifica el nivel de permiso de elemento de lectura y escritura en su manifiesto.

Si el complemento requerirá acceso de escritura al elemento actual u otros elementos del buzón del usuario, el complemento debe especificar el permiso de buzón de lectura y escritura. nivel 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. Este se obtiene de la propiedad Office.context.mailbox.item.itemId, pero deben realizarse algunas comprobaciones para asegurarse de que se trata de un identificador con formato para REST.

• En Outlook en 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.

Importante

En el caso de las implementaciones de Exchange locales, se produce un error en las solicitudes del lado cliente que usan AJAX o bibliotecas similares porque CORS no se admite en esa configuración del 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.
  });
}

Vea también

• Para obtener un ejemplo que llame a las API de REST desde un complemento de Outlook, vea command-demo en GitHub.
• Las API de REST de Outlook también están disponibles a través del extremo de Microsoft Graph, pero hay algunas diferencias importantes, incluida la forma en la que el complemento obtiene un token de acceso. Para obtener más información, vea API de REST de Outlook mediante Microsoft Graph.