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 quando vuoi eseguire script personalizzati o riutilizzare script esistenti nell'integrazione.

Prima di iniziare

Prima di utilizzare l'attività di Apps Script, assicurati 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 su come attivare l'API Apps Script nel tuo progetto Google Cloud, consulta Abilitazione di un'API in un progetto Google Cloud standard. Per attivare l'API nel tuo account utente, fai clic su Impostazioni e imposta Google Apps Script API su On.

Creare un ID client OAuth 2.0

Se hai un ID client OAuth 2.0 disponibile, puoi saltare questo passaggio e andare a Configurare un profilo di autenticazione.

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

Configurare un profilo di autenticazione

Application Integration utilizza il profilo di autenticazione per connettersi a Google Cloud per eseguire il deployment e eseguire il progetto Apps Script. Per configurare un profilo di autenticazione:

Aggiungi l'attività Apps Script

  1. Nella console Google Cloud, vai alla pagina Integrazione delle applicazioni.

    Vai ad Application Integration

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

    Viene visualizzata la pagina Integrazioni, che elenca 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 di integrazione.
    4. Fai clic su Crea.

    Viene visualizzata l'integrazione nell'editor di integrazione.

  4. Nella barra di navigazione dell'editor di integrazione, fai clic su Attività per visualizzare l'elenco di attività e connettori disponibili.
  5. Fai clic e posiziona l'elemento Apps Script 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à 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
    • 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 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 Genera token di accesso e salva.

    Viene visualizzata 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 va a buon fine, 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, 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 vedere 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'utilizzo delle variabili di integrazione, consulta la sezione Utilizzare le variabili di integrazione.
    • Main.gs: contiene il codice di inizializzazione per eseguire Apps Script dalla tua integrazione. Non 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 in formato App web. Per maggiori informazioni sulle varie modalità di deployment, consulta Creare e gestire i deployment.

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

Ad esempio, se hai una variabile di integrazione denominata Prodotto che vuoi utilizzare nel tuo script di Apps, puoi definire Chiave come ProductKey e il valore come Prodotto. In Apps Script, puoi utilizzare AppsScriptTask.getTaskParameter('ProductKey') per leggere la variabile Prodotto.

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

Nome funzione Descrizione Utilizzo

setIntegrationVariable

 Imposta il valore fornito alla variabile.

Sintassi: setIntegrationVariable(value,value)

Esempio: 

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

getTaskParameter

 Recupera 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 script di Apps, fai clic su Altro > Apri in una nuova scheda.

Testare il tuo script di 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 casi di test basati su affermazioni e viene importata automaticamente per l'utilizzo 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 i casi di test, puoi visualizzare le asserzioni nel log di esecuzione. Per visualizzare i log, fai clic su Log di esecuzione nel 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, ti consigliamo di codificare tutta la logica in un'unica 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, consulta Limiti di utilizzo.

Considerazioni

Quando includi l'attività Apps Script nel design dell'integrazione, tieni presenti le seguenti limitazioni del sistema:

  • Deployment attivi massimi per un progetto AppsScript: 50
  • Query al secondo (QPS) per gli eseguibili dell'API: 5000/min
  • Query al secondo (QPS) per i deployment di app web: 5000/min
  • Latenza per gli eseguibili API: 1,5 secondi
  • Latenza per la web app: 2,5 s
  • Dimensioni cumulative massime di tutte le variabili di integrazione in un progetto 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 va a buon fine a causa di un errore temporaneo. Per informazioni su come utilizzare una strategia di gestione degli errori e sui diversi tipi di strategie di gestione degli errori, consulta Strategie di gestione degli errori.

Esclusioni SLA

L'attività Apps Script ha una dipendenza dal prodotto Google Apps Script. Poiché questa dipendenza è esterna all'integrazione delle applicazioni, tutte le esecuzioni di integrazioni di active che non vanno a buon fine a causa di un errore nell'attività di Apps Script sono escluse dai termini e dalle condizioni dell'accordo sul livello del servizio (SLA) per l'integrazione delle applicazioni.

Quote e limiti

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

Passaggi successivi