Habilitar carpetas compartidas y escenarios de buzón compartido en un complemento de Outlook

  • Artículo

En este artículo se describe cómo habilitar carpetas compartidas (también conocidas como acceso delegado) y escenarios de buzón compartido en el complemento de Outlook, incluidos los permisos que admite la API de JavaScript de Office.

Nota:

La compatibilidad con carpetas compartidas se introdujo en el conjunto de requisitos 1.8, mientras que la compatibilidad con buzones compartidos se introdujo en el conjunto de requisitos 1.13. Para obtener información sobre la compatibilidad con clientes para estas características, consulte Clientes y plataformas compatibles.

Plataformas y clientes admitidos

En la tabla siguiente se muestran las combinaciones de cliente y servidor admitidas para esta característica, incluida la actualización acumulativa mínima necesaria cuando corresponda. No se admiten combinaciones excluidas.

Cliente Exchange Online Exchange 2019 local
(Actualización acumulativa 1 o posterior)		 Exchange 2016 local
(Actualización acumulativa 6 o posterior)		 Exchange 2013 local
Windows
Carpetas compartidas: versión 1910 (compilación 12130.20272) o posterior

Buzones compartidos: versión 2304 (compilación 16327.20248) o posterior		 Compatible Apoyado* Apoyado* Apoyado*
Mac
Compilación 16.47 o posterior		 Compatible Compatible Compatible Compatible
Explorador web (interfaz de usuario moderna de Outlook) Compatible No aplicable No aplicable No aplicable
Explorador web (interfaz de usuario clásica de Outlook) No aplicable No aplicable No aplicable No aplicable

Nota:

* La compatibilidad con esta característica en un entorno de Exchange local está disponible a partir de Outlook en windows versión 2206 (compilación 15330.20000) para el canal actual y la versión 2207 (compilación 15427.20000) para el canal mensual de empresa.

Configuraciones admitidas

En las secciones siguientes se describen las configuraciones admitidas para buzones compartidos y carpetas compartidas. Es posible que las API de características no funcionen como se esperaba en otras configuraciones. Seleccione la plataforma que desea aprender a configurar.

Carpetas compartidas

El propietario del buzón debe proporcionar primero acceso a un delegado mediante una de las siguientes opciones.

Una vez proporcionado el acceso, el delegado debe seguir las instrucciones que se describen en la sección "Agregar el buzón de otra persona a su perfil" del artículo Administración de elementos de calendario y correo de otra persona.

Buzones compartidos

Los administradores del servidor exchange pueden crear y administrar buzones compartidos para que los conjuntos de usuarios accedan. se admiten entornos de Exchange Exchange Online y locales.

Una característica Exchange Server conocida como "asignación automática" está activada de forma predeterminada, lo que significa que, posteriormente, el buzón compartido debería aparecer automáticamente en la aplicación de Outlook de un usuario después de que Outlook se haya cerrado y vuelto a abrir. Sin embargo, si un administrador ha desactivado la asignación automática, el usuario debe seguir los pasos manuales descritos en la sección "Agregar un buzón compartido a Outlook" del artículo Abrir y usar un buzón compartido en Outlook.

Advertencia

NO inicie sesión en el buzón compartido con una contraseña. Las API de características no funcionarán en ese caso.

Para obtener más información sobre dónde hacen y no se activan los complementos en general, consulte la sección Elementos de buzón disponibles para complementos de la página de información general de los complementos de Outlook.

Permisos admitidos

En la tabla siguiente se describen los permisos que admite la API de JavaScript de Office para delegados y usuarios de buzones compartidos.

Permiso Valor Description
Lectura 1 (000001) Puede leer elementos.
Escritura 2 (000010) Puede crear elementos.
DeleteOwn 4 (000100) Solo puede eliminar los elementos que crearon.
DeleteAll 8 (001000) Puede eliminar cualquier elemento.
EditOwn 16 (010000) Solo puede editar los elementos que creó.
EditAll 32 (100000) Puede editar cualquier elemento.

Nota:

Actualmente, la API admite la obtención de permisos existentes, pero no la configuración de permisos.

El objeto DelegatePermissions se implementa mediante una máscara de bits para indicar los permisos. Cada posición de la máscara de bits representa un permiso determinado y, si se establece 1 en , el usuario tiene el permiso correspondiente. Por ejemplo, si el segundo bit de la derecha es 1, el usuario tiene permiso de escritura . Puede ver un ejemplo de cómo comprobar un permiso específico en la sección Realizar una operación como usuario de buzón de correo compartido o delegado más adelante en este artículo.

Sincronización entre clientes de carpetas compartidas

Las actualizaciones de un delegado en el buzón del propietario suelen sincronizarse entre buzones inmediatamente.

Sin embargo, si se usaron operaciones REST o Exchange Web Services (EWS) para establecer una propiedad extendida en un elemento, estos cambios podrían tardar unas horas en sincronizarse. En su lugar, se recomienda usar el objeto CustomProperties y las API relacionadas para evitar este retraso. Para obtener más información, consulte la sección de propiedades personalizadas del artículo "Obtener y establecer metadatos en un complemento de Outlook".

Importante

En un escenario de delegado, no puede usar EWS con los tokens proporcionados actualmente por office.js API.

Configuración del manifiesto

Para habilitar carpetas compartidas y escenarios de buzón compartido en el complemento, debe habilitar los permisos necesarios en el manifiesto.

En primer lugar, para admitir llamadas REST desde un delegado, el complemento debe solicitar el permiso de buzón de lectura y escritura . El marcado varía en función del tipo de manifiesto.

  • Manifiesto XML: establezca el <elemento Permissions> en ReadWriteMailbox.
  • Manifiesto unificado para Microsoft 365 (versión preliminar): establezca la propiedad "name" de un objeto en la matriz "authorization.permissions.resourceSpecific" en "Mailbox.ReadWrite.User".

En segundo lugar, habilite la compatibilidad con carpetas compartidas. El marcado varía en función del tipo de manifiesto.

Agregue un objeto adicional a la matriz "authorization.permissions.resourceSpecific" y establezca su propiedad "name" en "Mailbox.SharedFolder".

"authorization": {
  "permissions": {
    "resourceSpecific": [
      ...
      {
        "name": "Mailbox.SharedFolder",
        "type": "Delegated"
      },
    ]
  }
},

Realizar una operación como usuario delegado o de buzón compartido

Puedes obtener las propiedades compartidas de un elemento en el modo Compose o Read llamando al método item.getSharedPropertiesAsync . Esto devuelve un objeto SharedProperties que actualmente proporciona los permisos del usuario, la dirección de correo electrónico del propietario, la dirección URL base de la API REST y el buzón de destino.

En el ejemplo siguiente se muestra cómo obtener las propiedades compartidas de un mensaje o una cita, comprobar si el usuario del buzón de correo compartido o delegado tiene permiso de escritura y realizar una llamada REST.

function performOperation() {
  Office.context.mailbox.getCallbackTokenAsync({
      isRest: true
    },
    function (asyncResult) {
      if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
        Office.context.mailbox.item.getSharedPropertiesAsync({
            // Pass auth token along.
            asyncContext: asyncResult.value
          },
          function (asyncResult1) {
            let sharedProperties = asyncResult1.value;
            let delegatePermissions = sharedProperties.delegatePermissions;

            // Determine if user can do the expected operation.
            // E.g., do they have Write permission?
            if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
              // Construct REST URL for your operation.
              // Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
              // Update <operation> placeholder with actual operation.
              let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
  
              $.ajax({
                  url: rest_url,
                  dataType: 'json',
                  headers:
                  {
                    "Authorization": "Bearer " + asyncResult1.asyncContext
                  }
                }
              ).done(
                function (response) {
                  console.log("success");
                }
              ).fail(
                function (error) {
                  console.log("error message");
                }
              );
            }
          }
        );
      }
    }
  );
}

Sugerencia

Como delegado, puede usar REST para obtener el contenido de un mensaje de Outlook adjunto a una publicación de grupo o elemento de Outlook.

Controlar la llamada a REST en elementos compartidos y no compartidos

Si desea llamar a una operación REST en un elemento, independientemente de si el elemento se comparte o no, puede usar la getSharedPropertiesAsync API para determinar si el elemento está compartido. Después, puede construir la dirección URL de REST para la operación mediante el objeto adecuado.

if (item.getSharedPropertiesAsync) {
  // In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
  // Add-ins don't activate on shared items in mobile so no need to handle.

  // Perform operation for shared item.
} else {
  // In general, this isn't a shared item, so construct the REST URL using info from the Call REST APIs article:
  // https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api

  // Perform operation for non-shared item.
}

Limitaciones

En función de los escenarios del complemento, hay algunas limitaciones que debe tener en cuenta al controlar las situaciones de carpetas compartidas o buzones compartidos.

Modo de redacción de mensajes

En el modo redacción de mensajes, getSharedPropertiesAsync no se admite en Outlook en la Web ni en Windows, a menos que se cumplan las condiciones siguientes.

a. Delegar acceso/Carpetas compartidas

  1. El propietario del buzón inicia un mensaje. Puede ser un mensaje nuevo, una respuesta o un reenvío.
  2. Guardan el mensaje y lo mueven de su propia carpeta Borradores a una carpeta compartida con el delegado.
  3. El delegado abre el borrador de la carpeta compartida y, a continuación, continúa redactando.

b. Buzón compartido (solo se aplica a Outlook en Windows)

  1. Un usuario de buzón compartido inicia un mensaje. Puede ser un mensaje nuevo, una respuesta o un reenvío.
  2. Guardan el mensaje y lo mueven de su propia carpeta Borradores a una carpeta del buzón compartido.
  3. Otro usuario de buzón compartido abre el borrador del buzón compartido y, a continuación, continúa redactando.

El mensaje está ahora en un contexto compartido y los complementos que admiten estos escenarios compartidos pueden obtener las propiedades compartidas del elemento. Una vez enviado el mensaje, normalmente se encuentra en la carpeta Elementos enviados del remitente.

REST y EWS

El complemento puede usar REST. Para habilitar el acceso REST al buzón del propietario o al buzón compartido según corresponda, el 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 (versión preliminar): establezca la propiedad "name" de un objeto en la matriz "authorization.permissions.resourceSpecific" en "Mailbox.ReadWrite.User".

No se admite EWS.

Buzón de usuario o compartido oculto en una lista de direcciones

Si un administrador ocultó una dirección de usuario o buzón compartido de una lista de direcciones como la lista global de direcciones (GAL), los elementos de correo afectados abiertos en el informe Office.context.mailbox.item de buzón de correo se muestran como null. Por ejemplo, si el usuario abre un elemento de correo en un buzón compartido que está oculto en la GAL, Office.context.mailbox.item representar ese elemento de correo es null.

Consulte también