Pause e retome um fluxo de trabalho através de callbacks e do Google Sheets

O Google Sheets é uma solução de folha de cálculo baseada na nuvem que suporta a colaboração em tempo real e oferece ferramentas para visualizar, processar e comunicar dados.

Este tutorial demonstra como criar e implementar um fluxo de trabalho que cria um ponto final de retorno de chamada (ou webhook), guarda o URL de retorno de chamada no Google Sheets, pausa a execução e, em seguida, aguarda a aprovação humana através da folha de cálculo do Sheets para reiniciar o fluxo de trabalho. Saiba mais sobre a utilização de retornos de chamada.

Objetivos

Neste tutorial, vai:

  1. Crie uma nova pasta no Google Drive. Esta pasta é usada para armazenar a sua folha de cálculo e permite que o fluxo de trabalho escreva na folha de cálculo.
  2. Crie uma folha de cálculo do Google Sheets para captar uma aprovação e iniciar um retorno de chamada para um fluxo de trabalho.
  3. Use o Google Apps Script, uma plataforma JavaScript baseada na nuvem que lhe permite criar, ler e editar produtos do Google Workspace de forma programática, para acionar o recomeço de um fluxo de trabalho pausado sempre que um pedido for aprovado através de uma atualização da folha de cálculo.
  4. Crie e implemente um fluxo de trabalho que chame o conetor da API Google Sheets para acrescentar dados à folha de cálculo. O fluxo de trabalho é executado, pausado e, em seguida, retomado quando uma chamada de retorno é aprovada através da folha de cálculo. Saiba mais sobre os conetores do Workflows.
  5. Teste todo o processo e confirme se o fluxo de trabalho decorre conforme esperado.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

O tutorial também usa o Google Workspace. Os serviços de nível empresarial que não estão incluídos nas apps de consumidor gratuitas da Google são faturáveis.

Antes de começar

Pode executar alguns dos seguintes comandos na Google Cloud consola ou através da CLI Google Cloud no terminal ou no Cloud Shell.

As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

Consola

  1. Na Google Cloud consola, na página do seletor de projetos, selecione ou crie um Google Cloud projeto.

    Aceder ao seletor de projetos

  2. Certifique-se de que a faturação está ativada para o seu Google Cloud projeto. Saiba como verificar se a faturação está ativada num projeto.

  3. Ative as APIs Compute Engine, Sheets e Workflows.

    Ative as APIs

  4. Tome nota da conta de serviço predefinida do Compute Engine uma vez que a vai associar ao fluxo de trabalho neste tutorial para fins de teste. Os novos projetos que ativaram a API Compute Engine têm esta conta de serviço criada com a função básica de editor do IAM e com o seguinte formato de email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola.

    Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.

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. Certifique-se de que a faturação está ativada para o seu Google Cloud projeto. Saiba como verificar se a faturação está ativada num projeto.

  3. Ative as APIs Compute Engine, Sheets e Workflows.

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

  4. Tome nota da conta de serviço predefinida do Compute Engine uma vez que a vai associar ao fluxo de trabalho neste tutorial para fins de teste. Os novos projetos que ativaram a API Compute Engine têm esta conta de serviço criada com a função básica de editor do IAM e com o seguinte formato de email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Pode obter o número do projeto:

    gcloud projects describe PROJECT_ID

    Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.

Crie uma nova pasta no Google Drive

Crie uma nova pasta no Google Drive. Esta pasta é usada para armazenar a sua folha de cálculo. Ao configurar uma autorização para a pasta partilhada, o seu fluxo de trabalho tem permissão para escrever na folha de cálculo.

  1. Aceda a drive.google.com.
  2. Clique em Novo > Nova pasta.
  3. Introduza um nome para a pasta.
  4. Clique em Criar.
  5. Clique com o botão direito do rato na nova pasta e selecione Partilhar.

  6. Adicione o endereço de email da conta de serviço predefinida do Compute Engine.

    Isto concede à conta de serviço acesso à pasta. Quando associa a conta de serviço ao seu fluxo de trabalho, o fluxo de trabalho tem acesso de edição a qualquer ficheiro na pasta. Saiba mais sobre a partilha de ficheiros, pastas e discos.

  7. Selecione a função Editor.

  8. Desmarque a caixa de verificação Notificar pessoas.

  9. Clique em Partilhar.

Crie uma folha de cálculo com o Google Sheets

Quando cria uma folha de cálculo através do Google Sheets, esta é guardada no Google Drive. Por predefinição, a folha de cálculo é guardada na pasta raiz do Drive. Não existe uma opção para criar uma folha de cálculo diretamente numa pasta especificada através da API Google Sheets. No entanto, existem alternativas, incluindo mover a folha de cálculo para uma pasta específica depois de a criar, como é feito neste exemplo. Para mais informações, consulte o artigo Trabalhe com pastas do Google Drive.

  1. Aceda a sheets.google.com.

  2. Clique em Novo Plus.

    Isto cria e abre a sua nova folha de cálculo. Cada folha de cálculo tem um valor spreadsheetId exclusivo, com letras, números, hífenes ou sublinhados. Pode encontrar o ID da folha de cálculo num URL do Google Sheets:

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

  3. Tome nota deste ID, pois vai precisar dele quando criar o fluxo de trabalho.

  4. Adicione cabeçalhos de colunas de acordo com o seguinte exemplo:

    Exemplo de folha de cálculo para registar aprovações

    Tenha em atenção que o valor na coluna G, Aprovado?, é usado para iniciar callbacks no fluxo de trabalho.

  5. Mova a folha de cálculo para a pasta do Google Drive que criou anteriormente:

    1. Na folha de cálculo, selecione Ficheiro > Mover.
    2. Navegue até à pasta que criou.
    3. Clique em Mover.

Também pode usar o conetor da API Google Sheets para criar uma folha de cálculo. Tenha em atenção que, quando usar o conector, o elemento spreadsheetId pode ser obtido a partir do resultado resp. Por exemplo: 

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

Expanda o Google Sheets com o Apps Script

O Apps Script permite-lhe criar, ler e editar o Google Sheets de forma programática. A maioria dos scripts concebidos para o Sheets manipulam matrizes para interagir com as células, as linhas e as colunas numa folha de cálculo. Para uma introdução à utilização do Apps Script com o Google Sheets, consulte o Início rápido de funções personalizadas.

  1. Crie um projeto do Apps Script a partir do Google Sheets:

    1. Abra a folha de cálculo do Sheets.
    2. Selecione Extensões > Apps Script.
    3. No editor de scripts, clique em Projeto sem título.
    4. Atribua um nome ao projeto e clique em Mudar o nome.

    O script está agora associado à sua folha de cálculo, o que lhe confere capacidades especiais para alterar a interface do utilizador ou responder quando a folha de cálculo é aberta.

    Um projeto de script representa uma coleção de ficheiros e recursos do Apps Script. Os ficheiros de código num projeto de script têm uma extensão..gs

  2. Pode usar o Apps Script para escrever funções personalizadas que pode usar no Google Sheets tal como uma função incorporada. As funções personalizadas são criadas com JavaScript padrão. Crie uma função:

    1. Abra o seu projeto do Apps Script.
    2. Clique em Editor .
    3. Um ficheiro de script é apresentado como um ficheiro de projeto com o nome Code.gs. Para editar o ficheiro, selecione-o.

    4. Substitua qualquer código no editor de scripts pelo seguinte código que lê os dados na sua folha de cálculo e transmite-os como entrada para uma execução do fluxo de trabalho:

      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. Clique em Guardar .

  3. Os acionadores instaláveis do Apps Script permitem que um projeto de script execute uma função especificada quando determinadas condições são cumpridas, como quando uma folha de cálculo é aberta ou editada. Crie um acionador:

    1. Abra o seu projeto do Apps Script.
    2. Clique em Acionadores .
    3. Clique em Adicionar acionador.
    4. Na caixa de diálogo Adicionar acionador para YOUR_PROJECT_NAME, configure o acionador:
      1. Na lista Escolha a função a executar, selecione handleEdit.
      2. Na lista Escolha a implementação que deve ser executada, selecione Principal.
      3. Na lista Selecionar origem do evento, selecione Da folha de cálculo.
      4. Na lista Selecionar tipo de evento, selecione Na edição.
      5. Na lista Definições de notificação de falhas, selecione Notificar-me diariamente.
    5. Clique em Guardar.

    6. Se receber um pedido para escolher uma Conta Google, selecione a conta adequada e, de seguida, clique em Permitir.

      Isto permite que o seu projeto do Apps Script veja, edite, crie e elimine as suas folhas de cálculo do Google Sheets, bem como se ligue a um serviço externo.

  4. Um ficheiro de manifesto de um projeto do Apps Script é um ficheiro JSON que especifica informações básicas do projeto que o Apps Script precisa para executar um script com êxito. Tenha em atenção que o editor do Apps Script oculta os ficheiros de manifesto por predefinição para proteger as definições do seu projeto do Apps Script. Edite o ficheiro de manifesto:

    1. Abra o seu projeto do Apps Script.
    2. Clique em Definições do projeto .
    3. Selecione a caixa de verificação Mostrar ficheiro de manifesto "appsscript.json" no editor.
    4. Clique em Editor .
    5. O ficheiro de manifesto aparece como um ficheiro de projeto com o nome appsscript.json. Para editar o ficheiro, selecione-o.

    6. O campo oauthScopes especifica uma matriz de strings. Para definir os âmbitos de autorização que o seu projeto usa, adicione uma matriz com os âmbitos que quer suportados. Por exemplo: 

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

      Isto define âmbitos explícitos para:

      • Ligar a um serviço externo
      • Ver, editar, configurar e eliminar os seus Google Cloud dados e ver o endereço de email da sua Conta Google
      • Ver, editar, criar e eliminar todas as suas folhas de cálculo do Google Sheets

    7. Clique em Guardar .

Implemente um fluxo de trabalho que escreve numa folha de cálculo e usa callbacks

Implemente um fluxo de trabalho que é executado, pausado e, em seguida, retomado quando um retorno de chamada é aprovado através de uma folha de cálculo. O fluxo de trabalho escreve numa folha de cálculo do Sheets usando o conetor da API Google Sheets.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho:

    Aceda a Fluxos de trabalho

  2. Clique em Criar.

  3. Introduza um nome para o novo fluxo de trabalho: workflows-awaits-callback-sheets.

  4. Na lista Região, selecione us-central1 (Iowa).

  5. Para a Conta de serviço, selecione a conta de serviço predefinida do Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  6. Clicar em Seguinte.

  7. No editor de fluxos de trabalho, introduza a seguinte definição para o seu fluxo de trabalho:

    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. Certifique-se de que substitui o valor do marcador de posição sheetId pelo seu spreadsheetId.

  9. Clique em Implementar.

gcloud

  1. Crie um ficheiro de código-fonte para o seu fluxo de trabalho:

    touch workflows-awaits-callback-sheets.yaml

  2. Num editor de texto, copie o seguinte fluxo de trabalho para o ficheiro de código-fonte:

    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. Certifique-se de que substitui o valor do marcador de posição sheetId pelo seu spreadsheetId.

  4. Implemente o fluxo de trabalho introduzindo o seguinte 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

    Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto. Pode obter o número do projeto:

    gcloud projects describe PROJECT_ID

Teste o fluxo integral

Execute o fluxo de trabalho para testar o fluxo integral. A execução de um fluxo de trabalho executa a definição do fluxo de trabalho atual associada ao fluxo de trabalho.

Consola

  1. Na Google Cloud consola, aceda à página Fluxos de trabalho:

    Aceda a Fluxos de trabalho

  2. Na página Fluxos de trabalho, selecione o fluxo de trabalho workflows-awaits-callback-sheets para aceder à respetiva página de detalhes.

  3. Na página Detalhes do fluxo de trabalho, clique em Executar.

  4. Clique novamente em Executar.

    O fluxo de trabalho é iniciado e o respetivo estado de execução deve ser Em execução. Os registos também indicam que o fluxo de trabalho está em pausa e a aguardar:

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

  5. Verifique se o fluxo de trabalho escreveu os detalhes da chamada de retorno numa linha da sua folha de cálculo.

    Por exemplo, deve ver o ID de execução do fluxo de trabalho na coluna ID de execução, um ponto final de retorno de chamada na coluna URL de retorno de chamada e FALSE na coluna Aprovado?.

  6. Na folha de cálculo, altere o valor FALSO para VERDADEIRO.

    Após um ou dois minutos, a execução deve ser retomada e, em seguida, concluída com um estado de execução de Succeeded.

gcloud

  1. Abra um terminal.

  2. Execute o fluxo de trabalho:

      gcloud workflows run workflows-awaits-callback-sheets

    O fluxo de trabalho é iniciado e o resultado deve indicar que o fluxo de trabalho está em pausa e a aguardar:

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

  3. Verifique se o fluxo de trabalho escreveu os detalhes da chamada de retorno numa linha da sua folha de cálculo.

    Por exemplo, deve ver o ID de execução do fluxo de trabalho na coluna ID de execução, um ponto final de retorno de chamada na coluna URL de retorno de chamada e FALSE na coluna Aprovado?.

  4. Na folha de cálculo, altere o valor FALSO para VERDADEIRO.

    Após um ou dois minutos, a execução deve ser retomada e, em seguida, concluída com um estado de execução de SUCCEEDED.

Limpar

Se criou um novo projeto para este tutorial, elimine o projeto. Se usou um projeto existente e quer mantê-lo sem as alterações adicionadas neste tutorial, elimine os recursos criados para o tutorial.

Elimine o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

  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.

Elimine os recursos criados neste tutorial

  1. Elimine ficheiros no Google Drive.
  2. Elimine um fluxo de trabalho.

O que se segue?