Consulta i connettori supportati per Application Integration.

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 consente di creare in modo semplice e veloce applicazioni aziendali. Per ulteriori informazioni, consulta 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 l'API Apps Script

Per utilizzare questa operazione, devi attivare l'API Apps Script nel tuo progetto Google Cloud e nel tuo account utente Apps Script. 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

Application 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. Nella console Google Cloud, vai alla pagina Application Integration.

    Vai ad Application Integration

  2. Nel menu di navigazione, fai clic su Integrations (Integrazioni).

    Viene visualizzata la pagina Integrazioni, in cui sono elencate tutte le integrazioni disponibili nel progetto Google Cloud.

  3. Seleziona un'integrazione esistente o fai clic su Crea integrazione per crearne una nuova.

    Se stai creando una nuova integrazione:

    1. Inserisci un nome e una descrizione nel riquadro Crea integrazione.
    2. Seleziona una regione per l'integrazione.
    3. Seleziona un account di servizio per l'integrazione. Puoi modificare o aggiornare i dettagli dell'account di servizio di un'integrazione in qualsiasi momento dal riquadro Riepilogo dell'integrazione nella barra degli strumenti dell'integrazione.
    4. Fai clic su Crea.

    L'integrazione viene aperta nell'editor dell'integrazione.

  4. Nella barra di navigazione dell'editor dell'integrazione, fai clic su Attività per visualizzare l'elenco delle attività e dei connettori 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 carattere 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.

Configura l'attività Apps Script

Per configurare un progetto Apps Script nell'attività Apps Script, svolgi i seguenti passaggi:

  1. Nel riquadro di configurazione dell'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 alla tua integrazione in Integrazione delle applicazioni.

  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à 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 testarlo.

    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 metodo 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. In Apps Script, puoi utilizzare AppsScriptTask.getTaskParameter('ProductKey') per leggere la variabile Prodotto.

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 la voce di menu AppsScriptTaskTest 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 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

Non consigliamo di utilizzare l'attività di 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 delle prestazioni.

Per informazioni sui limiti di utilizzo che si applicano all'attività Apps Script, consulta 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.

Esclusioni SLA

L'attività di Apps Script ha una dipendenza dal prodotto Google Apps Script. Poiché questa dipendenza è esterna ad Application Integration, tutte le esecuzioni active di integrazioni non riuscite a causa dell'errore in l'attività Apps Script, sono escluse la sezione Application Integration Termini e condizioni dell'accordo sul livello del servizio (SLA).

Quote e limiti

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

Passaggi successivi