Solicitar permisos para el uso de la API en los complementos

En este artículo se describen los distintos niveles de permisos que se declaran en el manifiesto del complemento para especificar el nivel de acceso de la API de JavaScript que requiere el complemento para sus características.

Importante

Este artículo solo se aplica a complementos que no son de Outlook. Para obtener información sobre los niveles de permisos para complementos de Outlook, vea Modelo de permisos de Outlook.

Modelo de permisos

Un modelo de permisos de acceso de api de JavaScript de cinco niveles proporciona la base para la privacidad y la seguridad de los usuarios de los complementos. En la ilustración siguiente se muestran los cinco niveles de permisos de API que puede declarar en el manifiesto del complemento.

Estos permisos especifican el subconjunto de la API que el tiempo de ejecución del complemento permite que el complemento se use cuando un usuario inserta y, a continuación, activa (confía) el complemento. Para declarar el nivel de permiso que requiere el complemento, especifique uno de los valores de permiso en el manifiesto. El marcado varía en función del tipo de manifiesto.

• Manifiesto unificado para Microsoft 365: use la propiedad "authorization.permissions.resourceSpecific". En el ejemplo siguiente se solicita el permiso de escritura del documento , que solo permite métodos que pueden escribir en el documento (pero no leerlo).

  "authorization": {
      "permissions": {
        "resourceSpecific": [
          ...
          {
            "name": "Document.Write.User",
            "type": "Delegated"
          },
        ]
      }  
  },
  

  Nota:

  El manifiesto unificado para Microsoft 365 se puede usar en complementos de Outlook de producción. Solo está disponible como versión preliminar para excel, PowerPoint y complementos de Word.

• Manifiesto de solo complemento: use el elemento Permissions del manifiesto. En el ejemplo siguiente se solicita el permiso de escritura del documento , que solo permite métodos que pueden escribir en el documento (pero no leerlo).

  <Permissions>WriteDocument</Permissions>
  

El procedimiento recomendado es solicitar los permisos basándose en el principio de privilegio mínimo. Es decir, debería solicitar permisos para tener acceso únicamente al subconjunto mínimo de la API que el complemento necesite para funcionar correctamente. Por ejemplo, si el complemento solo necesita leer datos en el documento de un usuario para sus características, no debe solicitar más que el permiso de documento de lectura .

En la tabla siguiente se describen los subconjuntos de las API de JavaScript comunes y específicas de la aplicación que están habilitadas por cada nivel de permiso.

Nombre canónico del permiso	Nombre del manifiesto de solo complemento	Nombre del manifiesto unificado	Subconjunto habilitado de las API específicas de la aplicación	Subconjunto habilitado de las API comunes
restringido	Restricted	Document.Restricted.User	Ninguno	Los métodos del objeto Settings y del método Document.getActiveViewAsync. Este es el nivel de permiso mínimo que puede solicitar un complemento.
leer documento	ReadDocument	Document.Read.User	Todas y solo las API que leen el documento o sus propiedades.	Además de la API permitida por el permiso restringido , agrega acceso a los miembros de la API necesarios para leer el documento y administrar los enlaces. Esto incluye el uso de: El método Document.getSelectedDataAsync para obtener los datos de texto, HTML (solamente Word) o tabulares seleccionados pero no el código de Open Office XML (OOXML) subyacente que contiene todos los datos del documento. El método Document.getFileAsync para obtener todo el texto del documento, pero no la copia binaria OOXML subyacente del documento. El método Binding.getDataAsync para leer los datos enlazados del documento. Los métodos addFromNamedItemAsync, addFromPromptAsync y addFromSelectionAsync del objeto Bindings para crear enlaces en el documento. Los métodos getAllAsync, getByIdAsync y releaseByIdAsync del objeto Bindings para tener acceso y eliminar los enlaces del documento. El método Document.getFilePropertiesAsync para tener acceso a las propiedades de archivo del documento, como la dirección URL del documento. El método Document.goToByIdAsync para ir a los objetos con nombre del documento. Para complementos de panel de tareas de Project, todos los métodos "get" del objeto ProjectDocument.
leer todo el documento	ReadAllDocument	Document.ReadAll.User	Igual que el documento leído.	Además de la API permitida por los permisos de documentos restringidos y de lectura , permite el siguiente acceso adicional a los datos del documento. Los métodos Document.getSelectedDataAsync y Document.getFileAsync tienen acceso al código OOXML subyacente del documento (que, además del texto, puede incluir formato, vínculos, gráficos incrustados, comentarios, revisiones, etc.).
escribir documento	WriteDocument	Document.Write.User	Todas y solo las API que escriben en el documento o sus propiedades.	Además de la API permitida por el permiso restringido , agrega acceso a los siguientes miembros de la API. El método Document.setSelectedDataAsync para escribir en la selección del usuario en el documento.
documento de lectura y escritura	ReadWriteDocument	Document.ReadWrite.User	Todas las API de especificación de aplicación, incluidas las que se suscriben a eventos.	Además de la API permitida por los permisos restringidos, leer documentos, leer todo el documento y escribir documentos, incluye acceso a todas las API restantes admitidas por los complementos, incluidos los métodos para suscribirse a eventos. Debe declarar el permiso de documento de lectura y escritura para acceder a estos miembros de API adicionales: Método Binding.setDataAsync para escribir en regiones enlazadas del documento El método TableBinding.addRowsAsync para agregar filas a tablas enlazadas. El método TableBinding.addColumnsAsync para agregar columnas a tablas enlazadas. El método TableBinding.deleteAllDataValuesAsync para eliminar todos los datos de una tabla enlazada. Los métodos setFormatsAsync, clearFormatsAsync y setTableOptionsAsync del objeto TableBinding para definir el formato y las opciones de las tablas enlazadas. Todos los miembros de los objetos CustomXmlNode, CustomXmlPart, CustomXmlParts y CustomXmlPrefixMappings Todos los métodos para suscribirse a los eventos admitidos por los complementos, en concreto los addHandlerAsync métodos y removeHandlerAsync de los objetos Binding, CustomXmlPart, Document, ProjectDocument y Settings .

Vea también

• Privacidad y seguridad de complementos para Office