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.

Obiettivi

In questo tutorial, imparerai a:

  1. 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 nel foglio di lavoro.
  2. Crea un foglio di lavoro Google Sheets per acquisire un'approvazione e avviare un callback a un flusso di lavoro.
  3. Utilizza Google Apps Script, una piattaforma JavaScript basata sul cloud che ti 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.
  4. Crea ed esegui il deployment di un flusso di lavoro che chiama il connettore API Google Sheets per aggiungere dati al foglio di lavoro. Il flusso di lavoro viene eseguito, messo in pausa e ripreso quando un callback viene approvato tramite il foglio di lavoro. Scopri di più sui connettori di Workflows.
  5. Testa l'intero processo e verifica che il flusso di lavoro proceda come previsto.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Il tutorial utilizza anche Google Workspace. I servizi di livello aziendale che non sono inclusi nelle app per utenti finali gratuite di Google sono fatturabili.

Prima di iniziare

Puoi eseguire alcuni dei seguenti comandi nella console Google Cloud o utilizzando Google Cloud CLI nel 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

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

    Vai al selettore dei progetti

  2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud . Scopri come verificare se la fatturazione è abilitata per un progetto.

  3. Abilita le API Compute Engine, Sheets e Workflows.

    Abilita le API

  4. Prendi nota dell'account di servizio predefinito di Compute Engine, in quanto lo assocerai al flusso di lavoro in questo tutorial a scopo di test. I nuovi progetti in cui è stata abilitata l'API Compute Engine hanno questo account di servizio creato con il ruolo Editor di base IAM e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puoi trovare il numero di progetto nella pagina Benvenuto della console Google Cloud .

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo service account e concedergli uno o più ruoli IAM che contengano le autorizzazioni minime richieste e di seguire il principio del privilegio minimo.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud . Scopri come verificare se la fatturazione è abilitata per un progetto.

  3. Abilita le API Compute Engine, Sheets e Workflows.

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

  4. Prendi nota dell'account di servizio predefinito di Compute Engine, in quanto lo assocerai al flusso di lavoro in questo tutorial a scopo di test. I nuovi progetti in cui è stata abilitata l'API Compute Engine hanno questo account di servizio creato con il ruolo Editor di base IAM e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puoi recuperare il numero di progetto:

    gcloud projects describe PROJECT_ID

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo service account e concedergli uno o più ruoli IAM che contengano le autorizzazioni minime richieste e di 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 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 predefinito di Compute Engine.

    In questo modo, il account di servizio ha accesso alla cartella. Quando associ ilaccount di serviziot al tuo flusso di lavoro, quest'ultimo avrà 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 Fogli Google. Tuttavia, esistono alternative, tra cui lo spostamento del foglio di lavoro in una cartella specifica dopo la creazione, come in questo esempio. Per saperne di più, vedi Utilizzare le cartelle di Google Drive.

  1. Vai alla pagina sheets.google.com.

  2. Fai clic su Nuovo Plus.

    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 crei il flusso di lavoro.

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

    Esempio di foglio di lavoro per registrare le approvazioni

    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 manipolano 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.

  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 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 In caso di 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 di un 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 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 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 .

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

Esegui il deployment di un flusso di lavoro 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 flusso di lavoro: 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@developer.gserviceaccount.com).

  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@developer.gserviceaccount.com

    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 flusso di lavoro 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 Flussi di lavoro, seleziona il flusso di lavoro workflows-awaits-callback-sheets per andare alla pagina dei dettagli.

  3. Nella pagina Dettagli flusso di lavoro, 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 workflow è 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 flusso di lavoro 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 flusso di lavoro:

      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 flusso di lavoro 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 completarsi con uno 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 creato per il tutorial.

Per eliminare il progetto:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimina le risorse create in questo tutorial

  1. Eliminare file su Google Drive.
  2. Elimina un flusso di lavoro.

Passaggi successivi