Attività Apps Script

L'attività Apps Script ti consente di eseguire Google Apps Script dalla tua integrazione. Google Apps Script è una piattaforma per lo sviluppo rapido di applicazioni che rende facile e veloce la creazione di applicazioni aziendali. Per ulteriori informazioni, consulta Google Apps Script. Questa attività è utile quando vuoi eseguire script personalizzati o riutilizzare quelli esistenti nell'integrazione.

Prima di iniziare

Prima di utilizzare l'attività Apps Script, accertati di completare le seguenti operazioni:

Abilita API AppsScript

Per utilizzare questa attività, devi attivare l'API AppsScript nel progetto Google Cloud e nel tuo account utente AppsScript. Per informazioni sull'abilitazione dell'API AppsScript nel progetto Google Cloud, vedi 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 su On.

Crea ID client OAuth 2.0

Se hai a disposizione un ID client OAuth 2.0, puoi saltare questo passaggio e passare alla sezione Configurare un profilo di autenticazione.

Per informazioni sulla creazione di un nuovo ID client OAuth, consulta 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 l'esecuzione del progetto Apps Script. Per configurare un profilo di autenticazione, segui questi passaggi:

Aggiungi l'attività Apps Script

  1. Nell'interfaccia utente di Apigee, seleziona la tua organizzazione Apigee.
  2. Fai clic su Sviluppa > 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.

    In questo modo viene aperta l'integrazione nel designer dell'integrazione.

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

Crea un profilo di autenticazione

  1. Fai clic sull'elemento Apps Script nel designer per visualizzare il riquadro di configurazione delle attività di Apps Script.
  2. Nel riquadro di configurazione delle attività dell'attività 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
    • ID client: 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 i seguenti valori:

      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 uno spazio (" ").

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

    Il sistema ti reindirizzerà a una schermata di autorizzazione. Accedi e dai il consenso alle autorizzazioni elencate sullo schermo per generare il token di accesso. Se la generazione del token di accesso ha esito positivo, il profilo di autenticazione viene salvato e puoi continuare a modificare l'integrazione.

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 di crearne uno nuovo.

    La configurazione di un progetto Apps Script associa il progetto Apps Script all'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 richiamata quando viene eseguita l'attività Apps Script. Nello script, puoi utilizzare le variabili definite a livello di integrazione. Per informazioni sull'utilizzo delle variabili di integrazione, consulta Utilizzo delle variabili di integrazione.
    • Main.gs: contiene il codice di inizializzazione per eseguire Apps Script dall'integrazione. Non modificare o modificare questo file.
    • Test.gs: contiene il codice eseguibile per le esecuzioni del test. Puoi scrivere lo script all'interno della funzione testRun per testarlo.

    Assicurati di eseguire il deployment del progetto nel formato App web. Per saperne di più 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 consente di utilizzare le variabili di integrazione nello script. La libreria AppsScriptTask viene importata automaticamente ed è disponibile per l'utilizzo nella funzione run.

Per accedere a una variabile di integrazione in Apps Script, devi trasmetterla sotto forma di parametri dell'attività all'attività Apps Script. I parametri dell'attività sono 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à del riquadro di configurazione delle attività.

Ad esempio, se disponi di una variabile di integrazione denominata Product che vuoi utilizzare in Apps Script, puoi definire Key come ProductKey e il valore come Product. In Apps Script, puoi quindi utilizzare AppsScriptTask.getTaskParameter('ProductKey') per leggere la variabile Product.

La libreria AppsScriptTask offre i seguenti metodi 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

 Restituisce 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 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 consente di eseguire scenari di test basati su asserzioni e viene importata automaticamente per essere utilizzata nella funzione testRun.

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

Il seguente esempio 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);
}

Il seguente esempio mostra come accedere alle variabili JSON e 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 Execution. Per visualizzare i log, fai clic su Log di esecuzione dal menu.

best practice

Non è consigliabile utilizzare l'attività Apps Script se richiedi una latenza inferiore a 1-2 secondi per l'attività nell'integrazione.

Inoltre, consigliamo di codificare tutta la logica in una singola attività Apps Script, anziché concatenare più attività Apps Script, per ridurre al minimo i colli di bottiglia delle prestazioni.

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

Considerazioni

Quando includi l'attività Apps Script nella progettazione dell'integrazione, considera le seguenti limitazioni di sistema:

  • Numero massimo di deployment attivi per un AppsScript: 50
  • Query al secondo (QPS) per gli eseguibili API: 5000/min
  • Query al secondo (QPS) per i deployment di app web: 5000/min
  • Latenza per gli eseguibili API: 1,5 s
  • Latenza per app web: 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 intraprendere 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.