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


O Planilhas Google é uma solução de gerenciamento de planilhas que oferece suporte à colaboração em tempo real e fornece ferramentas para visualizar, processar e comunicar dados.

Este tutorial demonstra 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 das pessoas no Planilhas 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 planilha e permite que o fluxo de trabalho grave na planilha.
  2. Crie uma planilha do Planilhas Google para receber 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 para acionar a retomada de uma campanha fluxo de trabalho sempre que uma solicitação é aprovada por meio de uma atualização na 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. Serviços de nível empresarial nã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 seu projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

  3. Ative as APIs do Compute Engine, APIs Workflows.

    Ative as APIs

  4. Anote os valores Conta de serviço padrão do Compute Engine porque você vai associá-lo ao fluxo de trabalho neste tutorial para testar propósitos. Novos projetos que ativaram a API Compute Engine essa conta de serviço é criada com o IAM básico Editor e com o seguinte formato de e-mail:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    O número do projeto está na página Olá! do console do Google Cloud.

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço e concedendo a ele um ou mais papéis do IAM que contêm permissões mínimas necessárias e seguir 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 seu projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

  3. Ative as APIs do Compute Engine, APIs Workflows.

    gcloud services enable \
        compute.googleapis.com \
        sheets.googleapis.com \
        workflows.googleapis.com
    
  4. Anote os valores Conta de serviço padrão do Compute Engine porque você vai associá-lo ao fluxo de trabalho neste tutorial para testar propósitos. Novos projetos que ativaram a API Compute Engine essa conta de serviço é criada com o IAM básico Editor 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 concedendo a ele um ou mais papéis do IAM que contêm permissões mínimas necessárias e seguir o princípio do privilégio mínimo.

Criar uma pasta no Google Drive

Crie uma pasta no Google Drive. Ela é usada para armazenar 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. Adicionar o endereço de e-mail do serviço padrão do Compute Engine do Compute Engine.

    Isso concede à conta de serviço acesso à pasta. Ao associar a conta de serviço com seu fluxo de trabalho, o fluxo de trabalho terá edições acesso a qualquer arquivo na pasta. Saiba mais sobre como compartilhar arquivos, pastas e unidade de disco rígido.

  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 em Google Drive Por padrão, a planilha é salva na sua pasta raiz em Google Drive. Não há a opção de criar uma planilha diretamente em uma pasta específica usando a API Google Sheets. No entanto, não há são alternativas, incluindo mover a planilha para uma pasta específica após durante 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. Toda planilha tem um valor Valor spreadsheetId, que contenham letras, números, hifens ou sublinhados. Encontre a ID de 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

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

  5. Mova a planilha para a pasta do Google Drive que você criou. 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. Observe que, 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

O Apps Script permite criar, ler e editar programaticamente Planilhas Google. A maioria dos scripts criados para o Planilhas manipular para interagir com células, linhas e colunas em uma planilha. Para um sobre como usar o 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 será vinculado à planilha. que dá ao script habilidades especiais para alterar a interface de usuário ou responder quando a planilha for aberta.

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

  2. Você pode usar o Apps Script para escrever funções personalizadas que pode usar no Planilhas Google como uma função integrada. As funções personalizadas são 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: selecioná-la.
    4. Substitua qualquer código no editor de script pelo seguinte código, que mostra os dados da planilha e os transmite como entrada para um fluxo de trabalho execução:

      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. Apps Script acionadores instaláveis que um projeto de script execute uma função especificada quando determinadas condições são atendidos, 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 gatilho:
      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 o conta e clique em Permitir.

      Isso permite que seu projeto do Apps Script visualize, edite criar e excluir suas planilhas do Planilhas Google; e para se conectar 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 que O Apps Script precisa executar um script. Observe que o O editor do Apps Script oculta arquivos de manifesto por padrão para proteger o Apps Script 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 e selecioná-lo.
    6. O campo oauthScopes especifica uma matriz de strings. Para definir escopos de autorização usado pelo projeto, adicione uma matriz com os escopos que serão compatíveis. 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 e 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 é aprovados por meio de uma planilha. O fluxo de trabalho grava em um arquivo do Planilhas planilha usando o conector da API Google Sheets.

Console

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

    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 o padrão do Compute Engine conta de serviço (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  6. Clique em Next.

  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 sheetId pelo seu spreadsheetId.

  9. Clique em 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 sheetId pelo seu 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 definição de fluxo de trabalho atual associada ao fluxo de trabalho.

Console

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

    Acessar fluxos de trabalho

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

  3. Na página Detalhes do fluxo de trabalho, clique em Execução.

  4. Clique em Executar novamente.

    O fluxo de trabalho é iniciado, e o estado de execução deve ser Running. O 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 da chamada de retorno em uma linha no sua planilha.

    Por exemplo, você encontra o ID de execução do fluxo de trabalho na Coluna Execution ID, um endpoint de callback no Callback URL e FALSO na coluna Aprovado?.

  6. Na planilha, altere FALSO para VERDADEIRO.

    Depois de 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 deve indicar 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 da chamada de retorno em uma linha no sua planilha.

    Por exemplo, você encontra o ID de execução do fluxo de trabalho na Coluna Execution ID, um endpoint de callback no Callback URL e FALSO na coluna Aprovado?.

  4. Na planilha, altere FALSO para VERDADEIRO.

    Depois de 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