Permisos

Los usuarios deben autorizar los complementos y otras aplicaciones que accedan a sus datos. o actuar en su nombre. Cuando un usuario ejecuta un complemento por primera vez, el de complemento presenta un mensaje de autorización para iniciar el flujo de autorización.

Durante este flujo, el mensaje le dice al usuario lo que quiere la aplicación permiso para hacer. Por ejemplo, es posible que un complemento quiera permiso para leer una mensaje de correo electrónico de un usuario o crear eventos en su calendario. La secuencia de comandos del complemento el proyecto define estos permisos individuales como permisos de OAuth.

Debes declarar alcances en tu manifiesto. con cadenas de URL. Durante el flujo de autorización, Apps Script presenta un descripción del alcance legible por humanos. Por ejemplo, tu complemento de Google Workspace podría usar el mensaje "Leer el mensaje actual" permiso, que está escrito en tu manifiesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly Durante en el flujo de autorización, un complemento con este alcance le pide al usuario que permita el acceso complemento: Ver tus mensajes de correo electrónico cuando se ejecute el complemento.

Permisos de visualización

Para ver los alcances que requiere tu proyecto de secuencia de comandos actualmente, haz lo siguiente: lo siguiente:

  1. Abre el proyecto de secuencia de comandos.
  2. A la izquierda, haz clic en Descripción general.
  3. Consulta los permisos en "Permisos de OAuth del proyecto".

También puedes ver los alcances actuales del proyecto de secuencia de comandos en el manifiesto del proyecto. en oauthScopes pero solo si configuraste esos alcances de forma explícita.

Configura permisos explícitos

Apps Script determina automáticamente qué alcances necesita una secuencia de comandos mediante el análisis su código para las llamadas a funciones que las requieren. Para la mayoría de las secuencias de comandos, esto es suficiente y te ahorra tiempo, pero para los complementos publicados debes hacer ejercicio un control más directo de los alcances.

Por ejemplo, Apps Script podría darle a un proyecto de secuencia de comandos de complemento el nivel de alcance https://mail.google.com de forma predeterminada. Cuando un usuario autoriza una secuencia de comandos proyecto con este permiso, se le otorga acceso completo a la cuenta de Gmail del usuario de servicio predeterminada. Para los complementos publicados, debes reemplazar este alcance con un que cubre las necesidades de los complementos y nada más.

Para establecer explícitamente los alcances que utiliza tu proyecto de secuencia de comandos, edita su archivo manifest. El campo del manifiesto oauthScopes es un array. de todos los alcances que usa el complemento. Para configurar los permisos de tu proyecto, haz lo siguiente: lo siguiente:

  1. Consulta los permisos que usa tu complemento actualmente. Determinar qué se deben realizar cambios, como usar un alcance más limitado.
  2. Abre el archivo de manifiesto de tu complemento.
  3. Localiza el campo de nivel superior etiquetado como oauthScopes. Si no está presente, puedes agregarlo.

  4. La oauthScopes especifica un array de cadenas. Para configurar los permisos usa tu proyecto, reemplaza el contenido de este array con los permisos que que quieres que use. Por ejemplo, para un complemento de Google Workspace que extiende Gmail, podrías tener lo siguiente:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}

  5. Guarda los cambios en el archivo de manifiesto.

Verificación de OAuth

Si usas determinados permisos de OAuth sensibles, es posible que debas usar tu complemento Verificación de clientes de OAuth antes de que puedas publicarlo. Si deseas obtener más información, consulta las siguientes guías:

Permisos restringidos

Algunos permisos están restringidos y están sujetos a reglas adicionales que ayudan a proteger los datos del usuario. Si vas a publicar un complemento de Gmail o de Editor que utilice uno o más permisos restringidos, el complemento debe cumplir con todos los restricciones antes de que se pueda publicar.

Revisa la lista completa de permisos restringidos. antes de intentar publicarlo. Si tu complemento usa alguno, debes cumplir con las políticas con el Requisitos adicionales para permisos específicos de las APIs antes de la publicación.

Permisos del calendario

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que extienden Calendario de Google.

Alcance
Accede a los metadatos de eventos https://www.googleapis.com/auth/calendar.addons.execute

Obligatorio si el complemento accede a los metadatos de los eventos de Calendario. Permite el complemento para acceder a los metadatos del evento.

Cómo leer datos de eventos generados por el usuario https://www.googleapis.com/auth/calendar.addons.current.event.read

Obligatorio si el complemento necesita leer datos de eventos generados por el usuario. Permite que el complemento acceda a datos de eventos generados por el usuario. Estos datos son solo están disponibles si el Campo de manifiesto addOns.calendar.eventAccess se establece en READ o READ_WRITE.

Escribe datos de eventos generados por el usuario https://www.googleapis.com/auth/calendar.addons.current.event.write

Obligatorio si el complemento necesita escribir datos de eventos generados por el usuario. Permite que el complemento edite datos de eventos generados por el usuario. Estos datos son solo están disponibles si el Campo de manifiesto addOns.calendar.eventAccess se establece en WRITE o READ_WRITE.

Permisos de Drive

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que amplían Google Drive.

Alcance
Leer metadatos del elemento seleccionado https://www.googleapis.com/auth/drive.addons.metadata.readonly

Es obligatorio si el complemento implementa una interfaz contextual que se activa cuando el usuario selecciona elementos en Drive. Permite que el complemento lea metadatos limitados sobre los elementos que un usuario tiene. seleccionada en Google Drive. Los metadatos se limitan al ID del elemento, título, tipo de MIME, URL del ícono y si el complemento tiene permiso para acceder al elemento.

Acceso por archivo https://www.googleapis.com/auth/drive.file

Recomendado si el complemento necesita acceder a Drive de forma individual . Otorga acceso por archivo a los archivos que crea o abre la app mediante la versión avanzada de Drive de Apps Script Service. Esto no permite el uso de acciones similares con el servicio básico de Drive sin embargo. La autorización de archivos se otorga por archivo y se se revoca cuando el usuario desautoriza la app.

Consulta la Ejemplo de solicitud de acceso a los archivos seleccionados

Permisos de los complementos de Gmail

Hay algunos ámbitos que se crearon específicamente para Complementos de Google Workspace para proteger a los usuarios de Gmail de datos no estructurados. Debes agregar estos permisos de forma explícita al manifiesto del complemento, junto con cualquier otro del código del complemento.

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que extienden Gmail. los que tienen la etiqueta Obligatorio deben agregarse Manifiesto del complemento de Google Workspace si tu complemento extiende Gmail

Asegúrate de reemplazar también el amplio alcance https://mail.google.com en tu con un conjunto más limitado de alcances que permiten interacciones. y nada más.

Alcance
Crear borradores nuevos https://www.googleapis.com/auth/gmail.addons.current.action.compose

Es obligatorio si el complemento usa Redactar activadores de acciones. Permite que el complemento cree borradores de mensajes nuevos de forma temporal y respuestas. Consulta Redactar borradores de mensajes para conocer los detalles. este alcance también se usa a menudo acciones de redacción. Se requiere un token de acceso.

Leer los metadatos de los mensajes abiertos https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Otorga acceso temporal a los metadatos del mensaje abierto (como el asunto o destinatarios). No permite leer el contenido de los mensajes y requiere un token de acceso.

Obligatorio si el complemento usa metadatos en la acción de redacción activadores. Para acciones de composición, este permiso es obligatorio si se trata de un activador de composición necesita acceso a los metadatos. En la práctica, este permiso permite redactar activar listas de destinatarios de acceso (para:, cc: y cco:) de una respuesta borrador de correo electrónico.

Leer el contenido del mensaje abierto https://www.googleapis.com/auth/gmail.addons.current.message.action

Otorga acceso al contenido del mensaje abierto cuando el usuario interactúa como cuando se selecciona un elemento de menú complementario. Requiere acceso token.

Leer contenido de conversaciones abiertas https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Otorga acceso temporal a los metadatos y el contenido del mensaje abierto. También otorga acceso al contenido de otros mensajes de la pantalla conversación. Se requiere un token de acceso.

Leer los metadatos y el contenido de cualquier mensaje https://www.googleapis.com/auth/gmail.readonly

Leer los metadatos y el contenido de los correos electrónicos, incluido el mensaje abierto Son obligatorias si necesitas leer información sobre otros mensajes, como cuando se realiza una búsqueda o se lee un hilo de correo completo.

Tokens de acceso

Para proteger los datos del usuario, los permisos de Gmail utilizados en Los complementos de Google Workspace solo otorgan acceso acceso temporal a los datos del usuario. Para habilitar el acceso temporal, debes llamar al función GmailApp.setCurrentMessageAccessToken(accessToken) con un token de acceso como argumento. Debes obtener un token de acceso de un objeto de evento de acción.

A continuación, se muestra un ejemplo de configuración de un token de acceso para permitir el acceso a los metadatos de un mensaje. El único alcance necesario para este ejemplo es https://www.googleapis.com/auth/gmail.addons.current.message.metadata

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Permisos del editor

A continuación, se muestran los permisos de uso frecuente para los complementos de Google Workspace que amplían Documentos, Hojas de cálculo, y Presentaciones.

Alcance
Acceso actual a archivos de Documentos https://www.googleapis.com/auth/documents.currentonly

Es obligatorio si el complemento accede a la API de Documentos de Apps Script. Otorga acceso temporal al contenido del documento abierto.

Acceso a los archivos de Hojas de cálculo actuales https://www.googleapis.com/auth/spreadsheets.currentonly

Es obligatorio si el complemento accede a la API de Hojas de cálculo de Apps Script. Otorga acceso temporal al contenido de la hoja de cálculo abierta.

Acceso a archivos de Presentaciones actuales https://www.googleapis.com/auth/presentations.currentonly

Es obligatorio si el complemento accede a la API de Presentaciones de Apps Script. Otorga acceso temporal al contenido de la presentación abierta.

Acceso por archivo https://www.googleapis.com/auth/drive.file

Obligatorio para que el complemento use onFileScopeGrantedTrigger y si el complemento accede a la API de Documentos, Hojas de cálculo, Presentaciones o Drive. Otorga acceso por archivo a los archivos que crea o abre la app mediante la versión avanzada de Drive de Apps Script Service. Esto no permite el uso de acciones similares con el servicio básico de Drive sin embargo. La autorización de archivos se otorga por archivo y se revocada cuando el usuario desautoriza la aplicación.

Otros alcances

Es posible que tu complemento requiera permisos adicionales si usa otros servicios de Apps Script. En la mayoría de los casos, puedes permitir que Apps Script detecte estos alcances y actualizar el el manifiesto automáticamente. Cuando edites la lista de alcances de tu manifiesto, no la quites cualquier alcance, a menos que los reemplaces por una alternativa más adecuada, como un alcance más limitado.

A modo de referencia, aquí hay una lista de ámbitos de Apps Script que se usan a menudo en en conjunto con los complementos de Google Workspace:

Alcance
Leer la dirección de correo electrónico del usuario https://www.googleapis.com/auth/userinfo.email

Permite que el proyecto lea la dirección de correo electrónico del usuario actual.

Permitir llamadas a servicios externos https://www.googleapis.com/auth/script.external_request

Permite que el proyecto UrlFetch solicitudes. Esto también es necesario si el proyecto utiliza el OAuth2 para la biblioteca de Apps Script.

Leer la configuración regional y la zona horaria del usuario https://www.googleapis.com/auth/script.locale

Permite que el proyecto conozca la configuración regional y la zona horaria del usuario actual. Consulta Accede a la configuración regional y la zona horaria del usuario para obtener más detalles.

Crear activadores https://www.googleapis.com/auth/script.scriptapp

Permite que el proyecto cree activadores.

Vista previa de vínculos de terceros https://www.googleapis.com/auth/workspace.linkpreview

Obligatorio si el complemento muestra vistas previas de vínculos de un servicio de terceros. Permite que el proyecto vea un vínculo en una aplicación de Google Workspace mientras el usuario interactúa con ella. Para obtener más información, consulta Obtén una vista previa de vínculos con chips inteligentes.

Crea recursos de terceros https://www.googleapis.com/auth/workspace.linkcreate

Obligatorio si el complemento crea recursos en un servicio de terceros. Permite que el proyecto lea la información que envían los usuarios el formulario de creación de recursos y insertar un vínculo al recurso en una aplicación de Google Workspace. Para obtener más información, consulta Crea recursos de terceros desde el menú @.