Los usuarios deben autorizar los proyectos de secuencia de comandos que acceden a sus datos o actúan en su nombre. Cuando un usuario ejecuta una secuencia de comandos que requiere autorización por primera vez, la IU presenta un mensaje para iniciar el flujo de autorización.
Durante este flujo, la IU le indica al usuario lo que la secuencia de comandos quiere hacer con el permiso. Por ejemplo, una secuencia de comandos puede solicitar permiso para leer los mensajes de correo electrónico del usuario o crear eventos en su calendario. El proyecto de secuencia de comandos define estos permisos individuales como alcances de OAuth.
En la mayoría de las secuencias de comandos, Apps Script detecta automáticamente los permisos que necesitas. Puedes ver los permisos que usa una secuencia de comandos en cualquier momento. También puedes configurar los alcances de forma explícita en tu manifest con cadenas de URL. A veces, es necesario configurar los permisos de forma explícita para ciertas aplicaciones, como los complementos, ya que las aplicaciones publicadas siempre deben usar los permisos más limitados posibles.
Durante el flujo de autorización, Apps Script le presenta al usuario descripciones legibles por humanos de los permisos requeridos. Por ejemplo, si tu secuencia de comandos necesita acceso de solo lectura a tus hojas de cálculo, el manifiesto puede tener el permiso https://www.googleapis.com/auth/spreadsheets.readonly
. Durante el flujo de autorización, una secuencia de comandos con este permiso le solicita al usuario que permita que esta aplicación "Vea tus Hojas de cálculo de Google".
Algunos permisos incluyen otros. Por ejemplo, cuando se autoriza, el permiso https://www.googleapis.com/auth/spreadsheets
permite el acceso de lectura y escritura a las hojas de cálculo.
En algunas plataformas en las que se ejecutan secuencias de comandos, como cuando se ejecuta una secuencia de comandos directamente desde el IDE de Apps Script, a los usuarios se les presenta la pantalla de consentimiento de OAuth detallada. Esto permite que los usuarios seleccionen permisos específicos para otorgar en lugar de otorgar todos los permisos a la vez. Es importante diseñar tu secuencia de comandos para controlar los permisos de OAuth detallados.
Cómo ver los permisos
Para ver los alcances que requiere actualmente tu proyecto de secuencia de comandos, haz lo siguiente:
- Abre el proyecto de secuencia de comandos.
- A la izquierda, haz clic en Descripción general .
- Consulta los permisos en Project OAuth Scopes.
Establece permisos explícitos
Apps Script determina automáticamente qué alcances necesita una secuencia de comandos analizando su código en busca de llamadas a funciones que los requieran. Para la mayoría de las secuencias de comandos, esto es suficiente y te ahorra tiempo, pero para los complementos publicados, las apps web, las apps de Google Chat y las llamadas a la API de Google Chat, debes ejercer un control más directo de los permisos.
A veces, Apps Script asigna automáticamente a los proyectos permisos muy permisivos. Esto puede significar que tu secuencia de comandos le pide al usuario más de lo que necesita, lo que es una práctica inadecuada. En el caso de las secuencias de comandos publicadas, debes reemplazar los permisos amplios por un conjunto más limitado que cubra las necesidades de la secuencia de comandos y nada más.
Puedes establecer de forma explícita los alcances que usa tu proyecto de secuencia de comandos editando
su archivo de manifest. El campo del manifiesto oauthScopes
es un array de todos los alcances que usa el proyecto. Para configurar los permisos de tu proyecto, haz lo siguiente:
- Abre el proyecto de secuencia de comandos.
- A la izquierda, haz clic en Configuración del proyecto .
- Selecciona la casilla de verificación Mostrar el archivo de manifiesto "appsscript.json" en el editor.
- A la izquierda, haz clic en Editor .
- A la izquierda, haz clic en el archivo
appsscript.json
. - Busca el campo de nivel superior etiquetado como
oauthScopes
. Si no está presente, puedes agregarlo. - El campo
oauthScopes
especifica un array de cadenas. Para establecer los permisos que usa tu proyecto, reemplaza el contenido de este array por los permisos que deseas que use. Por ejemplo:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/spreadsheets.readonly", "https://www.googleapis.com/auth/userinfo.email" ], ... }
- En la parte superior, haz clic en Guardar .
Controla los permisos de OAuth detallados
La pantalla de consentimiento de OAuth detallada permite que los usuarios especifiquen qué permisos individuales de OAuth desean autorizar. Los permisos de OAuth detallados les brindan a los usuarios un control más detallado sobre los datos de la cuenta que eligen compartir con cada secuencia de comandos. Por ejemplo, imagina que desarrollas una secuencia de comandos que solicita permiso para los permisos de correo electrónico y calendario. Es posible que los usuarios quieran usar tu secuencia de comandos solo por sus funciones con el Calendario de Google, pero no con Gmail. Con los permisos de OAuth detallados, los usuarios pueden optar por otorgar solo permiso al Calendario, pero no a Gmail.
En las siguientes secciones, se describen las principales formas de controlar los permisos granulares de OAuth.
Cómo solicitar automáticamente el permiso para los alcances necesarios
Si un flujo de ejecución necesita permiso para los alcances para funcionar, puedes requerir que los usuarios otorguen esos permisos antes de poder usarlo. Tu secuencia de comandos puede verificar si el usuario ya otorgó el permiso y, de lo contrario, solicitárselo automáticamente.
Los siguientes métodos de la clase ScriptApp
te permiten validar el permiso para los alcances requeridos y renderizar automáticamente el mensaje de autorización para solicitar los permisos que faltan:
requireScopes(authMode, oAuthScopes)
: Usa este método para los flujos de ejecución que dependen de uno o más alcances, pero no de todos los que usa tu secuencia de comandos.requireAllScopes(authMode)
: Usa este método si un flujo de ejecución depende de todos los alcances que usa tu secuencia de comandos.
Ejemplo
En el siguiente ejemplo, se muestra cómo llamar a los métodos requireScopes(authMode, oAuthScopes)
y requireAllScopes(authMode)
.
La secuencia de comandos usa permisos para Gmail, Hojas de cálculo y Calendario.
La función sendEmail()
solo requiere los permisos de Gmail y Sheets, mientras que la función createEventSendEmail()
requiere todos los permisos que usa la secuencia de comandos.
// This function requires the Gmail and Sheets scopes.
function sendEmail() {
// Validates that the user has granted permission for the Gmail and Sheets scopes.
// If not, the execution ends and prompts the user for authorization.
ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
'https://mail.google.com/',
'https://www.googleapis.com/auth/spreadsheets'
]);
// Sends an email.
GmailApp.sendEmail("dana@example.com", "Subject", "Body");
Logger.log("Email sent successfully!");
// Opens a spreadsheet and sheet to track the sent email.
const ss = SpreadsheetApp.openById("abc1234567");
const sheet = ss.getSheetByName("Email Tracker")
// Gets the last row of the sheet.
const lastRow = sheet.getLastRow();
// Adds "Sent" to column E of the last row of the spreadsheet.
sheet.getRange(lastRow, 5).setValue("Sent");
Logger.log("Sheet updated successfully!");
}
// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
// Validates that the user has granted permission for all scopes used by the
// script. If not, the execution ends and prompts the user for authorization.
ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);
// Creates an event.
CalendarApp.getDefaultCalendar().createEvent(
"Meeting",
new Date("November 28, 2024 10:00:00"),
new Date("November 28, 2024 11:00:00")
);
Logger.log("Calendar event created successfully!");
// Sends an email.
GmailApp.sendEmail("dana@example.com", "Subject 2", "Body 2");
Logger.log("Email sent successfully!");
// Opens a spreadsheet and sheet to track the created meeting and sent email.
const ss = SpreadsheetApp.openById("abc1234567");
const sheet = ss.getSheetByName("Email and Meeting Tracker")
// Gets the last row
const lastRow = sheet.getLastRow();
// Adds "Sent" to column E of the last row
sheet.getRange(lastRow, 5).setValue("Sent");
// Adds "Meeting created" to column F of the last row
sheet.getRange(lastRow, 6).setValue("Meeting created");
Logger.log("Sheet updated successfully!");
}
Crea una experiencia personalizada para los alcances faltantes
Puedes obtener los detalles de los permisos del usuario que ejecuta tu secuencia de comandos y diseñar una experiencia personalizada según su estado de permiso. Por ejemplo, puedes apagar funciones específicas de la secuencia de comandos que requieren permisos que el usuario no otorgó, o bien presentar un diálogo personalizado en el que se expliquen los permisos que faltan. Los siguientes métodos obtienen un objeto con la información de permisos del usuario que incluye los permisos que autorizó el usuario y una URL para permitirte solicitar los permisos faltantes:
getAuthorizationInfo(authMode, oAuthScopes)
: Usa este método para verificar el estado de los permisos de alcances específicos.getAuthorizationInfo(authMode)
: Usa este método para verificar el estado de los permisos de todos los permisos que usa tu secuencia de comandos.
Para obtener los detalles del permiso del objeto de información de autorización, como una lista de los permisos que se autorizaron y una URL para solicitar los permisos faltantes, usa los métodos de la clase AuthorizationInfo
.
Ejemplo
En el siguiente ejemplo, se muestra cómo llamar al método getAuthorizationInfo(authMode, oAuthScopes)
para omitir funciones específicas dentro de un flujo de ejecución en el que no se otorgaron los permisos necesarios. Esto permite que el resto del flujo de ejecución continúe sin tener que solicitar la autorización de los permisos faltantes.
// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
GmailApp.sendEmail("dana@example.com", "Subject", "Body");
Logger.log("Email sent successfully!");
} else {
const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
}
// Continue the rest of the execution flow...
}
Verificación de OAuth
Ciertos permisos de OAuth son sensibles porque permiten el acceso a los datos del usuario de Google. Si tu proyecto de secuencia de comandos usa permisos que permiten el acceso a los datos del usuario, el proyecto debe pasar por la verificación del cliente de OAuth antes de que puedas publicarlo públicamente como una app web o un complemento. Si deseas obtener más información, consulta las siguientes guías:
- Verificación de cliente de OAuth para Apps Script
- Apps no verificadas
- Preguntas frecuentes sobre la verificación de OAuth
- Política de Datos del Usuario del Servicio de las APIs de Google
Permisos restringidos
Además de los permisos sensibles, algunos permisos se clasifican como restringidos y están sujetos a reglas adicionales que ayudan a proteger los datos del usuario. Si deseas publicar una app web o un complemento que use uno o más permisos restringidos, la app debe cumplir con todas las restricciones especificadas antes de que se pueda publicar.
Revisa la lista completa de alcances restringidos antes de intentar publicar. Si tu app usa alguna de ellas, debes cumplir con los requisitos adicionales para permisos específicos de API antes de publicarla.