Attività Apps Script

Annuncio: Application Integration è ora disponibile per il tuo progetto Google Cloud. Ora puoi utilizzare sia Apigee Integration che Application Integration all'interno dello stesso progetto Google Cloud. Scopri di più

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 rende rapida e semplice la creazione di applicazioni aziendali. Per ulteriori informazioni, consulta la sezione Google Apps Script. Questa attività è utile se vuoi eseguire script personalizzati o riutilizzare quelli esistenti nell'integrazione.

Nota: l'attività Apps Script è un servizio globale non regionalizzato.

Prima di iniziare

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

• Attiva l'API AppsScript
• Crea ID client OAuth 2.0
• Configurare un profilo di autenticazione
• Assicurati che i Controlli di servizio VPC NON siano configurati per l'Apigee Integration nel tuo progetto Google Cloud.
  Avviso: la funzione Cloud Functions non funziona o smette di funzionare se i Controlli di servizio VPC sono configurati per l'Apigee Integration nel tuo progetto Google Cloud.

Abilita API AppsScript

Per utilizzare questa attività, devi abilitare l'API AppsScript nel tuo progetto Google Cloud e il tuo account utente AppsScript. Per informazioni sull'abilitazione dell'API AppsScript nel tuo progetto Google Cloud, consulta la pagina relativa all'attivazione 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 è disponibile un ID client OAuth 2.0, puoi saltare questo passaggio e andare alla sezione Configurare 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 ed eseguire 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'UI 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.

   Viene aperta l'integrazione nel designer dell'integrazione.

4. Nella barra di navigazione integration designer, 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 il riquadro di configurazione dell'attività Apps Script.
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 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.

Nota: lo stesso utente deve creare sia il profilo di autenticazione sia eseguire il deployment di Apps Script. Se gli utenti sono diversi, Apps Script non viene eseguito.

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 creare un nuovo progetto Apps Script.

   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'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 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 scoprire 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 ti 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 passare la variabile sotto forma di parametri dell'attività all'attività di Apps Script. I parametri delle attività sono coppie chiave-valore in cui Key è il nome della variabile nell'attività AppsScript e Valore è il nome della variabile di integrazione corrispondente. Puoi aggiungere uno o più parametri delle attività nella sezione Parametri attività del riquadro di configurazione delle attività.

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

Nota: per utilizzare una variabile di integrazione in AppsScript, questa variabile deve essere aggiunta come parametro dell'attività di Apps Script.

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

• setIntegrationVariable
• getTaskParameter

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 voce di menu AppsScriptTask nell'editor di Apps Script, quindi 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 sulle 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, quindi 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à di Apps Script se hai bisogno di una latenza inferiore a 1 o 2 secondi per l'attività nell'integrazione.

Inoltre, consigliamo di programmare l'intera logica in una singola attività di Apps Script, anziché concatenare più attività di 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, 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 l'articolo sulle strategie di gestione degli errori.