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 su publicación como un servicio.

Propiedades

PropiedadTipoDescripción
AuthModeAuthModeUna enumeración que identifica qué categorías de servicios autorizados puede ejecutar Apps Script a través de una función activada.
AuthorizationStatusAuthorizationStatusUna enumeración que denota el estado de autorización de una secuencia de comandos.
EventTypeEventTypeUna enumeración que denota el tipo de evento activado.
InstallationSourceInstallationSourceUna enumeración que indica cómo se instaló la secuencia de comandos en el usuario como complemento.
TriggerSourceTriggerSourceUna enumeración que indica la fuente del evento que hace que el activador se active.
WeekDayWeekdayUna enumeración que representa los días de la semana.

Métodos

MétodoTipo de datos que se muestraDescripción breve
deleteTrigger(trigger)voidQuita el activador determinado para que ya no se ejecute.
getAuthorizationInfo(authMode)AuthorizationInfoObtiene un objeto que se usa para determinar si el usuario debe autorizar esta secuencia de comandos a fin de usar uno o más servicios y proporcionar la URL para un diálogo de autorización.
getIdentityToken()StringObtiene un token de identidad de OpenID Connect para el usuario real, si se otorgó el alcance openid.
getInstallationSource()InstallationSourceMuestra 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 lo instaló para todos los usuarios).
getOAuthToken()StringObtiene 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()StringObtiene el ID único del proyecto de la secuencia de comandos.
getService()ServiceObtiene 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 pertenecen a este usuario en el documento determinado, solo para esta secuencia de comandos o este complemento.
getUserTriggers(form)Trigger[]Obtiene todos los activadores instalables que posee este usuario en el formato especificado, solo para esta secuencia de comandos o este complemento.
getUserTriggers(spreadsheet)Trigger[]Obtiene todos los activadores instalables que pertenecen a este usuario en la hoja de cálculo determinada, solo para esta secuencia de comandos o este complemento.
invalidateAuth()voidInvalida la autorización que tiene el usuario efectivo para ejecutar la secuencia de comandos actual.
newStateToken()StateTokenBuilderCrea 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)TriggerBuilderInicia el proceso de creación de un activador instalable que, cuando se activa, llama a una función determinada.

Documentación detallada

deleteTrigger(trigger)

Quita el activador determinado para que ya no se ejecute. 

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

Parámetros

NombreTipoDescripción
triggerTriggerEl 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 se usa para determinar si el usuario debe autorizar esta secuencia de comandos a fin de usar uno o más servicios y proporcionar la URL para un diálogo de autorización. Si la secuencia de comandos se publica como un complemento que usa activadores instalables, esta información se puede usar a fin de controlar el acceso a secciones de código para las que el usuario no tiene la autorización necesaria. Como alternativa, el complemento puede pedirle al usuario que abra la URL del diálogo de autorización para resolver el problema. 

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

Parámetros

NombreTipoDescripción
authModeAuthModeel modo de autorización para el que se solicita la 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 autorización.

Devolvedor

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

getIdentityToken()

Obtiene un token de identidad de OpenID Connect para el usuario real, si se otorgó el alcance openid. Este alcance no está incluido 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 mostrar información adicional del usuario en el token.

El token de ID que se muestra 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 de perfil de Google del usuario efectivo. 

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Consulta la documentación de OpenID Connect para ver la lista completa de los campos (reclamaciones) que se muestran.

Devolvedor

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

getInstallationSource()

Muestra 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 lo instaló para todos los usuarios).

Devolvedor

InstallationSource: Es la fuente de instalación.

getOAuthToken()

Obtiene el token de acceso de OAuth 2.0 para el usuario efectivo. Si los alcances de OAuth de la secuencia de comandos son suficientes para autorizar a otra API de Google que normalmente requiere su propio flujo de OAuth (como el selector de Google), las secuencias de comandos pueden omitir el segundo mensaje de autorización pasando este token en su lugar. El token vence después de un tiempo (algunos minutos como mínimo); las secuencias de comandos deben manejar las fallas de autorización y llamar a este método para obtener un token nuevo cuando sea necesario.

El token que muestra este método solo incluye los alcances que la secuencia de comandos necesita actualmente. Los permisos que se autorizaron con anterioridad, pero que la secuencia de comandos ya no usan, no se incluyen en el token que se mostró. Si se necesitan permisos de OAuth adicionales de los que requiere la secuencia de comandos, se pueden especificar en el archivo de manifiesto de la secuencia de comandos.

Devolvedor

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.');

Devolvedor

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 la 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 se proporcionó la clave de proyecto con anterioridad.

Devolvedor

String: Es el ID del proyecto de la 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.
var url = ScriptApp.getService().getUrl();

Devolvedor

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 pertenecen a este usuario en el documento determinado, solo para esta secuencia de comandos o este complemento. No se puede usar este método para ver los activadores adjuntos a otras secuencias de comandos. 

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

Parámetros

NombreTipoDescripción
documentDocumentUn archivo de Documentos de Google que puede contener activadores instalables.

Devolvedor

Trigger[]: Es un array de activadores que son propiedad de 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 formato especificado, solo para esta secuencia de comandos o este complemento. No se puede usar este método para ver los activadores adjuntos a otras secuencias de comandos. 

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

Parámetros

NombreTipoDescripción
formFormUn archivo de Formularios de Google que puede contener activadores instalables.

Devolvedor

Trigger[]: Es un array de activadores que son propiedad de este usuario con el formato especificado.

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 pertenecen a este usuario en la hoja de cálculo determinada, solo para esta secuencia de comandos o este complemento. No se puede usar este método para ver los activadores adjuntos a otras secuencias de comandos. 

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

Parámetros

NombreTipoDescripción
spreadsheetSpreadsheetUn archivo de Hojas de cálculo de Google que puede contener activadores instalables.

Devolvedor

Trigger[]: Es un array de activadores que son propiedad de 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 muy útil para las funciones etiquetadas como autorización única. Debido a que las funciones de autorización únicas solo se pueden llamar a la primera ejecución después de que la secuencia de comandos haya obtenido autorización, si deseas realizar una acción después, debes revocar cualquier autorización que tenga la secuencia de comandos, de modo que el usuario pueda ver el diálogo de autorización nuevamente. 

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.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var 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 autorizada 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 para autorizar, y la página de autorización de OAuth2 lo redirecciona de nuevo 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 la solicitud del navegador se dirija a /usercallback, que invoca el método especificado por StateTokenBuilder.withMethod(method).

Devolvedor

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

newTrigger(functionName)

Inicia 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();

Parámetros

NombreTipoDescripción
functionNameStringLa función a la que se debe llamar cuando se activa el activador. Puedes usar funciones de las bibliotecas incluidas, como Library.libFunction1.

Devolvedor

TriggerBuilder: Es un objeto que se usa para continuar con 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

Métodos obsoletos