Pausar e retomar um fluxo de trabalho usando callbacks e o app Planilhas Google

O Planilhas Google é uma solução de planilhas baseada na nuvem compatível com colaboração em tempo real e que oferece ferramentas para visualizar, processar e comunicar dados.

Neste tutorial, demonstramos como criar e implantar um fluxo de trabalho que cria um endpoint de callback (ou webhook), salva o URL de callback no Planilhas Google, pausa a execução e aguarda a aprovação humana dessa planilha para reiniciar o fluxo de trabalho. Saiba mais sobre como usar callbacks.

Objetivos

Com este tutorial, você vai:

  1. Crie uma pasta no Google Drive. Ela é usada para armazenar sua planilha e permite que o fluxo de trabalho grave nela.
  2. Crie uma planilha do Planilhas Google para capturar uma aprovação e iniciar um callback para um fluxo de trabalho.
  3. Use o Google Apps Script, uma plataforma JavaScript baseada na nuvem que permite criar, ler e editar produtos do Google Workspace de maneira programática, para acionar a retomada de um fluxo de trabalho pausado sempre que uma solicitação for aprovada por meio de uma atualização da planilha.
  4. Criar e implantar um fluxo de trabalho que chama o conector da API Google Sheets para anexar dados à planilha. O fluxo de trabalho é executado, pausado e retomado quando um callback é aprovado pela planilha. Saiba mais sobre os conectores do Workflows.
  5. Teste todo o processo e confirme se o fluxo de trabalho continua como esperado.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados 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 nos apps gratuitos do Google para o consumidor são faturáveis.

Antes de começar

É possível executar alguns dos comandos a seguir no console do Google Cloud ou usando a Google Cloud CLI no seu terminal ou no Cloud Shell.

As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito do Google Cloud.

Console

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

    Acessar o seletor de projetos

  2. Verifique se a cobrança está ativada para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

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

    Ative as APIs

  4. Anote a conta de serviço padrão do Compute Engine, porque você a associará ao fluxo de trabalho deste tutorial para fins de teste. Novos projetos que ativaram a API Compute Engine têm essa conta de serviço criada com o papel Editor básico do IAM e com o seguinte formato de e-mail:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    O número do projeto está na página de boas-vindas do console do Google Cloud.

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço e conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias e sigam o princípio do privilégio mínimo.

gcloud

  1. No Console do Google Cloud, ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. Verifique se a cobrança está ativada para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

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

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

  4. Anote a conta de serviço padrão do Compute Engine, porque você a associará ao fluxo de trabalho deste tutorial para fins de teste. Novos projetos que ativaram a API Compute Engine têm essa conta de serviço criada com o papel Editor básico do IAM e com o seguinte formato de e-mail:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    É possível recuperar o número do projeto:

    gcloud projects describe PROJECT_ID

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço e conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias e sigam o princípio do privilégio mínimo.

Criar uma pasta no Google Drive

Crie uma pasta no Google Drive. Essa pasta é usada para armazenar sua planilha. Ao configurar uma permissão para a pasta compartilhada, seu fluxo de trabalho tem permissão para gravar na planilha.

  1. Acesse drive.google.com.
  2. Clique em Novo > Nova pasta.
  3. Digite um nome para a pasta.
  4. Clique em Criar.
  5. Clique com o botão direito do mouse na nova pasta e selecione Compartilhar.

  6. Adicione o endereço de e-mail da conta de serviço padrão do Compute Engine.

    Isso concede à conta de serviço acesso à pasta. Quando você associar a conta de serviço ao seu fluxo de trabalho, ele terá acesso para editar qualquer arquivo na pasta. Saiba como compartilhar arquivos, pastas e drives.

  7. Selecione o papel Editor.

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

  9. Clique em Compartilhar.

Criar uma planilha usando o Planilhas Google

Quando você cria uma planilha no Planilhas Google, ela é salva no Google Drive. Por padrão, a planilha é salva na sua pasta raiz no Drive. Não há a opção de criar uma planilha diretamente em uma pasta especificada usando a API Google Sheets. No entanto, existem alternativas, incluindo mover a planilha para uma pasta específica após a criação, como neste exemplo. Para mais informações, consulte Trabalhar com pastas do Google Drive.

  1. Acesse sheets.google.com.

  2. Clique em Novo Mais.

    A nova planilha será criada e aberta. Cada planilha tem um valor spreadsheetId exclusivo, contendo letras, números, hifens ou sublinhados. Você pode encontrar o ID da planilha em um URL do Planilhas Google:

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

  3. Anote esse ID, ele será necessário para criar seu fluxo de trabalho.

  4. Adicione os títulos das colunas para corresponder ao exemplo a seguir:

    Exemplo de planilha para registrar aprovações

    Observe que o valor na coluna G, Aprovado?, é usado para iniciar callbacks no fluxo de trabalho.

  5. Mova a planilha para a pasta do Google Drive criada anteriormente:

    1. Na planilha, selecione Arquivo > Mover.
    2. Navegue até a pasta que você criou.
    3. Clique em Mover.

Você também pode usar o conector da API Google Sheets para criar uma planilha. Ao usar o conector, o spreadsheetId pode ser recuperado do resultado resp. Exemplo: 

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

Ampliar as Planilhas Google com o Apps Script

Com o Apps Script, você pode criar, ler e editar o Planilhas Google de maneira programática. A maioria dos scripts do Planilhas manipulam matrizes para interagir com células, linhas e colunas. Para uma introdução ao uso do Apps Script com o Planilhas Google, consulte o Guia de início rápido de funções personalizadas.

  1. Crie um projeto do Apps Script nas Planilhas Google:

    1. Abra sua planilha do Planilhas.
    2. Selecione Extensões > Apps Script.
    3. No editor de script, clique em Projeto sem título.
    4. Dê um nome ao projeto e clique em Renomear.

    Seu script agora está vinculado à sua planilha, o que dá a ele recursos especiais de alterar a interface do usuário ou responder quando a planilha for aberta.

    Um projeto de script representa um conjunto de arquivos e recursos do Apps Script. Os arquivos de código em um projeto de script têm uma extensão .gs.

  2. Use o Apps Script para escrever funções personalizadas que podem ser usadas no Planilhas Google como uma função integrada. As funções personalizadas são criadas usando JavaScript padrão. Crie uma função:

    1. Abra seu projeto do Apps Script.
    2. Clique em Editor .
    3. Um arquivo de script aparece como um arquivo de projeto chamado Code.gs. Para editar o arquivo, selecione-o.

    4. Substitua qualquer código no editor de script pelo seguinte código, que lê os dados na sua planilha e os transmite como entrada para a 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 Salvar .

  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 atendidas, como quando uma planilha é aberta ou editada. Crie um gatilho:

    1. Abra seu projeto do Apps Script.
    2. Clique em Gatilhos .
    3. Clique em Adicionar gatilho.
    4. Na caixa de diálogo Adicionar gatilho para YOUR_PROJECT_NAME, configure o acionador:
      1. Na lista Escolher qual função executar, selecione handleEdit.
      2. Na lista Escolher qual implantação deve ser executada, selecione Cabeçalho.
      3. Na lista Selecionar origem do evento, selecione Da planilha.
      4. Na lista Selecionar tipo de evento, escolha Na edição.
      5. Na lista Configurações de notificação de falha, selecione Receber notificação diariamente.
    5. Clique em Salvar.

    6. Se você receber uma solicitação para escolher uma Conta do Google, selecione a opção apropriada e clique em Permitir.

      Isso permite que seu projeto do Apps Script veja, edite, crie e exclua suas planilhas do Planilhas Google, além de se conectar a um serviço externo.

  4. Um arquivo de manifesto de projeto do Apps Script é um arquivo JSON que especifica as informações básicas do projeto necessárias para o Apps Script executar um script. O editor do Apps Script oculta arquivos de manifesto por padrão para proteger as configurações do projeto. Edite o arquivo de manifesto:

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

    6. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos de autorização usados pelo projeto, adicione uma matriz com os escopos que você quer aceitar. 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"
  ]
}

      Define os escopos explícitos como:

      • Conectar a um serviço externo
      • Consultar, editar, configurar e excluir seus dados do Google Cloud, além de conferir o endereço de e-mail da sua Conta do Google
      • Ver, editar, criar e excluir todas as suas planilhas do Planilhas Google

    7. Clique em Salvar .

Implantar um fluxo de trabalho que grave em uma planilha e use callbacks

Implante um fluxo de trabalho que é executado, pausado e retomado quando um callback é aprovado por meio de uma planilha. O fluxo de trabalho grava em uma planilha do Planilhas usando o conector da API Google Sheets.

Console

  1. No console do Google Cloud, acesse a página Fluxos de trabalho:

    Acessar fluxos de trabalho

  2. Clique em Criar.

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

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

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

  6. Clique em Próxima.

  7. No editor de fluxo de trabalho, insira a seguinte definição para 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. Substitua o valor do marcador de posição sheetId pelo spreadsheetId.

  9. Selecione Implantar.

gcloud

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

    touch workflows-awaits-callback-sheets.yaml

  2. Em um editor de texto, copie o fluxo de trabalho a seguir para o arquivo 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. Substitua o valor do marcador de posição sheetId pelo spreadsheetId.

  4. Implante o fluxo de trabalho digitando 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 número do projeto do Google Cloud. É possível recuperar o número do projeto:

    gcloud projects describe PROJECT_ID

Testar o fluxo de ponta a ponta

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

Console

  1. No console do Google Cloud, acesse a página Fluxos de trabalho:

    Acessar fluxos de trabalho

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

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

  4. Clique em Executar novamente.

    O fluxo de trabalho é iniciado, e o estado de execução deve ser Running. Os registros também indicam que o fluxo de trabalho está pausado e aguardando:

    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 gravou os detalhes do callback em uma linha da planilha.

    Por exemplo, você verá o ID de execução do fluxo de trabalho na coluna ID de execução, um endpoint de callback na coluna URL de callback e FALSO na coluna Aprovado?.

  6. Na planilha, altere FALSE para FALSE.

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

gcloud

  1. Abra um terminal.

  2. Execute o fluxo de trabalho:

      gcloud workflows run workflows-awaits-callback-sheets

    O fluxo de trabalho é iniciado, e a saída indica que ele está pausado e aguardando:

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

  3. Verifique se o fluxo de trabalho gravou os detalhes do callback em uma linha da planilha.

    Por exemplo, você verá o ID de execução do fluxo de trabalho na coluna ID de execução, um endpoint de callback na coluna URL de callback e FALSO na coluna Aprovado?.

  4. Na planilha, altere FALSE para FALSE.

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

Limpar

Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.

Exclua o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

  1. No Console do Google Cloud, acesse a página Gerenciar recursos.

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir recursos criados neste tutorial

  1. Excluir arquivos no Google Drive.
  2. Excluir um fluxo de trabalho.

A seguir