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

Fogli Google è una soluzione per 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 illustra 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 di Fogli per riavviare il flusso di lavoro. Scopri di più sull'utilizzo dei callback.

Obiettivi

In questo tutorial, imparerai a:

Crea una nuova cartella su Google Drive. Questa cartella viene utilizzata per archiviare il foglio di lavoro e consente al flusso di lavoro di scrivere.
Crei un foglio di lavoro Fogli Google per acquisire un'approvazione e avviare un callback a un flusso di lavoro.
Utilizza Google Apps Script, una piattaforma JavaScript basata su cloud che consente di creare, leggere e modificare in modo programmatico i prodotti Google Workspace per attivare la ripresa di un flusso di lavoro in pausa ogni volta che una richiesta viene approvata tramite un aggiornamento del foglio di lavoro.
Crea ed esegui il deployment di un flusso di lavoro che chiami il connettore dell'API Fogli Google per aggiungere dati al foglio di lavoro. Il flusso di lavoro viene eseguito, messo in pausa e poi ripreso quando un callback viene approvato tramite il foglio di lavoro. Scopri di più sui connettori Workflows.
Testare l'intero processo e verificare che il flusso di lavoro proceda come previsto.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Il tutorial utilizza anche Google Workspace. I servizi di livello aziendale non inclusi nelle app consumer gratuite di Google sono fatturabili.

Prima di iniziare

Puoi eseguire alcuni dei comandi seguenti nella console Google Cloud o utilizzando Google Cloud CLI nel tuo terminale o in Cloud Shell.

I vincoli di sicurezza definiti dalla tua organizzazione potrebbero impedirti di completare i passaggi seguenti. Per informazioni sulla risoluzione dei problemi, vedi Sviluppare applicazioni in un ambiente Google Cloud vincolato.

Console

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

Vai al selettore progetti
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud. Scopri come verificare se la fatturazione è abilitata in un progetto.
Abilita le API Compute Engine, Fogli e Workflows.

Abilita le API
I nuovi progetti che hanno abilitato l'API Compute Engine hanno un account di servizio predefinito di Compute Engine creato con il ruolo Editor di base IAM e con il seguente formato email:
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
Puoi trovare il numero del progetto nella pagina Ti diamo il benvenuto della console Google Cloud.

Prendi nota di questo account di servizio perché lo assocerai al flusso di lavoro in questo tutorial a scopo di test.

Importante: per gli ambienti di produzione, consigliamo vivamente di creare un nuovo account di servizio e di concedergli uno o più ruoli IAM che contengono le autorizzazioni minime richieste e seguire il principio del privilegio minimo.

gcloud

Nella console Google Cloud, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud. Scopri come verificare se la fatturazione è abilitata in un progetto.

Abilita le API Compute Engine, Fogli e Workflows.

gcloud services enable \
    compute.googleapis.com \
    sheets.googleapis.com \
    workflows.googleapis.com

I nuovi progetti che hanno abilitato l'API Compute Engine hanno un account di servizio predefinito di Compute Engine creato con il ruolo Editor di base IAM e con il seguente formato email:
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
Puoi recuperare il numero del progetto:
```
gcloud projects describe PROJECT_ID
```
Prendi nota di questo account di servizio perché lo assocerai al flusso di lavoro in questo tutorial a scopo di test.

Importante: per gli ambienti di produzione, consigliamo vivamente di creare un nuovo account di servizio e di concedergli uno o più ruoli IAM che contengono le autorizzazioni minime richieste e seguire il principio del privilegio minimo.

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 imposti un'autorizzazione per la cartella condivisa, il flusso di lavoro può scrivere nel foglio di lavoro.

Accedi a drive.google.com.
Fai clic su Nuovo > Nuova cartella.
Inserisci un nome per la cartella.
Fai clic su Crea.
Fai clic con il pulsante destro del mouse sulla nuova cartella e seleziona Condividi.
Aggiungi l'indirizzo email dell'account di servizio predefinito di Compute Engine.

In questo modo l'account di servizio potrà accedere alla cartella. Quando associ l'account di servizio al flusso di lavoro, quest'ultimo avrà accesso in modifica a qualsiasi file nella cartella. Scopri di più sulla condivisione di file, cartelle e Drive.
Seleziona il ruolo Editor.
Deseleziona la casella di controllo Invia notifiche.
Fai clic su Condividi.

Creare un foglio di lavoro con Fogli Google

I fogli di lavoro creati con Fogli Google vengono salvati su Google Drive. Per impostazione predefinita, il foglio di lavoro viene salvato nella cartella principale di Drive. Non esiste un'opzione per creare un foglio di lavoro direttamente in una cartella specificata con l'API Fogli Google. Tuttavia, esistono alternative, tra cui spostare il foglio di lavoro in una cartella specifica dopo averlo creato, come avviene in questo esempio. Per ulteriori informazioni, vedi Lavorare con le cartelle di Google Drive.

Vai a sheets.google.com.
Fai clic su Nuovo .

Verrà creato e aperto il 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
Prendi nota di questo ID, che sarà necessario quando crei il flusso di lavoro.
Aggiungi le intestazioni di colonna in base all'esempio seguente:

Tieni presente che il valore nella colonna G, Approvata?, viene utilizzato per avviare i callback nel flusso di lavoro.
Sposta il foglio di lavoro nella cartella di Google Drive creata 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 Fogli Google per creare un foglio di lavoro. Tieni presente che quando utilizzi il connettore, è possibile recuperare spreadsheetId 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}

Estendi Fogli Google utilizzando Apps Script

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

Creare un progetto Apps Script da Fogli Google:
1. Apri il foglio di lavoro di 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.
Ora lo script è associato al foglio di lavoro, in modo da poterlo modificare in modo particolare per modificare l'interfaccia utente o per rispondere all'apertura del foglio di lavoro.

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

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

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

Sostituisci qualsiasi codice nell'editor di script con il seguente codice, che legge i dati nel foglio di lavoro e li passa 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);
}

Fai clic su Salva .

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 attivatore:
1. Apri il progetto Apps Script.
2. Fai clic su Attivatori .
3. Fai clic su Aggiungi attivatore.
4. Nella finestra di dialogo Aggiungi trigger per YOUR_PROJECT_NAME, configura l'attivatore:
  1. Nell'elenco Scegli la funzione da eseguire, seleziona handleEdit.
  2. Nell'elenco Scegli quale deployment eseguire, seleziona Head.
  3. Nell'elenco Seleziona origine evento, scegli Da foglio di lavoro.
  4. Nell'elenco Seleziona il tipo di evento, scegli Alla modifica.
  5. Nell'elenco Impostazioni di notifica di errore, seleziona Avvisami ogni giorno.
5. Fai clic su Salva.
6. Se ti viene chiesto di scegliere un Account Google, seleziona l'account appropriato, quindi fai clic su Consenti.
  
  In questo modo il tuo progetto Apps Script potrà visualizzare, modificare, creare ed eliminare i tuoi fogli di lavoro di Fogli Google e di connettersi a un servizio esterno.
Un file manifest di 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 di Apps Script nasconde i file manifest per impostazione predefinita per proteggere le impostazioni del 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 che siano supportati. 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"
  ]
}
```
  Gli ambiti espliciti vengono impostati su:
  - Connettersi a un servizio esterno
  - Visualizzare, modificare, configurare ed eliminare i tuoi dati Google Cloud e visualizzare 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 file manifest "appsscript.json" nell'editor.

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

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

Console

Nella console Google Cloud, vai alla pagina Flussi di lavoro:

Vai a Workflows
Fai clic su Crea.
Inserisci un nome per il nuovo flusso di lavoro: workflows-awaits-callback-sheets.
Nell'elenco Regione, seleziona us-central1 (Iowa).
Per Account di servizio, seleziona l'account di servizio predefinito di Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com).
Tocca Avanti.

Nell'editor del flusso di lavoro, inserisci la definizione seguente per il flusso di lavoro:

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}

Assicurati di sostituire il valore segnaposto sheetId con il tuo spreadsheetId.
Fai clic su Esegui il deployment.

gcloud

Crea un file di codice sorgente per il tuo flusso di lavoro:
```
touch workflows-awaits-callback-sheets.yaml
```

In un editor di testo, copia il seguente flusso di lavoro nel file di 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}

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

Esegui il deployment del flusso di lavoro inserendo il seguente comando:

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

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

gcloud projects describe PROJECT_ID

Testare il flusso end-to-end

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

Console

Nella console Google Cloud, vai alla pagina Flussi di lavoro:

Vai a Workflows
Nella pagina Flussi di lavoro, seleziona il flusso di lavoro workflows-awaits-callback-sheets per accedere alla relativa pagina dei dettagli.
Nella pagina Dettagli flusso di lavoro, fai clic su Esegui.
Fai di nuovo clic su Execute (Esegui).

Il flusso di lavoro viene avviato e il suo stato di esecuzione deve essere In esecuzione. I log indicano inoltre 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
```
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 esecuzione del flusso di lavoro nella colonna ID esecuzione, un endpoint di callback nella colonna URL di callback e FALSE nella colonna Approvato?.
Nel foglio di lavoro, modifica il valore da FALSE a TRUE.

Dopo uno o due minuti, l'esecuzione dovrebbe riprendere e completata con lo stato Riuscito.

gcloud

Apri un terminale.

Esegui il flusso di lavoro:

  gcloud workflows run workflows-awaits-callback-sheets

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

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

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 esecuzione del flusso di lavoro nella colonna ID esecuzione, un endpoint di callback nella colonna URL di callback e FALSE nella colonna Approvato?.
Nel foglio di lavoro, modifica il valore da FALSE a TRUE.

Dopo uno o due minuti, l'esecuzione dovrebbe riprendere e poi essere completata con lo stato di esecuzione SUCCEEDED.

Esegui la pulizia

Se hai creato un nuovo progetto per questo tutorial, elimina il progetto. Se hai utilizzato un progetto esistente e vuoi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività in questo documento, quando lo elimini elimini anche qualsiasi altro lavoro svolto nel progetto.
Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Nella console Google Cloud, vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

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

Obiettivi

Costi

Prima di iniziare

Console

gcloud

Creare una nuova cartella su Google Drive

Creare un foglio di lavoro con Fogli Google

Estendi Fogli Google utilizzando Apps Script

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

Console

gcloud

Testare il flusso end-to-end

Console

gcloud

Esegui la pulizia

Elimina il progetto

Elimina le risorse create in questo tutorial

Passaggi successivi