Usar los servicios Web Exchange (EWS) desde un complemento de Outlook

Artículo
11/13/2024

El complemento de Outlook puede usar Exchange Web Services (EWS) desde un entorno que ejecuta Exchange Server (local). EWS es un servicio web que está disponible en el servidor que proporciona la ubicación de origen para la interfaz de usuario del complemento. En este artículo se proporciona un ejemplo que muestra cómo un complemento de Outlook puede solicitar información de EWS.

Importante

Los tokens de Exchange heredados están en desuso. A partir de febrero de 2025, comenzaremos a desactivar los tokens heredados de identidad de usuario y devolución de llamada de Exchange para Exchange Online inquilinos. Para ver la escala de tiempo y los detalles, consulte nuestra página de preguntas más frecuentes. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro.

La forma de llamar a un servicio web varía en función de dónde se encuentre el servicio web. En las tablas siguientes se enumeran las distintas formas en que puede llamar a un servicio web en función de la ubicación.

Ubicación del servicio web	Forma de llamar al servicio web
Servidor Exchange que hospeda el buzón de correo del cliente	Use el método mailbox.makeEwsRequestAsync para llamar a las operaciones de EWS que los complementos admiten. El servidor Exchange que hospeda el buzón de correo también expone EWS.
Servidor web que proporciona la ubicación de origen para la interfaz de usuario del complemento	Llame al servicio web con técnicas de JavaScript estándar. El código de JavaScript en el marco de la interfaz de usuario se ejecuta en el contexto del servidor web que proporciona la interfaz de usuario. Por lo tanto, puede llamar a los servicios web de ese servidor sin causar ningún error de scripting entre sitios.
Todas las demás ubicaciones	Cree un proxy para el servicio web en el servidor web que proporciona la ubicación de origen para la interfaz de usuario. Si no proporciona un proxy, los errores de scripting entre sitios impedirán que se ejecute el complemento. Una manera de proporcionar un proxy es con JSON/P. Para obtener más información, consulte Privacidad y seguridad de complementos para Office.

Uso del método makeEwsRequestAsync para tener acceso a las operaciones de EWS

Importante

Las llamadas y operaciones de EWS no se admiten en complementos que se ejecutan en Outlook en Android y en iOS.

Puede usar el método mailbox.makeEwsRequestAsync para realizar una solicitud EWS al servidor exchange local que hospeda el buzón del usuario.

Los EWS son compatibles con diversas operaciones que se llevan a cabo en un servidor Exchange, por ejemplo, operaciones del nivel de elemento para copiar, buscar, actualizar o enviar un elemento, y operaciones del nivel de carpeta para crear, obtener o actualizar una carpeta. Para realizar una operación EWS, cree una solicitud SOAP XML para esa operación. Cuando finaliza la operación, obtiene una respuesta SOAP XML que contiene datos relevantes para la operación. Las solicitudes y respuestas SOAP de EWS siguen el esquema definido en el archivo Messages.xsd . Al igual que otros archivos de esquema EWS, el archivo Message.xsd se encuentra en el directorio virtual de IIS que hospeda EWS.

Para usar el makeEwsRequestAsync método para iniciar una operación EWS, proporcione lo siguiente:

XML de la solicitud SOAP para esa operación EWS como argumento para el parámetro de datos .
Una función de devolución de llamada (como argumento de devolución de llamada ).
Cualquier dato de entrada opcional para esa función de devolución de llamada (como argumento userContext ).

Una vez completada la solicitud SOAP de EWS, Outlook llama a la función de devolución de llamada con un argumento, que es un objeto AsyncResult . La función de devolución de llamada puede tener acceso a dos propiedades del AsyncResult objeto: la value propiedad , que contiene la respuesta SOAP XML de la operación EWS, y, opcionalmente, la asyncContext propiedad , que contiene los datos pasados como userContext parámetro. Normalmente, la función de devolución de llamada analiza el XML en la respuesta SOAP para obtener la información pertinente y procesa esa información en consecuencia.

Sugerencias para analizar las respuestas de EWS

Al analizar una respuesta SOAP desde una operación EWS, tenga en cuenta los siguientes problemas dependientes del explorador.

Especifique el prefijo de un nombre de etiqueta al usar el método getElementsByTagName DOM para incluir compatibilidad con Internet Explorer y la vista web trident.

getElementsByTagName se comporta de forma diferente en función del tipo de explorador. Por ejemplo, una respuesta de EWS puede contener el siguiente XML (con formato y abreviado para mostrar).

<t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
PropertyName="MyProperty" 
PropertyType="String"/>
<t:Value>{
...
}</t:Value></t:ExtendedProperty>

El código, como en el siguiente, funcionaría en un explorador como Chrome para obtener el XML incluido en las ExtendedProperty etiquetas.

const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("ExtendedProperty")
});

Para la vista web tridente (Internet Explorer), debe incluir el t: prefijo del nombre de etiqueta, como se indica a continuación.

const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
});

Use la propiedad textContent DOM para obtener el contenido de una etiqueta en una respuesta de EWS, como se indica a continuación.
```
content = $.parseJSON(value.textContent);
```
Es posible que otras propiedades como innerHTML no funcionen en la vista web de Trident (Internet Explorer) para algunas etiquetas en una respuesta de EWS.

Ejemplo

En el ejemplo siguiente se llama makeEwsRequestAsync a para usar la operación GetItem para obtener el asunto de un elemento. En este ejemplo se incluyen las tres funciones siguientes.

getSubjectRequest : toma un identificador de elemento como entrada y devuelve el XML para que la solicitud SOAP llame GetItem al elemento especificado.
sendRequest : llama getSubjectRequest a para obtener la solicitud SOAP del elemento seleccionado y, a continuación, pasa la solicitud SOAP y la función de devolución de llamada, callback, para makeEwsRequestAsync obtener el asunto del elemento especificado.
callback : procesa la respuesta SOAP, que incluye cualquier asunto y otra información sobre el elemento especificado.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

Operaciones de EWS compatibles con los complementos

Los complementos de Outlook pueden acceder a un subconjunto de operaciones que están disponibles en EWS a través del makeEwsRequestAsync método . Si no está familiarizado con las operaciones de EWS y cómo usar el makeEwsRequestAsync método para acceder a una operación, comience con un ejemplo de solicitud SOAP para personalizar el argumento de datos .

A continuación se describe cómo puede usar el makeEwsRequestAsync método .

En el XML, sustituya todos los identificadores de elementos y los atributos de operaciones de EWS correspondientes por los valores adecuados.
Incluya la solicitud SOAP como argumento para el parámetro de datos de makeEwsRequestAsync.
Especifique una función de devolución de llamada y llame a makeEwsRequestAsync.
En la función de devolución de llamada, compruebe los resultados de la operación en la respuesta SOAP.
Use los resultados de la operación de EWS de acuerdo con sus necesidades.

En la siguiente tabla se enumeran las operaciones de EWS compatibles con los complementos. Para ver ejemplos de solicitudes y respuestas de SOAP, elija el vínculo para cada operación. Para más información sobre operaciones de EWS, vea Operaciones de EWS en Exchange.

Operación de EWS	Descripción
Operación CopyItem	Copia los elementos especificados y coloca los elementos nuevos en una carpeta designada en el almacén de Exchange.
Operación CreateFolder	Crea carpetas en la ubicación especificada en el almacén de Exchange.
Operación CreateItem	Crea los elementos especificados en el almacén de Exchange.
Operación ExpandDL	Muestra los miembros pertenecientes a las listas de distribución.
Operación FindConversation	Enumera una lista de conversaciones en la carpeta especificada en el almacén de Exchange.
Operación FindFolder	Busca subcarpetas de una carpeta identificada y devuelve un conjunto de propiedades que describen el conjunto de subcarpetas.
Operación FindItem	Identifica a los elementos que se encuentran en una carpeta especificada en el almacén de Exchange.
Operación GetConversationItems	Obtiene uno o varios conjuntos de elementos que están organizados en nodos en una conversación.
Operación GetFolder	Obtiene las propiedades y los contenidos especificados de las carpetas del almacén de Exchange.
Operación GetItem	Obtiene las propiedades y los contenidos especificados de los elementos del almacén de Exchange.
Operación GetUserAvailability	Proporciona información detallada sobre la disponibilidad de un conjunto de usuarios, salas y recursos en un período de tiempo especificado.
Operación MarkAsJunk	Mueve mensajes de correo a la carpeta Correo electrónico no deseado y agrega o quita de la lista de remitentes bloqueados a los remitentes de los mensajes, según corresponda.
Operación MoveItem	Mueve elementos a una sola carpeta de destino en el almacén de Exchange.
Operación ResolveNames	Resuelve direcciones de correo y nombres para mostrar ambiguos.
Operación SendItem	Envía mensajes de correo electrónico que se encuentran en el almacén de Exchange.
Operación UpdateFolder	Modifica las propiedades de las carpetas existentes en el almacén de Exchange.
Operación UpdateItem	Modifica las propiedades de los elementos existentes en el almacén de Exchange.

Nota:

Los elementos fai (información asociada a carpetas) no se pueden actualizar (ni crear) desde un complemento. Estos mensajes ocultos se almacenan en una carpeta y se usan para almacenar una amplia variedad de configuraciones y datos auxiliares. Si se intenta usar la operación UpdateItem, se producirá un error ErrorAccessDenied, similar al siguiente: "La extensión de Office no tiene permiso para actualizar este tipo de elemento". Como alternativa, puede usar la API administrada de EWS para actualizar estos elementos desde un cliente de Windows o una aplicación de servidor. Se recomienda precaución, ya que las estructuras de datos de tipo servicio pueden cambiar y pueden interrumpir su solución.

Consideraciones de autenticación y permisos para makeEwsRequestAsync

Cuando se usa el makeEwsRequestAsync método , la solicitud se autentica mediante las credenciales de la cuenta de correo electrónico del usuario actual. El makeEwsRequestAsync método administra las credenciales automáticamente para que no tenga que proporcionar credenciales de autenticación con la solicitud.

Nota:

El administrador del servidor debe usar el cmdlet New-WebServicesVirtualDirectory o el cmdlet Set-WebServicesVirtualDirectory para establecer el parámetro trueOAuthAuthentication en en el directorio EWS del servidor de acceso de cliente para permitir que el makeEwsRequestAsync método realice solicitudes de EWS.

Para usar el método , el makeEwsRequestAsync complemento debe solicitar el permiso de buzón de lectura y escritura en el manifiesto. El marcado varía en función del tipo de manifiesto.

Manifiesto de solo complemento: establezca el <elemento Permissions> en ReadWriteMailbox.
Manifiesto unificado para Microsoft 365: establezca la propiedad "name" de un objeto en la matriz "authorization.permissions.resourceSpecific" en "Mailbox.ReadWrite.User".

Para obtener información sobre cómo usar el permiso de buzón de lectura y escritura , consulte permiso de buzón de lectura y escritura.

Vea también

Consulte lo siguiente para crear servicios back-end para complementos mediante ASP.NET Web API.

Compartir a través de