Consulta los conectores compatibles para Application Integration.

Tarea de Apps Script

La tarea Apps Script te permite ejecutar Google Apps Script desde tu integración. Google Apps Script es una plataforma de desarrollo de aplicaciones rápida que permite crear aplicaciones empresariales con rapidez y facilidad. Para obtener más información, consulta Google Apps Script. Esta tarea es útil cuando deseas ejecutar secuencias de comandos personalizadas o volver a usar las secuencias de comandos existentes en la integración.

Nota: La tarea de Apps Script es un servicio global no regionalizado.

Antes de comenzar

Antes de usar la tarea de Apps Script, asegúrate de completar los siguientes pasos:

• Habilita la API de AppsScript
• Crea un ID de cliente de OAuth 2.0
• Configura un perfil de autenticación
• Asegúrate de que los Controles del servicio de VPC NO estén configurados para Application Integration en tu proyecto de Google Cloud.
  Advertencia: Cloud Function no funciona o deja de funcionar si los Controles del servicio de VPC están configurados para Application Integration en tu proyecto de Google Cloud.

Habilita la API de AppsScript

Debes habilitar la API de AppsScript en tu proyecto de Google Cloud y tu cuenta de usuario de AppsScript para usar esta tarea. Si deseas obtener información para habilitar la API de AppsScript en tu proyecto de Google Cloud, consulta Habilita una API en un proyecto estándar de Google Cloud. Para habilitar la API en tu cuenta de usuario, haz clic en Configuración y configura Google Apps Script API como On.

Crea un ID de cliente de OAuth 2.0

Si tienes un ID de cliente de OAuth 2.0 disponible, puedes omitir este paso y continuar con la configuración de un perfil de autenticación.

Para obtener información sobre cómo crear un nuevo ID de cliente de OAuth, consulta la página Crea un ID de cliente de OAuth.

Configura un perfil de autenticación

Application Integration usa el perfil de autenticación para conectarse a Google Cloud a fin de implementar y ejecutar el proyecto de Apps Script. Para configurar un perfil de autenticación, sigue estos pasos:

Agrega la tarea de Apps Script

1. En la consola de Google Cloud, ve a la página Application Integration.

   Ir a Application Integration

2. En el menú de navegación, haz clic en Integraciones.

   Aparecerá la página Integraciones con todas las integraciones disponibles en el proyecto de Google Cloud.

3. Selecciona una integración existente o haz clic en Crear integración para crear una nueva.

   Si creas una integración nueva, haz lo siguiente:

   1. Ingresa un nombre y una descripción en el panel Create Integration.
   2. Selecciona una región para la integración.
      Nota: En el menú desplegable Regiones, solo se enumeran las regiones aprovisionadas en el proyecto de Google Cloud. Para aprovisionar una región nueva, haz clic en Habilitar región. Consulta Habilita una región nueva para obtener más información.
   3. Selecciona una cuenta de servicio para la integración. Puedes cambiar o actualizar los detalles de la cuenta de servicio de una integración en cualquier momento desde el panel Resumen de la integración en la barra de herramientas de integración.
      Nota: La opción de seleccionar una cuenta de servicio solo se muestra si habilitaste la administración de integraciones para la región seleccionada.
   4. Haz clic en Crear.

   Esto abrirá la integración en la página del editor de integración.

4. En la barra de navegación del editor de integración, haz clic en Tasks para ver la lista de tareas disponibles.
5. Haz clic y coloca el elemento Apps Script en el editor de integración.

Crear un perfil de autenticación

1. Haz clic en el elemento Apps Script del diseñador para ver el panel de configuración de tareas de Apps Script.
2. En el panel de configuración de tareas de la tarea de Apps Script, haz clic en +Nuevo perfil de autenticación.
3. En el cuadro de diálogo Perfil de autenticación, ingresa un nombre y una descripción para el perfil, y configura las siguientes propiedades:
   • Tipo de autenticación: Selecciona el código de autorización de OAuth 2.0.
   • Extremo de autenticación: Ingresa https://accounts.google.com/o/oauth2/auth.
   • Extremo del token: Ingresa https://oauth2.googleapis.com/token
   • ID de cliente: Ingresa el ID de cliente.

     El ID de cliente está disponible en el panel de tu proyecto de Google Cloud en Credenciales > ID de cliente de OAuth 2.0.

   • Secret (Secreto): Ingresa el secreto del cliente.

     El secreto del cliente está disponible en el panel de tu proyecto de Google Cloud en Credenciales > ID de cliente de OAuth 2.0.

   • Alcances: Ingresa lo siguiente:

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     Nota: Varios permisos pueden separarse con un solo carácter de espacio (" ").

4. Haz clic en Generar token de acceso y guardar.

   Serás redireccionado a una pantalla de autorización. Accede y otorga tu consentimiento para los permisos enumerados en la pantalla a fin de generar el token de acceso. Si la generación del token de acceso es correcta, tu perfil de autenticación se guarda y puedes continuar editando tu integración.

Nota: El mismo usuario debe crear el perfil de autenticación, además de implementar Apps Script. Si los usuarios son diferentes, Apps Script no se ejecuta.

Configura la tarea de Apps Script

Para configurar un proyecto de Apps Script en la tarea Apps Script, sigue estos pasos:

1. En el panel de configuración de la tarea, haz clic en Configurar proyecto de Apps Script.

   Aparecerá el cuadro de diálogo Configuración de Apps Script.

2. Puedes elegir vincular un proyecto existente de Apps Script o crear un proyecto nuevo de Apps Script.

   La configuración de un proyecto de Apps Script asocia ese proyecto con tu integración en Application Integration.

3. Haz clic en Guardar.
4. Haz clic en Abrir proyecto de Apps Script.

   En el editor de Apps Script, puede ver los siguientes archivos:

   • Run.gs: Contiene el código ejecutable. Escribe tu secuencia de comandos dentro de la función run. Se llama a esta función cuando se ejecuta la tarea de Apps Script. En la secuencia de comandos, puedes usar las variables definidas en el nivel de Integración. Para obtener información sobre el uso de las variables de integración, consulta Usa variables de integración.
   • Main.gs: Contiene el código de inicialización para ejecutar Apps Script desde la integración. No edites ni modifiques este archivo.
   • Test.gs: Contiene el código ejecutable para las ejecuciones de prueba. Puedes escribir la secuencia de comandos dentro de la función testRun para probar la secuencia de comandos.

   Asegúrate de implementar el proyecto en formato Web apps. Para obtener más información sobre los diferentes modos de implementación, consulta Crea y administra implementaciones.

Accede a variables de integración

La tarea de Apps Script usa la biblioteca AppsScriptTask, que te permite usar variables de integración en la secuencia de comandos. La biblioteca AppsScriptTask se importa de forma automática y está disponible para su uso en la función run.

Para acceder a una variable de integración en tu Apps Script, debes pasar la variable en forma de parámetros de tareas a la tarea de Apps Script. Los parámetros de la tarea son pares clave-valor en los que Clave es el nombre de la variable en tu tarea de AppsScript y Valor es el nombre de la variable de integración correspondiente. Puedes agregar uno o más parámetros de tarea en la sección Parámetros de valor del panel de configuración de tareas.

Por ejemplo, si tienes una variable de integración llamada Product que deseas usar en Apps Script, puedes definir Key como ProductKey y el valor como Product. En tu Apps Script, puedes usar AppsScriptTask.getTaskParameter('ProductKey') para leer la variable Product.

Nota: Para usar una variable de integración en AppsScript, la variable debe agregarse como un parámetro de tarea a la tarea de Apps Script.

La biblioteca AppsScriptTask proporciona los siguientes métodos para acceder a las variables de integración:

• setIntegrationVariable
• getTaskParameter

Nombre de la función	Descripción	Uso
setIntegrationVariable	Establece el valor proporcionado para la variable.	Sintaxis: setIntegrationVariable(value,value) Ejemplo: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
getTaskParameter	Obtiene el valor de una variable.	Sintaxis: getTaskParameter(value) Ejemplo: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

Para ver todas las funciones disponibles en la biblioteca AppsScriptTask, desplázate sobre el elemento de menú en AppsScriptTask del editor de Apps Script y haz clic en Más Abrir en una pestaña nueva.

Prueba tu Apps Script

Antes de publicar tu integración, puedes probar la secuencia de comandos con la función testRun disponible en el archivo Test.gs. Escribe el código de prueba en la función testRun mediante la biblioteca AppsScriptTaskTest. Esta biblioteca te permite ejecutar casos de prueba basados en aserciones y se importa automáticamente para su uso en la función testRun.

Para ver todas las funciones disponibles en la biblioteca AppsScriptTaskTest, desplázate sobre el elemento de menú AppsScriptTaskTest del editor de Apps Script y haz clic en Más > Abrir en una pestaña nueva.

En el siguiente ejemplo, se muestra el uso de las funciones de la biblioteca AppsScriptTaskTest.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

En el siguiente ejemplo, se muestra cómo acceder a las variables JSON y de arreglo en el método testRun:

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);

  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

Después de ejecutar los casos de prueba, puedes ver las afirmaciones en el Registro de ejecución. Para ver los registros, haz clic en Registro de ejecución en el menú.

prácticas recomendadas

No recomendamos usar la tarea de Apps Script si necesitas una latencia menor a 1 o 2 segundos para la tarea en tu integración.

Además, te recomendamos que codifiques toda la lógica en una sola tarea Apps Script, en lugar de encadenar varias tareas Ejecutar Apps Script, para minimizar los cuellos de botella de rendimiento.

Para obtener más información sobre los límites de uso que se aplican a la tarea Apps Script, consulta Límites de uso.

Consideraciones

Cuando incluyas la tarea Apps Script en el diseño de tu integración, ten en cuenta las siguientes limitaciones del sistema:

• Cantidad máxima de implementaciones activas para AppsScript: 50
• Consultas por segundo (QPS) para ejecutables de API: 5,000 por minuto
• Consultas por segundo (QPS) para implementaciones de Webapp: 5,000 por minuto
• Latencia de los ejecutables de la API: 1.5 s
• Latencia para Webapp: 2.5 s
• Tamaño acumulativo máximo de todas las variables de integración en una AppsScript: 15 MB

Estrategia de manejo de errores

Una estrategia de manejo de errores de una tarea específica la acción que se debe realizar si la tarea falla debido a un error temporal. Para obtener información sobre cómo usar una estrategia de manejo de errores y conocer los diferentes tipos de estrategias de manejo de errores, consulta Estrategias de manejo de errores.

Exclusiones del ANS

La tarea Apps Script depende del producto Google Apps Script. Como esta dependencia es externa a Application Integration, todas las ejecuciones de integraciones de active que fallan debido al error en la tarea de Apps Script, se excluyen de los Términos y Condiciones del Acuerdo de Nivel de Servicio (ANS) de Application Integration.