Solicitar permisos para el uso de la API en los complementos

En este artículo se describen los distintos niveles de permisos que puede declarar en el manifiesto del complemento del panel de tareas o contenido para especificar el nivel de acceso a la API de JavaScript que necesita el complemento por sus características.

Nota:

Para obtener información sobre los niveles de permisos de los complementos de correo (Outlook), vea Modelo de permisos de Outlook.

Modelo de permisos

Un modelo de permisos de acceso a la API de JavaScript de cinco niveles proporciona la base de la privacidad y seguridad de los usuarios de complementos del panel de tareas o contenido. En la figura 1 se indican los cinco niveles de permisos de la API que puede declarar en el manifiesto del complemento.

Figura 1. Modelo de permisos de cinco niveles para complementos del panel de tareas y de contenido

Estos permisos especifican el subconjunto de la API que el tiempo de ejecución del complemento permitirá que el complemento de contenido o panel de tareas use cuando un usuario inserte y, a continuación, activa (confía) el complemento. Para declarar el nivel de permisos que necesita su complemento de panel de tareas o contenido, especifique uno de los valores de texto de permiso del elemento Permissions del manifiesto del complemento. En el siguiente ejemplo se solicita el permiso WriteDocument, que únicamente permitirá métodos que pueden escribir (pero no leer) en el documento.

<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, por sus características, solamente necesita leer datos de un documento del usuario, no debería solicitar ningún otro permiso aparte de ReadDocument.

En la siguiente tabla se describe el subconjunto de la API JavaScript que permite cada nivel de permiso.

Permiso	Subconjunto de API habilitado
Restringido	Los métodos del objeto Settings y del método Document.getActiveViewAsync. Se trata del permiso mínimo que puede pedir un complemento de panel de tareas.
ReadDocument	Además de la API permitida por el permiso Restricted, agrega acceso a los miembros de la API necesarios para leer el documento y administrar 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 de un 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.
ReadAllDocument	Además de la API permitida por los permisos Restricted y ReadDocument , 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.).
WriteDocument	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.
ReadWriteDocument	Además de la API permitida por los permisos Restricted, ReadDocument, ReadAllDocument y WriteDocument, incluye acceso a todas las demás API admitidas por los complementos de panel de tareas y contenido, incluidos los métodos para suscribirse a eventos. Debe declarar el permiso ReadWriteDocument para tener acceso a estos miembros de la API adicionales: El método Binding.setDataAsync para escribir en regiones delimitadas 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 el contenido y los complementos del panel de tareas, específicamente los métodos addHandlerAsync y removeHandlerAsync de los objetos Binding, CustomXmlPart, Document, ProjectDocument y Settings.

Vea también

• Privacidad y seguridad de complementos para Office