Se usó la API de Cloud Translation para traducir esta página.

Miras

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

Durante este flujo, el mensaje le indica al usuario qué desea que haga la aplicación. Por ejemplo, es posible que un complemento quiera obtener permiso para leer el mensaje de correo electrónico de un usuario o crear eventos en su calendario. El proyecto de secuencia de comandos del complemento define estos permisos individuales como permisos de OAuth.

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

Alcances de visualización

Puedes ver los alcances que requiere tu proyecto de secuencia de comandos de la siguiente manera:

Abre el proyecto de la secuencia de comandos.
A la izquierda, haz clic en Descripción general .
Consulta los alcances en “Alcances de OAuth del proyecto”.

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

Configura permisos explícitos

Apps Script determina automáticamente los permisos que necesita una secuencia de comandos mediante el análisis de su código en busca de llamadas a funciones que las requieran. Para la mayoría de las secuencias de comandos, esto es suficiente y te ahorra tiempo, pero en el caso de los complementos publicados, debes ejercer un control más directo de los permisos.

Por ejemplo, Apps Script podría darle a un proyecto de secuencia de comandos de complemento el permiso muy permisivo https://mail.google.com de forma predeterminada. Cuando un usuario autoriza un proyecto de secuencia de comandos con este alcance, el proyecto obtiene acceso completo a la cuenta de Gmail del usuario. En el caso de los complementos publicados, debes reemplazar este alcance por un conjunto más limitado que cubra las necesidades de los complementos y no más.

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

Consulta los alcances que tu complemento usa actualmente. Determina qué cambios se deben realizar, como usar un alcance más acotado.
Abre el archivo de manifiesto del complemento.
Ubica el campo de nivel superior etiquetado oauthScopes. Si no lo tienes, puedes agregarlo.
En el campo oauthScopes, se especifica un array de strings. Para establecer los permisos que usa tu proyecto, reemplaza el contenido de este arreglo por los alcances que deseas que use. Por ejemplo, en el caso de un complemento de Google Workspace que extiende Gmail, es posible que tenga lo siguiente:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
Guarda los cambios en el archivo de manifiesto.

Verificación de OAuth

Es posible que el uso de ciertos permisos sensibles de OAuth requiera que el complemento pase por la verificación del cliente de OAuth para poder publicarlo. Si deseas obtener más información, consulta las siguientes guías:

Alcances restringidos

Algunos permisos están restringidos y están sujetos a reglas adicionales que ayudan a proteger los datos del usuario. Si quieres publicar un complemento de Gmail o un editor que use uno o más alcances restringidos, el complemento debe cumplir con todas las restricciones especificadas para poder publicarse.

Revisa la lista completa de permisos restringidos antes de intentar publicar. Si el complemento usa alguno de ellos, debes cumplir con los requisitos adicionales para permisos específicos de la API antes de publicarlo.

Permisos de Calendario

A continuación, se muestran los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden el Calendario de Google.

Alcance
Accede a los metadatos de eventos	`https://www.googleapis.com/auth/calendar.addons.execute` Obligatorio si el complemento accede a metadatos de eventos de Calendario. Permite que el complemento acceda a los metadatos del evento.
Leer datos de eventos generados por usuarios	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Obligatorio si el complemento necesita leer los datos de eventos generados por los usuarios. Permite que el complemento acceda a los datos de eventos generados por el usuario. Estos datos 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 los usuarios	`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 los usuarios. Estos datos 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 que se usan con frecuencia para los complementos de Google Workspace que extienden Google Drive.

Alcance

Leer metadatos de elementos seleccionados

Alcance
Leer metadatos de elementos seleccionados	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` 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 seleccionó en Google Drive. Los metadatos se limitan al ID del elemento, el título, el tipo de MIME, la URL del ícono y si el complemento tiene permiso para acceder al elemento.
Acceso por archivo	`https://www.googleapis.com/auth/drive.file` Se recomienda si el complemento necesita acceder a archivos de Drive individuales. Otorga acceso por archivo a los archivos que crea o abre la app con el Servicio de Drive avanzado de Apps Script. Sin embargo, esto no permite el uso de acciones similares que usan el servicio básico de Drive. La autorización del archivo se otorga por archivo y se revoca cuando el usuario desautoriza la aplicación. Consulta el ejemplo de Solicitud de acceso a archivos para los archivos seleccionados.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

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 seleccionó en Google Drive. Los metadatos se limitan al ID del elemento, el título, el tipo de MIME, la URL del ícono y si el complemento tiene permiso para acceder al elemento.

Acceso por archivo

https://www.googleapis.com/auth/drive.file

Se recomienda si el complemento necesita acceder a archivos de Drive individuales. Otorga acceso por archivo a los archivos que crea o abre la app con el Servicio de Drive avanzado de Apps Script. Sin embargo, esto no permite el uso de acciones similares que usan el servicio básico de Drive. La autorización del archivo se otorga por archivo y se revoca cuando el usuario desautoriza la aplicación.

Consulta el ejemplo de Solicitud de acceso a archivos para los archivos seleccionados.

Permisos de los complementos de Gmail

Hay algunos permisos que se crearon específicamente para los complementos de Google Workspace a fin de ayudar a proteger los datos de Gmail de los usuarios. Debes agregar estos alcances de forma explícita al manifiesto de complemento, junto con cualquier otro que requiera el código del complemento.

A continuación, se muestran los alcances de uso frecuente para los complementos de Google Workspace que extienden Gmail; los que se etiquetan como Obligatorios deben agregarse al manifiesto del complemento de Google Workspace si su complemento extiende Gmail.

Asegúrate de reemplazar el alcance https://mail.google.com, que es muy amplio, en tu complemento por un conjunto más limitado de permisos que permitan las interacciones que necesita tu complemento.

Alcance
Crear borradores nuevos	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obligatorio si el complemento usa activadores de acción de redacción. Permite que el complemento cree temporalmente nuevos borradores de mensajes y respuestas. Consulta Cómo redactar mensajes en borrador para obtener más información. Este alcance también se usa a menudo con acciones de redacción. Requiere un token de acceso.
Leer metadatos de 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 los destinatarios). No permite leer el contenido del mensaje y requiere un token de acceso. Obligatorio si el complemento usa metadatos en los activadores de acciones de redacción. En el caso de las acciones de composición, este alcance es obligatorio si el activador de composición necesita acceso a los metadatos. En la práctica, este alcance permite que un elemento de redacción active las listas de destinatarios (a:, cc: y bcc:) de un borrador de correo electrónico de respuesta.
Leer el contenido de mensaje abierto	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Otorga acceso al contenido del mensaje abierto cuando la interacción del usuario, como cuando se selecciona un elemento de menú complementario. Requiere un token de acceso.
Leer contenido de la conversación abierta	`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 del subproceso abierto. Requiere un token de acceso.
Leer cualquier contenido y metadatos del mensaje	`https://www.googleapis.com/auth/gmail.readonly` Lee los metadatos y el contenido del correo electrónico, incluido el mensaje abierto. Es obligatorio si necesitas leer información sobre otros mensajes, como cuando realizas una búsqueda o lees una conversación de correo completa. Advertencia: Este es un alcance restringido muy amplio. Úsalo solo si es absolutamente necesario.

Tokens de acceso

Para proteger los datos del usuario, los permisos de Gmail que se usan en los complementos de Google Workspace solo otorgan acceso temporal a los datos del usuario. Para habilitar el acceso temporal, debes llamar a la 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 cómo configurar un token de acceso para permitir el acceso a los metadatos de un mensaje. El único permiso 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();
}

Alcances del editor

A continuación, se muestran los permisos que se usan con frecuencia para los complementos de Google Workspace que extienden Documentos, Hojas de cálculo y Presentaciones.

Alcance
Acceso al archivo de Documentos actual	`https://www.googleapis.com/auth/documents.currentonly` Obligatorio si el complemento accede a la API de Documentos de Apps Script. Otorga acceso temporal al contenido del documento abierto.
Acceso a archivos de Hojas de cálculo actuales	`https://www.googleapis.com/auth/spreadsheets.currentonly` 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 al archivo de Presentaciones actual	`https://www.googleapis.com/auth/presentations.currentonly` Obligatorio si el complemento accede a la API de Slides 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 acceda 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 con el Servicio de Drive avanzado de Apps Script. Sin embargo, esto no permite el uso de acciones similares que usan el servicio básico de Drive. La autorización del archivo se otorga por archivo y se revoca cuando el usuario desautoriza la aplicación.

Otros permisos

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 permisos y actualice el manifiesto automáticamente. Cuando edites la lista de permisos del manifiesto, no quites ningún permiso, a menos que los reemplaces con una alternativa más adecuada, como un alcance más reducido.

A modo de referencia, aquí te mostramos una lista de alcances de Apps Script que suelen usarse en conjunto con 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 realice solicitudes `UrlFetch`. Esto también es obligatorio si el proyecto usa la biblioteca OAuth2 para 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. Para obtener más información, consulta Acceso a la configuración regional y la zona horaria del usuario.
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 de vista previa se vincula desde un servicio de terceros. Permite que el proyecto vea un vínculo dentro de una aplicación de Google Workspace mientras el usuario interactúa con ella. Si quieres obtener más información, consulta Cómo obtener vistas previas de vínculos con chips inteligentes.