Attività Apps Script

L'attività Apps Script ti consente di eseguire Google Apps Script dalla tua integrazione. Google Apps Script è una piattaforma di sviluppo rapido di applicazioni che lo rende veloce e applicazioni aziendali facili da creare. Per ulteriori informazioni, vedi Google Apps Script. Questa attività è utile se vuoi eseguire script personalizzati o riutilizzare quelli esistenti nell'integrazione.

Prima di iniziare

Prima di utilizzare l'attività di Apps Script, accertati di completare i seguenti passaggi:

Abilita API AppsScript

Per abilitare l'API AppsScript devi abilitare l'API AppsScript nel tuo progetto Google Cloud e il tuo account utente AppsScript per usano questa attività. Per informazioni sull'abilitazione dell'API AppsScript nel tuo progetto Google Cloud, consulta Abilitazione di un'API in un progetto Google Cloud standard. Per abilitare l'API nel tuo account utente, fai clic su Impostazioni e imposta Google Apps Script API a On.

Crea ID client OAuth 2.0

Se è disponibile un ID client OAuth 2.0, puoi saltare questo passaggio e procedere con Configura un profilo di autenticazione.

Per informazioni sulla creazione di un nuovo ID client OAuth, consulta l'articolo Creare un ID client OAuth.

Configura un profilo di autenticazione

Apigee Integration utilizza il profilo di autenticazione per connettersi a Google Cloud per il deployment e che eseguono il progetto Apps Script. Per configurare un profilo di autenticazione, segui questi passaggi:

Aggiungi l'attività Apps Script

  1. Nell'UI di Apigee, seleziona la tua organizzazione Apigee.
  2. Fai clic su Sviluppo > Integrazioni.
  3. Seleziona un'integrazione esistente o creane una nuova facendo clic su Crea integrazione.

    Se stai creando una nuova integrazione:

    1. Inserisci un nome e una descrizione nella finestra di dialogo Crea integrazione.
    2. Seleziona una regione per l'integrazione dall'elenco delle regioni supportate.
    3. Fai clic su Crea.

    Viene aperta l'integrazione nel designer dell'integrazione.

  4. Nella barra di navigazione del designer dell'integrazione, fai clic su +Aggiungi un'attività/un attivatore > Tasks per visualizzare l'elenco delle attività disponibili.
  5. Fai clic sull'elemento Apps Script e posizionalo nell'editor dell'integrazione.

Crea un profilo di autenticazione

  1. Fai clic sull'elemento Apps Script nel designer per visualizzare Apps Script di configurazione delle attività.
  2. Nel riquadro di configurazione dell'attività di Apps Script, fai clic su +Nuovo profilo di autenticazione.
  3. Nella finestra di dialogo Profilo di autenticazione, inserisci un nome e una descrizione per il profilo e imposta le seguenti proprietà:
    • Tipo di autenticazione: seleziona Codice di autorizzazione OAuth 2.0
    • Endpoint di autenticazione: inserisci https://accounts.google.com/o/oauth2/auth
    • Endpoint token: inserisci https://oauth2.googleapis.com/token
    • Client ID: inserisci l'ID client.

      L'ID client è disponibile nella dashboard del progetto Google Cloud in Credenziali > ID client OAuth 2.0.

    • Secret: inserisci il client secret.

      Il client secret è disponibile nella dashboard del progetto Google Cloud in Credenziali > ID client OAuth 2.0.

    • Ambiti: inserisci quanto segue.

      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: più ambiti possono essere separati da un singolo spazio (" ").

  4. Fai clic su Generate Access Token and Save (Genera token di accesso e salva).

    Si aprirà una schermata di autorizzazione. Accedi e fornisci il tuo consenso per le autorizzazioni elencate sullo schermo per generare il token di accesso. Se la generazione del il token di accesso è riuscito, il profilo di autenticazione è stato salvato puoi continuare a modificare l'integrazione.

di Gemini Advanced.

Configura l'attività Apps Script

Per configurare un progetto Apps Script nell'attività Apps Script: segui questi passaggi:

  1. Nel riquadro di configurazione delle attività, fai clic su Configura progetto Apps Script.

    Viene visualizzata la finestra di dialogo Configurazione di Apps Script.

  2. Puoi scegliere di collegarti a un progetto Apps Script esistente o crearne uno nuovo.

    La configurazione di un progetto Apps Script associa il progetto Apps Script alla tua integrazione in Apigee Integration.

  3. Fai clic su Salva.
  4. Fai clic su Apri progetto Apps Script.

    Nell'editor di Apps Script puoi visualizzare i seguenti file:

    • Run.gs: contiene il codice eseguibile. Scrivi lo script all'interno della funzione run. Questa funzione viene chiamata quando viene eseguita l'attività di Apps Script. Nello script, puoi utilizzare le variabili definite a livello di integrazione. Per informazioni sull'uso delle variabili di integrazione, consulta Utilizzo delle variabili di integrazione.
    • Main.gs: contiene il codice di inizializzazione da eseguire Apps Script dell'integrazione. Non modificare o modificare questo file.
    • Test.gs: contiene il codice eseguibile per le esecuzioni di test. Puoi scrivere lo script all'interno della funzione testRun per testare lo script.

    Assicurati di eseguire il deployment del progetto nel formato App web. Per sulle varie modalità di deployment, consulta Creare e gestire i deployment.

Accedi alle variabili di integrazione

L'attività Apps Script utilizza la libreria AppsScriptTask, che ti consente di usa le variabili di integrazione nello script. L'API AppsScriptTask la libreria viene importata automaticamente ed è disponibile per l'uso in run personalizzata.

Per accedere a una variabile di integrazione in Apps Script, devi passare il parametro sotto forma di parametri dell'attività nell'attività di Apps Script. I parametri dell'attività coppie chiave-valore in cui Chiave è il nome della variabile nell'attività AppsScript e Valore è il nome della variabile di integrazione corrispondente. Puoi aggiungere uno o più parametri dell'attività nella sezione Parametri attività di configurazione del deployment.

Ad esempio, se hai una variabile di integrazione denominata Product, da utilizzare in Apps Script, puoi definire Key come ProductKey e il valore Product. Nel tuo Apps Script, puoi quindi usare AppsScriptTask.getTaskParameter('ProductKey') per leggere la variabile Product.

La libreria AppsScriptTask fornisce i seguenti metodi per per accedere alle variabili di integrazione:

Nome funzione Descrizione Utilizzo

setIntegrationVariable

 Imposta il valore fornito sulla variabile.

Sintassi: setIntegrationVariable(value,value)

Esempio: 

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

getTaskParameter

 Ottiene il valore di una variabile.

Sintassi: getTaskParameter(value)

Esempio: 

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

Per visualizzare tutte le funzioni disponibili nella libreria AppsScriptTask, passa il mouse sopra la nella voce di menu AppsScriptTask nell'editor di Apps Script, fai clic su Altro > Apri in una nuova scheda.

Testare Apps Script

Prima di pubblicare l'integrazione, puoi testare lo script utilizzando la funzione testRun disponibile nel file Test.gs. Scrivi il codice di test nella funzione testRun utilizzando la libreria AppsScriptTaskTest. Questa libreria ti consente di eseguire query basate su asserzioni scenari di test e vengono importati automaticamente per essere utilizzati nella funzione testRun.

Per visualizzare tutte le funzioni disponibili nella libreria AppsScriptTaskTest, passa il mouse sopra alla voce di menu AppsScriptTaskTest nel nell'editor di Apps Script, fai clic su Altro > Apri in una nuova scheda.

L'esempio seguente mostra l'utilizzo delle funzioni della libreria 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);
}

L'esempio seguente mostra come accedere alle variabili JSON e di array nel metodo 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"]);
}

Dopo aver eseguito gli scenari di test, puoi visualizzare le asserzioni nel log di esecuzione. Per visualizzare i log, fai clic su Log esecuzione dal menu.

Best practice

Sconsigliamo di utilizzare l'attività Apps Script se hai bisogno di una latenza inferiore a 1-2 secondi per l'attività nell'integrazione.

Inoltre, consigliamo di programmare l'intera logica in un'unica attività di Apps Script, anziché più attività di Apps Script per ridurre al minimo i colli di bottiglia nelle prestazioni.

Per informazioni sui limiti di utilizzo che si applicano all'attività Apps Script, vedi Limiti di utilizzo.

Considerazioni

Quando includi l'attività di Apps Script nella progettazione dell'integrazione, tieni conto delle seguenti limitazioni di sistema:

  • Numero massimo di deployment attivi per un AppsScript: 50
  • Query al secondo (QPS) per gli eseguibili dell'API: 5000/min
  • Query al secondo (QPS) per le implementazioni di app web: 5000/min
  • Latenza per gli eseguibili dell'API: 1,5 s
  • Latenza per Webapp: 2,5 s
  • Dimensione cumulativa massima di tutte le variabili di integrazione in un AppsScript: 15 MB

Strategia di gestione degli errori

Una strategia di gestione degli errori per un'attività specifica l'azione da eseguire se l'attività non riesce a causa di un errore temporaneo. Per informazioni su come utilizzare una strategia di gestione degli errori e per conoscere i diversi tipi di strategie di gestione degli errori, consulta Strategie di gestione degli errori.

Quote e limiti

Per informazioni su quote e limiti, consulta Quote e limiti.

Passaggi successivi