Mettere in pausa e riprendere un flusso di lavoro utilizzando i callback e Fogli Google

Fogli Google è una soluzione di fogli di lavoro basata su cloud che supporta la collaborazione in tempo reale e fornisce strumenti per visualizzare, elaborare e comunicare i dati.

Questo tutorial mostra come creare ed eseguire il deployment di un flusso di lavoro che crea un endpoint di callback (o webhook), salva l'URL di callback in Fogli Google, mette in pausa l'esecuzione e poi attende l'approvazione umana tramite il foglio di lavoro Fogli per riavviare il flusso di lavoro. Scopri di più sull'utilizzo dei richiami.

Creare una nuova cartella su Google Drive

Crea una nuova cartella su Google Drive. Questa cartella viene utilizzata per archiviare il foglio di lavoro. Se configuri un'autorizzazione per la cartella condivisa, il flusso di lavoro può scrivere nel foglio di lavoro.

1. Accedi a drive.google.com.
2. Fai clic su Nuovo > Nuova cartella.
3. Inserisci un nome per la cartella.
4. Fai clic su Crea.
5. Fai clic con il tasto destro del mouse sulla nuova cartella e seleziona Condividi.

6. Aggiungi l'indirizzo email per il service account Compute Engine predefinito.

   In questo modo, il account di servizio ha accesso alla cartella. Quando associ ilaccount di serviziot al tuo flusso di lavoro, quest'ultimo avrà l'accesso in modifica a qualsiasi file nella cartella. Scopri di più sulla condivisione di file, cartelle e drive.

7. Seleziona il ruolo Editor.

8. Deseleziona la casella di controllo Invia notifiche.

9. Fai clic su Condividi.

Creare un foglio di lavoro utilizzando Fogli Google

Quando crei un foglio di lavoro tramite Fogli Google, questo viene salvato su Google Drive. Per impostazione predefinita, il foglio di lavoro viene salvato nella cartella principale di Drive. Non esiste alcuna opzione per creare un foglio di lavoro direttamente all'interno di una cartella specificata utilizzando l'API Google Sheets. Tuttavia, esistono alternative, ad esempio spostare il foglio di lavoro in una cartella specifica dopo averlo creato, come in questo esempio. Per saperne di più, vedi Utilizzare le cartelle di Google Drive.

1. Vai su sheets.google.com.

2. Fai clic su Nuovo .

   Viene creato e aperto un nuovo foglio di lavoro. Ogni foglio di lavoro ha un valore spreadsheetId univoco, contenente lettere, numeri, trattini o trattini bassi. Puoi trovare l'ID del foglio di lavoro in un URL di Fogli Google:

   https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0

3. Prendi nota di questo ID perché ti servirà quando creerai il flusso di lavoro.

4. Aggiungi le intestazioni di colonna in modo che corrispondano al seguente esempio:

   

   Tieni presente che il valore nella colonna G, Approvato?, viene utilizzato per avviare i callback nel flusso di lavoro.

5. Sposta il foglio di lavoro nella cartella di Google Drive che hai creato in precedenza:

   1. Nel foglio di lavoro, seleziona File > Sposta.
   2. Vai alla cartella che hai creato.
   3. Fai clic su Sposta.

Puoi anche utilizzare il connettore API Google Sheets per creare un foglio di lavoro. Tieni presente che quando utilizzi il connettore, il spreadsheetId può essere recuperato dal risultato resp. Ad esempio:

- create_spreadsheet:
    call: googleapis.sheets.v4.spreadsheets.create
    args:
      body:
      connector_params:
        scopes: ${driveScope}
    result: resp
- assign_sheet_id:
    assign:
      - sheetId: ${resp.spreadsheetId}

Estendere Fogli Google utilizzando Apps Script

Apps Script consente di creare, leggere e modificare programmaticamente i Fogli Google. La maggior parte degli script progettati per Fogli manipola gli array per interagire con le celle, le righe e le colonne di un foglio di lavoro. Per un'introduzione all'utilizzo di Apps Script con Fogli Google, consulta la guida rapida alle funzioni personalizzate.

Nota :se hai eseguito l'accesso a più Account Google contemporaneamente, potresti avere difficoltà ad accedere ad Apps Script. L'accesso multiplo o l'accesso a più Account Google contemporaneamente non è supportato per Apps Script. Per ulteriori informazioni, vedi Risolvere i problemi relativi a più Account Google.

1. Crea un progetto Apps Script da Fogli Google:

   1. Apri il foglio di lavoro Fogli.
   2. Seleziona Estensioni > Apps Script.
   3. Nell'editor di script, fai clic su Progetto senza titolo.
   4. Assegna un nome al progetto e fai clic su Rinomina.

   Lo script è ora associato al foglio di lavoro, il che gli conferisce capacità speciali per modificare l'interfaccia utente o rispondere quando il foglio di lavoro viene aperto.

   Un progetto di script rappresenta una raccolta di file e risorse Apps Script. I file di codice in un progetto script hanno un'estensione .gs.

2. Puoi utilizzare Apps Script per scrivere funzioni personalizzate che puoi utilizzare in Fogli Google proprio come una funzione integrata. Le funzioni personalizzate vengono create utilizzando JavaScript standard. Crea una funzione:

   1. Apri il progetto Apps Script.
   2. Fai clic su Editor .
   3. Un file di script viene visualizzato come file di progetto denominato Code.gs. Per modificare il file, selezionalo.

   4. Sostituisci qualsiasi codice nell'editor di script con il seguente codice che legge i dati nel foglio di lavoro e li trasmette come input a un'esecuzione del flusso di lavoro:

      function handleEdit(e) {
        var range = e.range.getA1Notation();
        var sheet = e.source;
      
        if (range.length > 1 && range[0] === 'G') {
          if (e.value == "TRUE") {
            Logger.log("Approved: TRUE");
      
            var row = range.slice(1);
            var url = sheet.getRange('E' + row).getCell(1, 1).getValue();
            var approver = sheet.getRange('F' + row).getCell(1, 1).getValue();
      
            callback(url, approver);
          }
          else {
            Logger.log("Approved: FALSE");
          }
        }
      }
      
      function callback(url, approver) {
        const headers = {
          "Authorization": "Bearer " + ScriptApp.getOAuthToken()
        };
      
        var payload = {
          'approver': approver
        };
      
        const params = {
          "method": 'POST',
          "contentType": 'application/json',
          "headers": headers,
          "payload": JSON.stringify(payload)
        };
      
      
        Logger.log("Workflow callback request to " + url);
        var response = UrlFetchApp.fetch(url, params);
        Logger.log(response);
      }

   5. Fai clic su Salva .

3. Gli attivatori installabili di Apps Script consentono a un progetto di script di eseguire una funzione specificata quando vengono soddisfatte determinate condizioni, ad esempio quando un foglio di lavoro viene aperto o modificato. Crea un trigger:

   1. Apri il progetto Apps Script.
   2. Fai clic su Attivatori .
   3. Fai clic su Aggiungi trigger.
   4. Nella finestra di dialogo Aggiungi trigger per YOUR_PROJECT_NAME, configura il trigger:
      1. Nell'elenco Scegli la funzione da eseguire, seleziona handleEdit.
      2. Nell'elenco Scegli quale deployment deve essere eseguito, seleziona Head.
      3. Nell'elenco Seleziona origine evento, seleziona Da foglio di lavoro.
      4. Nell'elenco Seleziona il tipo di evento, seleziona Modifica.
      5. Nell'elenco Impostazioni di notifica degli errori, seleziona Inviami una notifica giornaliera.
   5. Fai clic su Salva.

   6. Se ti viene chiesto di scegliere un Account Google, seleziona l'account appropriato e poi fai clic su Consenti.

      In questo modo, il tuo progetto Apps Script può visualizzare, modificare, creare ed eliminare i tuoi fogli Google e connettersi a un servizio esterno.

4. Un file manifest del progetto Apps Script è un file JSON che specifica le informazioni di base del progetto necessarie ad Apps Script per eseguire correttamente uno script. Tieni presente che l'editor Apps Script nasconde i file manifest per impostazione predefinita per proteggere le impostazioni del tuo progetto Apps Script. Modifica il file manifest:

   1. Apri il progetto Apps Script.
   2. Fai clic su Impostazioni progetto .
   3. Seleziona la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.
   4. Fai clic su Editor .
   5. Il file manifest viene visualizzato come file di progetto denominato appsscript.json. Per modificare il file, selezionalo.

   6. Il campo oauthScopes specifica un array di stringhe. Per impostare gli ambiti di autorizzazione utilizzati dal tuo progetto, aggiungi un array con gli ambiti che vuoi supportare. Ad esempio:

      {
        "timeZone": "America/Toronto",
        "dependencies": {
        },
        "exceptionLogging": "STACKDRIVER",
        "runtimeVersion": "V8",
        "oauthScopes": [
          "https://www.googleapis.com/auth/script.external_request",
          "https://www.googleapis.com/auth/cloud-platform",
          "https://www.googleapis.com/auth/spreadsheets"
        ]
      }

      In questo modo vengono impostati ambiti espliciti per:

      • Connettersi a un servizio esterno
      • Visualizzare, modificare, configurare ed eliminare i tuoi dati di Google Cloud e vedere l'indirizzo email del tuo Account Google
      • Visualizzare, modificare, creare ed eliminare tutti i tuoi fogli Google

   7. Fai clic su Salva .

   Nota: per proteggere le impostazioni del progetto, nascondi il manifest al termine della modifica deselezionando la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.

Esegui il deployment di un flusso di lavoro che scrive in un foglio di lavoro e utilizza i callback

Esegui il deployment di un workflow che viene eseguito, messo in pausa e poi ripreso quando un callback viene approvato tramite un foglio di lavoro. Il flusso di lavoro scrive in un foglio di lavoro utilizzando il connettore dell'API Fogli Google.

Console

1. Nella console Google Cloud , vai alla pagina Workflows:

   Vai a Flussi di lavoro

2. Fai clic su Crea.

3. Inserisci un nome per il nuovo workflow: workflows-awaits-callback-sheets.

4. Nell'elenco Regione, seleziona us-central1 (Iowa).

5. Per Service account, seleziona il account di servizio predefinito di Compute Engine (PROJECT_NUMBER-compute@).

6. Fai clic su Avanti.

7. Nell'editor del workflow, inserisci la seguente definizione per il workflow:

   main:
     steps:
       - init:
           assign:
           # Replace with your sheetId and make sure the service account
           # for the workflow has write permissions to the sheet
           - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
       - before_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here before waiting for callback from sheets"}
       - wait_for_sheets_callback:
           call: await_callback_sheets
           args:
             sheetId: ${sheetId}
           result: await_callback_result
       - after_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here after receiving callback from sheets"}
       - returnResult:
           return: ${await_callback_result}
   
   await_callback_sheets:
       params: [sheetId]
       steps:
           - init:
               assign:
                 - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
                 - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
                 - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
                 - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
           - create_callback:
               call: events.create_callback_endpoint
               args:
                 http_callback_method: POST
               result: callback_details
           - save_callback_to_sheets:
               call: googleapis.sheets.v4.spreadsheets.values.append
               args:
                   range: ${"Sheet1!A1:G1"}
                   spreadsheetId: ${sheetId}
                   valueInputOption: RAW
                   body:
                       majorDimension: "ROWS"
                       values:
                         - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
           - log_and_await_callback:
               try:
                 steps:
                   - log_await_start:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Started waiting for callback from sheet " + sheetId}
                   - await_callback:
                       call: events.await_callback
                       args:
                         callback: ${callback_details}
                         timeout: 3600
                       result: callback_request
                   - log_await_stop:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Stopped waiting for callback from sheet " + sheetId}
               except:
                   as: e
                   steps:
                       - log_error:
                           call: sys.log
                           args:
                               severity: "ERROR"
                               text: ${"Received error " + e.message}
           - check_null_await_result:
               switch:
                 - condition: ${callback_request == null}
                   return: null
           - log_await_result:
               call: sys.log
               args:
                 severity: INFO
                 data: ${"Approved by " + callback_request.http_request.body.approver}
           - return_await_result:
               return: ${callback_request.http_request.body}

8. Assicurati di sostituire il valore del segnaposto sheetId con il tuo spreadsheetId.

9. Fai clic su Esegui il deployment.

gcloud

1. Crea un file di codice sorgente per il workflow:

   touch workflows-awaits-callback-sheets.yaml

2. In un editor di testo, copia il seguente flusso di lavoro nel file del codice sorgente:

   main:
     steps:
       - init:
           assign:
           # Replace with your sheetId and make sure the service account
           # for the workflow has write permissions to the sheet
           - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
       - before_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here before waiting for callback from sheets"}
       - wait_for_sheets_callback:
           call: await_callback_sheets
           args:
             sheetId: ${sheetId}
           result: await_callback_result
       - after_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here after receiving callback from sheets"}
       - returnResult:
           return: ${await_callback_result}
   
   await_callback_sheets:
       params: [sheetId]
       steps:
           - init:
               assign:
                 - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
                 - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
                 - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
                 - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
           - create_callback:
               call: events.create_callback_endpoint
               args:
                 http_callback_method: POST
               result: callback_details
           - save_callback_to_sheets:
               call: googleapis.sheets.v4.spreadsheets.values.append
               args:
                   range: ${"Sheet1!A1:G1"}
                   spreadsheetId: ${sheetId}
                   valueInputOption: RAW
                   body:
                       majorDimension: "ROWS"
                       values:
                         - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
           - log_and_await_callback:
               try:
                 steps:
                   - log_await_start:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Started waiting for callback from sheet " + sheetId}
                   - await_callback:
                       call: events.await_callback
                       args:
                         callback: ${callback_details}
                         timeout: 3600
                       result: callback_request
                   - log_await_stop:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Stopped waiting for callback from sheet " + sheetId}
               except:
                   as: e
                   steps:
                       - log_error:
                           call: sys.log
                           args:
                               severity: "ERROR"
                               text: ${"Received error " + e.message}
           - check_null_await_result:
               switch:
                 - condition: ${callback_request == null}
                   return: null
           - log_await_result:
               call: sys.log
               args:
                 severity: INFO
                 data: ${"Approved by " + callback_request.http_request.body.approver}
           - return_await_result:
               return: ${callback_request.http_request.body}

3. Assicurati di sostituire il valore del segnaposto sheetId con il tuo spreadsheetId.

4. Esegui il deployment del flusso di lavoro inserendo questo comando:

   gcloud workflows deploy workflows-awaits-callback-sheets \
       --source=workflows-awaits-callback-sheets.yaml \
       --location=us-central1 \
       --service-account=PROJECT_NUMBER-compute@

   Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Puoi recuperare il numero di progetto:

   gcloud projects describe PROJECT_ID

Testare il flusso end-to-end

Esegui il workflow per testare il flusso end-to-end. L'esecuzione di un flusso di lavoro esegue la definizione attuale del flusso di lavoro associata al flusso di lavoro.

Console

1. Nella console Google Cloud , vai alla pagina Workflows:

   Vai a Flussi di lavoro

2. Nella pagina Workflow, seleziona il workflow workflows-awaits-callback-sheets per andare alla pagina dei dettagli.

3. Nella pagina Dettagli workflow, fai clic su Esegui.

4. Fai di nuovo clic su Esegui.

   Il workflow viene avviato e il suo stato di esecuzione deve essere In esecuzione. I log indicano anche che il flusso di lavoro è in pausa e in attesa:

   Execute steps here before waiting for callback from sheets
   ...
   Started waiting for callback from sheet 1JlNFFnqs760M_KDqeeeDc_qtrABZDxoalyCmRE39dpM

5. Verifica che il flusso di lavoro abbia scritto i dettagli del callback in una riga del foglio di lavoro.

   Ad esempio, dovresti vedere l'ID di esecuzione del workflow nella colonna ID esecuzione, un endpoint di callback nella colonna URL di callback e FALSE nella colonna Approvato?.

6. Nel foglio di lavoro, modifica FALSE in TRUE.

   Dopo un minuto o due, l'esecuzione dovrebbe riprendere e poi completarsi con lo stato di esecuzione Riuscita.

gcloud

1. Apri un terminale.

2. Esegui il workflow:

     gcloud workflows run workflows-awaits-callback-sheets

   Il flusso di lavoro viene avviato e l'output dovrebbe indicare che il flusso di lavoro è in pausa e in attesa:

     Waiting for execution [a8361789-90e0-467f-8bd7-ea1c81977820] to complete...working.

3. Verifica che il flusso di lavoro abbia scritto i dettagli del callback in una riga del foglio di lavoro.

   Ad esempio, dovresti vedere l'ID di esecuzione del workflow nella colonna ID esecuzione, un endpoint di callback nella colonna URL di callback e FALSE nella colonna Approvato?.

4. Nel foglio di lavoro, modifica FALSE in TRUE.

   Dopo un minuto o due, l'esecuzione dovrebbe riprendere e poi completarsi con lo stato di esecuzione SUCCEEDED.