Suspendre et reprendre un workflow à l'aide de rappels et de Google Sheets

Google Sheets est une solution de feuille de calcul dans le cloud qui permet de collaborer en temps réel et fournit des outils pour visualiser, traiter et communiquer des données.

Ce tutoriel explique comment créer et déployer un workflow qui crée un point de terminaison de rappel (ou webhook), enregistre l'URL de rappel dans Google Sheets, suspend l'exécution, puis attend l'approbation manuelle via la feuille de calcul Sheets pour redémarrer le workflow. En savoir plus sur l'utilisation des rappels

Objectifs

Au cours de ce tutoriel, vous allez :

  1. Créez un dossier dans Google Drive. Ce dossier permet de stocker votre feuille de calcul et permet au workflow d'écrire dans la feuille de calcul.
  2. Créez une feuille de calcul Google Sheets pour capturer une approbation et lancer un rappel vers un workflow.
  3. Utilisez Google Apps Script, une plate-forme JavaScript cloud qui vous permet de créer, de lire et de modifier des produits Google Workspace de manière programmatique, pour déclencher la reprise d'un workflow mis en veille chaque fois qu'une demande est approuvée via une mise à jour de la feuille de calcul.
  4. Créez et déployez un workflow qui appelle le connecteur de l'API Google Sheets pour ajouter des données à la feuille de calcul. Le workflow s'exécute, se met en pause, puis reprend lorsqu'un rappel est approuvé via la feuille de calcul. En savoir plus sur les connecteurs Workflows
  5. Testez l'ensemble du processus et vérifiez que le workflow se déroule comme prévu.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Le tutoriel utilise également Google Workspace. Les services de qualité professionnelle qui ne sont pas inclus dans les applications grand public gratuites de Google sont facturables.

Avant de commencer

Vous pouvez exécuter certaines des commandes suivantes dans la console Google Cloud ou à l'aide de Google Cloud CLI dans votre terminal ou Cloud Shell.

Les contraintes de sécurité définies par votre organisation peuvent vous empêcher d'effectuer les étapes suivantes. Pour obtenir des informations de dépannage, consultez la page Développer des applications dans un environnement Google Cloud limité.

Console

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  2. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

  3. Activez les API Compute Engine, Sheets et Workflows.

    Activer les API

  4. Notez le compte de service Compute Engine par défaut, car vous allez l'associer au workflow de ce tutoriel à des fins de test. Pour les nouveaux projets pour lesquels l'API Compute Engine est activée, ce compte de service est créé avec le rôle IAM d'éditeur de base et le format d'adresse e-mail suivant:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Vous trouverez le numéro de votre projet sur la page Bienvenue de la console Google Cloud.

    Pour les environnements de production, nous vous recommandons vivement de créer un compte de service et de lui attribuer un ou plusieurs rôles IAM contenant les autorisations minimales requises conformément au principe du moindre privilège.

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. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

  3. Activez les API Compute Engine, Sheets et Workflows.

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

  4. Notez le compte de service Compute Engine par défaut, car vous allez l'associer au workflow de ce tutoriel à des fins de test. Pour les nouveaux projets pour lesquels l'API Compute Engine est activée, ce compte de service est créé avec le rôle IAM d'éditeur de base et le format d'adresse e-mail suivant:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Vous pouvez récupérer votre numéro de projet:

    gcloud projects describe PROJECT_ID

    Pour les environnements de production, nous vous recommandons vivement de créer un compte de service et de lui attribuer un ou plusieurs rôles IAM contenant les autorisations minimales requises conformément au principe du moindre privilège.

Créer un dossier dans Google Drive

Créez un dossier dans Google Drive. Ce dossier permet de stocker votre feuille de calcul. En configurant une autorisation pour le dossier partagé, votre workflow est autorisé à écrire dans la feuille de calcul.

  1. Accédez à drive.google.com.
  2. Cliquez sur Nouveau > Nouveau dossier.
  3. Saisissez un nom pour le dossier.
  4. Cliquez sur Créer.
  5. Effectuez un clic droit sur votre nouveau dossier, puis sélectionnez Partager.

  6. Ajoutez l'adresse e-mail du compte de service Compute Engine par défaut.

    Cela donne au compte de service accès au dossier. Lorsque vous associez le compte de service à votre workflow, celui-ci dispose d'un accès en modification à tous les fichiers du dossier. En savoir plus sur le partage de fichiers, de dossiers et de Drive

  7. Sélectionnez le rôle Rédacteur.

  8. Décochez la case Envoyer une notification.

  9. Cliquez sur Partager,

Créer une feuille de calcul à l'aide de Google Sheets

Lorsque vous créez une feuille de calcul via Google Sheets, elle est enregistrée dans Google Drive. Par défaut, la feuille de calcul est enregistrée dans votre dossier racine sur Drive. Il n'est pas possible de créer une feuille de calcul directement dans un dossier spécifié à l'aide de l'API Google Sheets. Cependant, il existe d'autres options, comme déplacer la feuille de calcul dans un dossier spécifique après l'avoir créée, comme dans cet exemple. Pour en savoir plus, consultez la section Utiliser des dossiers Google Drive.

  1. Accédez à sheets.google.com.

  2. Cliquez sur Nouveau Plus.

    La nouvelle feuille de calcul s'ouvre. Chaque feuille de calcul est associée à une valeur spreadsheetId unique, composée de lettres, de chiffres, de traits d'union ou de traits de soulignement. Vous trouverez l'identifiant de la feuille de calcul dans une URL Google Sheets:

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

  3. Notez cet ID, car vous en aurez besoin lorsque vous créerez votre workflow.

  4. Ajoutez des en-têtes de colonne comme dans l'exemple suivant:

    Exemple de feuille de calcul pour enregistrer les approbations

    Notez que la valeur de la colonne G, Approuvé ?, est utilisée pour lancer des rappels dans le workflow.

  5. Déplacez la feuille de calcul vers le dossier Google Drive que vous avez créé précédemment:

    1. Dans la feuille de calcul, sélectionnez Fichier > Déplacer.
    2. Accédez au dossier que vous avez créé.
    3. Cliquez sur Déplacer.

Vous pouvez également utiliser le connecteur de l'API Google Sheets pour créer une feuille de calcul. Notez que lorsque vous utilisez le connecteur, le spreadsheetId peut être récupéré à partir du résultat resp. Exemple : 

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

Étendre Google Sheets à l'aide d'Apps Script

Apps Script vous permet de créer, lire et modifier des feuilles de calcul Google Sheets de façon programmatique. La plupart des scripts conçus pour Sheets manipulent des tableaux pour interagir avec les cellules, les lignes et les colonnes d'une feuille de calcul. Pour découvrir comment utiliser Apps Script avec Google Sheets, consultez le guide de démarrage rapide sur les fonctions personnalisées.

  1. Créez un projet Apps Script à partir de Google Sheets:

    1. Ouvrez votre feuille de calcul Sheets.
    2. Sélectionnez Extensions > Apps Script.
    3. Dans l'éditeur de script, cliquez sur Projet sans titre.
    4. Attribuez un nom à votre projet, puis cliquez sur Renommer.

    Votre script est désormais lié à votre feuille de calcul, ce qui lui donne des capacités spéciales pour modifier l'interface utilisateur ou répondre lorsque la feuille de calcul est ouverte.

    Un projet de script représente un ensemble de fichiers et de ressources Apps Script. Les fichiers de code d'un projet de script ont une extension .gs.

  2. Vous pouvez utiliser Apps Script pour écrire des fonctions personnalisées que vous pouvez utiliser dans Google Sheets comme une fonction intégrée. Les fonctions personnalisées sont créées à l'aide de JavaScript standard. Créez une fonction:

    1. Ouvrez votre projet Apps Script.
    2. Cliquez sur Éditeur .
    3. Un fichier de script apparaît sous la forme d'un fichier de projet nommé Code.gs. Pour modifier le fichier, sélectionnez-le.

    4. Remplacez tout code dans l'éditeur de script par le code suivant, qui lit les données de votre feuille de calcul et les transmet en entrée à l'exécution d'un workflow:

      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. Cliquez sur Enregistrer .

  3. Les déclencheurs installables Apps Script permettent à un projet de script d'exécuter une fonction spécifiée lorsque certaines conditions sont remplies, par exemple lorsqu'une feuille de calcul est ouverte ou modifiée. Créez un déclencheur:

    1. Ouvrez votre projet Apps Script.
    2. Cliquez sur Déclencheurs .
    3. Cliquez sur Ajouter un déclencheur.
    4. Dans la boîte de dialogue Ajouter un déclencheur pour VOTRE_NOM_PROJET, configurez le déclencheur :
      1. Dans la liste Choisir la fonction à exécuter, sélectionnez handleEdit.
      2. Dans la liste Choisir le déploiement à exécuter, sélectionnez Head (Tête).
      3. Dans la liste Sélectionner une source d'événements, sélectionnez À partir d'une feuille de calcul.
      4. Dans la liste Sélectionner un type d'événement, sélectionnez Lors de la modification.
      5. Dans la liste Paramètres de notification d'échec, sélectionnez M'envoyer une notification quotidienne.
    5. Cliquez sur Enregistrer.

    6. Si vous êtes invité à choisir un compte Google, sélectionnez le compte approprié, puis cliquez sur Autoriser.

      Votre projet Apps Script peut ainsi afficher, modifier, créer et supprimer vos feuilles de calcul Google Sheets, et se connecter à un service externe.

  4. Le fichier manifeste d'un projet Apps Script est un fichier JSON qui spécifie les informations de base du projet dont Apps Script a besoin pour exécuter un script. Notez que l'éditeur Apps Script masque les fichiers manifestes par défaut pour protéger les paramètres de votre projet Apps Script. Modifiez le fichier manifeste:

    1. Ouvrez votre projet Apps Script.
    2. Cliquez sur Paramètres du projet .
    3. Cochez la case Afficher le fichier manifeste "appsscript.json" dans l'éditeur.
    4. Cliquez sur Éditeur .
    5. Le fichier manifeste apparaît sous la forme d'un fichier de projet nommé appsscript.json. Pour modifier le fichier, sélectionnez-le.

    6. Le champ oauthScopes spécifie un tableau de chaînes. Pour définir les champs d'application d'autorisation que votre projet utilise, ajoutez un tableau contenant les champs d'application que vous souhaitez prendre en charge. Exemple : 

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

      Les portées explicites sont définies sur:

      • Se connecter à un service externe.
      • Consulter, modifier, configurer et supprimer vos données Google Cloud, et voir l'adresse e-mail de votre compte Google
      • Consulter, modifier, créer et supprimer toutes vos feuilles de calcul Google Sheets

    7. Cliquez sur Enregistrer .

Déployer un workflow qui écrit dans une feuille de calcul et utilise des rappels

Déployez un workflow qui s'exécute, se met en pause, puis reprend lorsqu'un rappel est approuvé via une feuille de calcul. Le workflow écrit dans une feuille de calcul Sheets à l'aide du connecteur de l'API Google Sheets.

Console

  1. Dans la console Google Cloud, accédez à la page Workflows:

    Accéder à "Workflows"

  2. Cliquez sur  Créer.

  3. Saisissez un nom pour le nouveau workflow: workflows-awaits-callback-sheets.

  4. Dans la liste Région, sélectionnez us-central1 (Iowa).

  5. Pour Compte de service, sélectionnez le compte de service Compute Engine par défaut (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  6. Cliquez sur Suivant.

  7. Dans l'éditeur de workflow, saisissez la définition suivante pour votre 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. Veillez à remplacer la valeur de l'espace réservé sheetId par votre spreadsheetId.

  9. Cliquez sur Déployer.

gcloud

  1. Créez un fichier de code source pour votre workflow:

    touch workflows-awaits-callback-sheets.yaml

  2. Dans un éditeur de texte, copiez le workflow suivant dans votre fichier de code source:

    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. Veillez à remplacer la valeur de l'espace réservé sheetId par votre spreadsheetId.

  4. Déployez le workflow en saisissant la commande suivante :

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

    Remplacez PROJECT_NUMBER par votre numéro de projet Google Cloud. Vous pouvez récupérer votre numéro de projet:

    gcloud projects describe PROJECT_ID

Tester le parcours de bout en bout

Exécutez le workflow pour tester le flux de bout en bout. L'exécution d'un workflow exécute la définition actuelle du workflow associé au workflow.

Console

  1. Dans la console Google Cloud, accédez à la page Workflows:

    Accéder à "Workflows"

  2. Sur la page Workflows (Workflows), sélectionnez le workflow workflows-awaits-callback-sheets pour accéder à sa page d'informations.

  3. Sur la page Détails du workflow, cliquez sur Exécuter.

  4. Cliquez à nouveau sur Exécuter.

    Le workflow démarre et son état d'exécution doit être En cours d'exécution. Les journaux indiquent également que le workflow est mis en veille et en attente:

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

  5. Vérifiez que le workflow a écrit les détails du rappel dans une ligne de votre feuille de calcul.

    Par exemple, vous devriez voir l'ID d'exécution de votre workflow dans la colonne ID d'exécution, un point de terminaison de rappel dans la colonne URL de rappel et FALSE dans la colonne Approuvé ?.

  6. Dans la feuille de calcul, remplacez FALSE par TRUE.

    Au bout d'une minute ou deux, l'exécution devrait reprendre, puis se terminer avec un état d'exécution de Succeeded (Réussie).

gcloud

  1. Ouvrez un terminal.

  2. Exécutez le workflow :

      gcloud workflows run workflows-awaits-callback-sheets

    Le workflow démarre et le résultat doit indiquer qu'il est mis en veille et en attente:

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

  3. Vérifiez que le workflow a écrit les détails du rappel dans une ligne de votre feuille de calcul.

    Par exemple, vous devriez voir l'ID d'exécution de votre workflow dans la colonne ID d'exécution, un point de terminaison de rappel dans la colonne URL de rappel et FALSE dans la colonne Approuvé ?.

  4. Dans la feuille de calcul, remplacez FALSE par TRUE.

    Au bout d'une minute ou deux, l'exécution devrait reprendre, puis se terminer avec un état d'exécution de SUCCEEDED.

Effectuer un nettoyage

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous souhaitez le conserver sans les modifications du présent tutoriel, supprimez les ressources créées pour ce tutoriel.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  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.

Supprimer les ressources créées dans ce tutoriel

  1. Supprimez des fichiers dans Google Drive.
  2. Supprimez un workflow.

Étape suivante