Llamar a servicios web desde un complemento de Outlook

Artículo
04/12/2024

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

Importante

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

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 ningún proxy, los errores de scripting entre sitios impedirán la ejecución del 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

Puede usar el método mailbox.makeEwsRequestAsync para crear una solicitud de EWS al servidor Exchange 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 finalice la operación, obtendrá una respuesta SOAP XML que contendrá los datos correspondientes a la operación. Las solicitudes y las respuestas SOAP de EWS siguen el esquema definido en el archivo Messages.xsd. Al igual que otros archivos de esquema de EWS, el archivo Message.xsd se encuentra en el directorio virtual de IIS que hospeda los 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 de 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 cualquier información relevante 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 getElementsByTagNameDOM , para incluir la 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, function(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, function(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:

La información asociada a la carpeta no puede actualizarse (ni crearse) a partir de 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 XML: 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.