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 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 attende l'approvazione da parte di un utente tramite il foglio di lavoro di Fogli per riavviare il flusso di lavoro. Scopri di più sull'utilizzo dei rilanci.

Obiettivi

In questo tutorial, imparerai a:

  1. Crea una nuova cartella su Google Drive. Questa cartella viene utilizzata per archiviare e consente al flusso di lavoro di scrivere nel foglio di lavoro.
  2. Crea un foglio di lavoro Fogli Google per acquisire un'approvazione e avviare un callback a un flusso di lavoro.
  3. Utilizza Google Apps Script, una piattaforma JavaScript basata su 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 chiami il connettore API Google Sheets per accodare i dati al foglio di lavoro. Il flusso di lavoro viene eseguito, messo in pausa e poi riprende quando viene approvato un callback tramite il foglio di lavoro. Scopri di più sui connettori di Workflows.
  5. Testa l'intero processo e verifica che il flusso di lavoro prosegua come previsto.

Costi

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

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Il tutorial utilizza anche Google Workspace. I servizi di livello professionale 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 l'interfaccia a riga di comando Google Cloud 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 di selezione del progetto, seleziona o crea un progetto Google Cloud.

    Vai al selettore dei progetti

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

  3. Abilitare Compute Engine, Fogli e API Workflows.

    Abilita le API

  4. Prendi nota Account di servizio predefinito Compute Engine come lo assocerai al flusso di lavoro di questo tutorial per i test. scopi. Nuovi progetti che hanno abilitato l'API Compute Engine creare questo account di servizio con IAM di base Ruolo Editor e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puoi trovare il numero del tuo progetto nella Ti diamo il benvenuto della console Google Cloud.

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo account di servizio e di assegnargli uno o più ruoli IAM contenenti 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 controllare se la fatturazione è attivata in un progetto.

  3. Abilitare Compute Engine, Fogli e API Workflows.

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

  4. Prendi nota Account di servizio predefinito Compute Engine come lo assocerai al flusso di lavoro di questo tutorial per i test. scopi. Nuovi progetti che hanno abilitato l'API Compute Engine creare questo account di servizio con IAM di base Ruolo Editor e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puoi recuperare il numero del tuo progetto:

    gcloud projects describe PROJECT_ID

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

Crea una nuova cartella su Google Drive

Crea una nuova cartella su Google Drive. Questa cartella viene utilizzata per archiviare il foglio di lavoro. Configurando un'autorizzazione per la cartella condivisa, il flusso di lavoro è autorizzato a 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 dell'account di servizio predefinito Compute Engine.

    In questo modo, l'account di servizio avrà accesso alla cartella. Quando associ l'account di servizio al flusso di lavoro, questo avrà accesso in modifica a qualsiasi file nella cartella. Scopri di più sulla condivisione di file, cartelle e unità.

  7. Seleziona il ruolo Editor.

  8. Deseleziona la casella di controllo Invia notifiche.

  9. Fai clic su Condividi.

Creare un foglio di lavoro con Fogli Google

Quando crei un foglio di lavoro con Fogli Google, viene salvato in Google Drive. Per impostazione predefinita, il foglio di lavoro viene salvato nella cartella principale su Drive. Non è possibile creare un foglio di lavoro direttamente all'interno di una cartella specificata utilizzando l'API di Fogli Google. Tuttavia, sono alternative, ad esempio spostare il foglio di lavoro in una cartella specifica dopo lo crei, come in questo esempio. Per ulteriori informazioni, consulta Utilizzare le cartelle di Google Drive.

  1. Vai a sheets.google.com.

  2. Fai clic su Nuovo Plus.

    Il nuovo foglio di lavoro viene creato e aperto. Ogni foglio di lavoro ha un indirizzo spreadsheetId, contenenti lettere, numeri, trattini o trattini bassi. Puoi trovare ID 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é sarà necessario durante la creazione del 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 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 utilizzare anche Connettore API Fogli Google per creare un foglio di lavoro. Tieni presente che quando utilizzi il connettore, spreadsheetId può essere recuperato dal risultato di 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}

Espandere Fogli Google utilizzando Apps Script

Apps Script ti consente di creare, leggere e modificare a livello di programmazione in Fogli Google. La maggior parte degli script progettati per Fogli manipola per 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.

  1. Crea 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.

    Lo script è ora associato al foglio di lavoro. che conferiscono allo script capacità speciali per modificare l'interfaccia utente o e rispondere quando il foglio di lavoro è aperto.

    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.

  2. Puoi usare Apps Script per scrivere funzioni personalizzate che possono essere usate in Fogli Google 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 flusso di lavoro esecuzione:

      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 l'attivatore:
      1. Nell'elenco Scegli la funzione da eseguire, seleziona handleEdit.
      2. Nell'elenco Scegli quale implementazione eseguire, seleziona Principale.
      3. Nell'elenco Seleziona l'origine evento, seleziona 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'app l'account di servizio e fai clic su Consenti.

      In questo modo, il tuo progetto Apps Script potrà 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, Apps Script deve 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. A modificare il file e selezionarlo.

    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"
  ]
}

      Vengono impostati gli ambiti espliciti su:

      • Connettersi a un servizio esterno
      • Visualizzare, modificare, configurare ed eliminare i tuoi dati di Google Cloud, nonché 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 riprende quando viene eseguito un callback approvati tramite un foglio di lavoro. Il flusso di lavoro scrive in un foglio di lavoro di Fogli utilizzando il connettore dell'API Fogli Google.

Console

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

    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. In Account di servizio, seleziona l'impostazione predefinita di Compute Engine account di servizio (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  6. Fai clic su Avanti.

  7. Nell'editor del flusso di lavoro, inserisci la seguente definizione per il tuo 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}

  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 flusso di lavoro:

    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 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 tuo Google Cloud del progetto. Puoi recuperare il numero del tuo progetto:

    gcloud projects describe PROJECT_ID

Testa 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 Flussi di lavoro:

    Vai a Flussi di lavoro

  2. Nella pagina Flussi di lavoro, seleziona la workflows-awaits-callback-sheets per accedere alla relativa pagina dei dettagli.

  3. Nella pagina Dettagli flusso di lavoro, fai clic su Esegui.

  4. Fai di nuovo clic su Esegui.

    Il flusso di lavoro si avvia e il relativo 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

  5. Verifica che il flusso di lavoro abbia scritto i dettagli del richiamata 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 callback e FALSE nella colonna Approvato?.

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

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

gcloud

  1. Apri un terminale.

  2. Esegui il flusso di lavoro:

      gcloud workflows run workflows-awaits-callback-sheets

    Il flusso di lavoro si avvia e l'output dovrebbe indicare che è 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 richiamata 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 callback e FALSE nella colonna Approvato?.

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

    Dopo un paio di minuti, l'esecuzione dovrebbe riprendere e completare 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 mantenerlo senza l'aggiunta delle modifiche In questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione 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