Class ScriptApp

ScriptApp

Acceder a la publicación y los activadores de secuencias de comandos, y manipularlos Esta clase permite a los usuarios crear activadores de secuencias de comandos y controlar la publicación de la secuencia de comandos como un servicio.

Propiedades

Propiedad	Tipo	Descripción
AuthMode	AuthMode	Es una enumeración que identifica qué categorías de servicios autorizados puede ejecutar Apps Script a través de una función activada.
AuthorizationStatus	AuthorizationStatus	Es una enumeración que denota el estado de autorización de una secuencia de comandos.
EventType	EventType	Es una enumeración que denota el tipo de evento activado.
InstallationSource	InstallationSource	Es una enumeración que indica cómo se instaló la secuencia de comandos para el usuario como complemento.
TriggerSource	TriggerSource	Es una enumeración que denota la fuente del evento que hace que se active el disparador.
WeekDay	Weekday	Es una enumeración que representa los días de la semana.

Métodos

Método	Tipo de datos que se muestra	Descripción breve
deleteTrigger(trigger)	void	Quita el activador determinado para que ya no se ejecute.
getAuthorizationInfo(authMode)	AuthorizationInfo	Obtiene un objeto que verifica si el usuario otorgó la autorización para todos los requisitos de la secuencia de comandos.
getAuthorizationInfo(authMode, oAuthScopes)	AuthorizationInfo	Obtiene un objeto que verifica si el usuario otorgó autorización para los alcances solicitados.
getIdentityToken()	String	Obtiene un token de identidad de OpenID Connect para el usuario efectivo, si se otorgó el alcance de openid.
getInstallationSource()	InstallationSource	Devuelve un valor de enumeración que indica cómo se instaló la secuencia de comandos como complemento para el usuario actual (por ejemplo, si el usuario la instaló personalmente a través de Chrome Web Store o si un administrador del dominio la instaló para todos los usuarios).
getOAuthToken()	String	Obtiene el token de acceso de OAuth 2.0 para el usuario efectivo.
getProjectTriggers()	Trigger[]	Obtiene todos los activadores instalables asociados con el proyecto y el usuario actuales.
getScriptId()	String	Obtiene el ID único del proyecto de secuencia de comandos.
getService()	Service	Obtiene un objeto que se usa para controlar la publicación de la secuencia de comandos como una app web.
getUserTriggers(document)	Trigger[]	Obtiene todos los activadores instalables que posee este usuario en el documento determinado, solo para esta secuencia de comandos o complemento.
getUserTriggers(form)	Trigger[]	Obtiene todos los activadores instalables que posee este usuario en el formulario determinado, solo para esta secuencia de comandos o complemento.
getUserTriggers(spreadsheet)	Trigger[]	Obtiene todos los activadores instalables que posee este usuario en la hoja de cálculo determinada, solo para esta secuencia de comandos o complemento.
invalidateAuth()	void	Invalida la autorización que tiene el usuario efectivo para ejecutar la secuencia de comandos actual.
newStateToken()	StateTokenBuilder	Crea un compilador para un token de estado que se puede usar en una API de devolución de llamada (como un flujo de OAuth).
newTrigger(functionName)	TriggerBuilder	Comienza el proceso de creación de un activador instalable que, cuando se activa, llama a una función determinada.
requireAllScopes(authMode)	void	Valida si el usuario otorgó su consentimiento para todos los permisos solicitados por la secuencia de comandos.
requireScopes(authMode, oAuthScopes)	void	Valida si el usuario otorgó su consentimiento para los alcances solicitados.

Métodos obsoletos

Método	Tipo de datos que se muestra	Descripción breve
getProjectKey()	String	Obtiene la clave del proyecto de la secuencia de comandos actual.
getScriptTriggers()	Trigger[]	Obtiene todos los activadores instalables asociados con el proyecto y el usuario actuales.

Documentación detallada

deleteTrigger(trigger)

Quita el activador determinado para que ya no se ejecute.

// Deletes all triggers in the current project.
const triggers = ScriptApp.getProjectTriggers();
for (let i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Parámetros

Nombre	Tipo	Descripción
trigger	Trigger	Es el activador que se borrará.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

getAuthorizationInfo(authMode)

Obtiene un objeto que verifica si el usuario otorgó la autorización para todos los requisitos de la secuencia de comandos. El objeto también proporciona una URL de autorización para que los usuarios otorguen esos permisos en caso de que no se autorice ninguno de los requisitos de la secuencia de comandos.

Algunas ejecuciones de secuencias de comandos pueden comenzar sin el consentimiento del usuario para todos los permisos requeridos que usa la secuencia de comandos. La información de este objeto te permite controlar el acceso a secciones de código que requieren ciertos alcances y solicitar la autorización de esos alcances para ejecuciones posteriores.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

Parámetros

Nombre	Tipo	Descripción
authMode	AuthMode	Es el modo de autorización para el que se solicita información de autorización. En casi todos los casos, el valor de authMode debe ser ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), ya que ningún otro modo de autorización requiere que los usuarios otorguen la autorización.

Volver

AuthorizationInfo: Es un objeto que puede proporcionar información sobre el estado de autorización del usuario.

---

getAuthorizationInfo(authMode, oAuthScopes)

Obtiene un objeto que verifica si el usuario otorgó autorización para los alcances solicitados. El objeto también proporciona una URL de autorización para que los usuarios otorguen esos permisos, en caso de que no se autorice ninguno de los alcances solicitados.

Algunas ejecuciones de secuencias de comandos pueden comenzar sin el consentimiento del usuario para todos los permisos requeridos que usa la secuencia de comandos. La información de este objeto te permite controlar el acceso a secciones de código que requieren ciertos alcances y solicitar la autorización de esos alcances para ejecuciones posteriores. Los permisos que no son válidos o que el script no requiere generan un error.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

Parámetros

Nombre	Tipo	Descripción
authMode	AuthMode	Es el modo de autorización para el que se solicita información de autorización. En casi todos los casos, el valor de authMode debe ser ScriptApp.AuthMode.FULL, ya que ningún otro modo de autorización requiere que los usuarios otorguen la autorización.
oAuthScopes	String[]	Son los permisos de OAuth para los que se solicita información de autorización.

Volver

AuthorizationInfo: Es un objeto que proporciona información sobre el estado de autorización del usuario y una URL de autorización en caso de que falten algunos consentimientos.

---

getIdentityToken()

Obtiene un token de identidad de OpenID Connect para el usuario efectivo, si se otorgó el alcance de openid. Este alcance no se incluye de forma predeterminada, y debes agregarlo como un alcance explícito en el archivo de manifiesto para solicitarlo. Incluye los alcances https://www.googleapis.com/auth/userinfo.email o https://www.googleapis.com/auth/userinfo.profile para devolver información adicional del usuario en el token.

El token de ID que se devuelve es un token web JSON (JWT) codificado y se debe decodificar para extraer información de él. En los siguientes ejemplos, se muestra cómo decodificar el token y extraer el ID del perfil de Google del usuario efectivo.

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);

Consulta la documentación de OpenID Connect para obtener la lista completa de campos (declaraciones) que se devuelven.

Volver

String: Es el token de identidad si está disponible; de lo contrario, es null.

---

getInstallationSource()

Devuelve un valor de enumeración que indica cómo se instaló la secuencia de comandos como complemento para el usuario actual (por ejemplo, si el usuario la instaló personalmente a través de Chrome Web Store o si un administrador del dominio la instaló para todos los usuarios).

Volver

InstallationSource: Es la fuente de instalación.

---

getOAuthToken()

Obtiene el token de acceso de OAuth 2.0 para el usuario efectivo. Si los permisos de OAuth de la secuencia de comandos son suficientes para autorizar otra API de Google que normalmente requiere su propio flujo de OAuth (como Google Picker), las secuencias de comandos pueden omitir la segunda solicitud de autorización pasando este token. El token vence después de un tiempo (unos minutos como mínimo). Los secuencias de comandos deben controlar los errores de autorización y llamar a este método para obtener un token nuevo cuando sea necesario.

El token que devuelve este método solo incluye los permisos que el script necesita actualmente. Los permisos que se autorizaron anteriormente, pero que ya no usa la secuencia de comandos, no se incluyen en el token que se devuelve. Si se necesitan permisos de OAuth adicionales más allá de los que requiere el propio código, se pueden especificar en el archivo de manifiesto del código.

Volver

String: Es una representación de cadena del token de OAuth 2.0.

---

getProjectTriggers()

Obtiene todos los activadores instalables asociados con el proyecto y el usuario actuales.

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

Volver

Trigger[]: Es un array de los activadores del usuario actual asociados con este proyecto.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

getScriptId()

Obtiene el ID único del proyecto de secuencia de comandos. Este es el método preferido para obtener el identificador único del proyecto de secuencia de comandos en lugar de getProjectKey(). Este ID se puede usar en todos los lugares en los que antes se proporcionaba la clave del proyecto.

Volver

String: Es el ID del proyecto de secuencia de comandos.

---

getService()

Obtiene un objeto que se usa para controlar la publicación de la secuencia de comandos como una app web.

// Get the URL of the published web app.
const url = ScriptApp.getService().getUrl();

Volver

Service: Es un objeto que se usa para observar y controlar la publicación de la secuencia de comandos como una app web.

---

getUserTriggers(document)

Obtiene todos los activadores instalables que posee este usuario en el documento determinado, solo para esta secuencia de comandos o complemento. Este método no se puede usar para ver los activadores adjuntos a otros secuencias de comandos.

const doc = DocumentApp.getActiveDocument();
const triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Parámetros

Nombre	Tipo	Descripción
document	Document	Un archivo de Documentos de Google que puede contener activadores instalables.

Volver

Trigger[]: Es un array de activadores que pertenecen a este usuario en el documento determinado.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

getUserTriggers(form)

Obtiene todos los activadores instalables que posee este usuario en el formulario determinado, solo para esta secuencia de comandos o complemento. Este método no se puede usar para ver los activadores adjuntos a otros secuencias de comandos.

const form = FormApp.getActiveForm();
const triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Parámetros

Nombre	Tipo	Descripción
form	Form	Un archivo de Formularios de Google que puede contener activadores instalables.

Volver

Trigger[]: Es un array de activadores que pertenecen a este usuario en el formulario determinado.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

getUserTriggers(spreadsheet)

Obtiene todos los activadores instalables que posee este usuario en la hoja de cálculo determinada, solo para esta secuencia de comandos o complemento. Este método no se puede usar para ver los activadores adjuntos a otros secuencias de comandos.

const ss = SpreadsheetApp.getActiveSpreadsheet();
const triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Parámetros

Nombre	Tipo	Descripción
spreadsheet	Spreadsheet	Un archivo de Hojas de cálculo de Google que puede contener activadores instalables.

Volver

Trigger[]: Es un array de activadores que pertenecen a este usuario en la hoja de cálculo determinada.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

invalidateAuth()

Invalida la autorización que tiene el usuario efectivo para ejecutar la secuencia de comandos actual. Se usa para invalidar cualquier permiso de la secuencia de comandos actual. Esto es especialmente útil para las funciones etiquetadas como autorización única. Dado que las funciones de autorización única solo se pueden llamar en la primera ejecución después de que la secuencia de comandos haya adquirido la autorización, si deseas realizar una acción después, debes revocar cualquier autorización que haya tenido la secuencia de comandos para que el usuario pueda volver a ver el diálogo de autorización.

ScriptApp.invalidateAuth();

Arroja

Error: Cuando falla la invalidación

---

newStateToken()

Crea un compilador para un token de estado que se puede usar en una API de devolución de llamada (como un flujo de OAuth).

// Generate a callback URL, given the name of a callback function. The script
// does not need to be published as a web app; the /usercallback URL suffix
// replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the
  // /edit at the end.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

En la mayoría de los flujos de OAuth2, el token state se pasa directamente al extremo de autorización (no como parte de la URL de devolución de llamada), y el extremo de autorización lo pasa como parte de la URL de devolución de llamada.

Por ejemplo:

• La secuencia de comandos redirecciona al usuario a la URL de autorización de OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
• El usuario hace clic en Autorizar y la página de autorización de OAuth2 lo redirecciona a https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants .
• El redireccionamiento anterior (de vuelta a http://script.google.com/...) hace que el navegador solicite /usercallback, lo que invoca el método especificado por StateTokenBuilder.withMethod(method).

Volver

StateTokenBuilder: Es un objeto que se usa para continuar el proceso de compilación del token de estado.

---

newTrigger(functionName)

Comienza el proceso de creación de un activador instalable que, cuando se activa, llama a una función determinada.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Antes de crear un activador, verifica que la función asociada tenga todos los permisos de OAuth necesarios.

Parámetros

Nombre	Tipo	Descripción
functionName	String	Función a la que se llama cuando se activa el disparador. Puedes usar funciones de bibliotecas incluidas, como Library.libFunction1.

Volver

TriggerBuilder: Es un objeto que se usa para continuar el proceso de compilación del activador.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp

---

requireAllScopes(authMode)

Valida si el usuario otorgó su consentimiento para todos los permisos solicitados por la secuencia de comandos. Usa este método si un flujo de ejecución depende de todos los permisos que solicita una secuencia de comandos. Si falta algún consentimiento, este método finaliza la ejecución actual y renderiza un mensaje de autorización para solicitar los consentimientos faltantes.

Este método solo funciona cuando los usuarios ejecutan la secuencia de comandos desde una plataforma que admite el consentimiento detallado, por ejemplo, desde el IDE de Apps Script. Cuando se ejecuta la secuencia de comandos sin los consentimientos necesarios desde una plataforma no compatible, como un complemento de Google Workspace, la secuencia de comandos renderiza un mensaje de autorización al comienzo de la ejecución para solicitar todos los permisos.

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

Parámetros

Nombre	Tipo	Descripción
authMode	AuthMode	Modo de autorización para el que se deben evaluar los permisos de la secuencia de comandos. En casi todos los casos, el valor de authMode debe ser ScriptApp.AuthMode.FULL, ya que ningún otro modo de autorización requiere que los usuarios otorguen la autorización.

---

requireScopes(authMode, oAuthScopes)

Valida si el usuario otorgó su consentimiento para los alcances solicitados. Usa este método si un flujo de ejecución depende de uno o más servicios. Si falta alguno de los consentimientos especificados, este método finaliza la ejecución actual y renderiza un mensaje de autorización para solicitar los consentimientos faltantes. Los permisos que no son válidos o que el script no requiere generan un error.

Este método solo funciona cuando los usuarios ejecutan la secuencia de comandos desde una plataforma que admite el consentimiento detallado, por ejemplo, desde el IDE de Apps Script. Cuando se ejecuta la secuencia de comandos sin los consentimientos necesarios desde una plataforma no compatible, como un complemento de Google Workspace, la secuencia de comandos renderiza un mensaje de autorización al comienzo de la ejecución para solicitar todos los permisos.

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

Parámetros

Nombre	Tipo	Descripción
authMode	AuthMode	Es el modo de autorización para el que se deben evaluar los permisos solicitados. En casi todos los casos, el valor de authMode debe ser ScriptApp.AuthMode.FULL, ya que ningún otro modo de autorización requiere que los usuarios otorguen la autorización.
oAuthScopes	String[]	Son los permisos de OAuth que se requieren para completar el flujo de ejecución determinado.

Métodos obsoletos

getProjectKey()

Obsoleto. Usa getScriptId() en su lugar.

Obtiene la clave del proyecto de la secuencia de comandos actual. La clave del proyecto es un identificador único para las secuencias de comandos y se usa para componer la URL de devolución de llamada que se usa junto con newStateToken().

Cuando se llama en una biblioteca, se devuelve la clave del proyecto de la secuencia de comandos más externa que se está ejecutando.

Volver

String: Es la clave del proyecto de la secuencia de comandos actual.

---

getScriptTriggers()

Obsoleto. Esta función está obsoleta y no se debe usar en secuencias de comandos nuevas.

Obtiene todos los activadores instalables asociados con el proyecto y el usuario actuales.

Logger.log(
    `Current script has ${ScriptApp.getScriptTriggers().length} triggers.`,
);

Volver

Trigger[]: Es un array de los activadores del usuario actual asociados con este proyecto.

Autorización

Las secuencias de comandos que usan este método requieren autorización con uno o más de los siguientes alcances:

• https://www.googleapis.com/auth/script.scriptapp