コールバックと Google スプレッドシートを使用してワークフローを一時停止、再開する

Google スプレッドシートは、リアルタイムでの共同編集が可能な、データの可視化、処理、通信のためのツールを提供するクラウドベースのスプレッドシートソリューションです。

このチュートリアルでは、コールバックエンドポイント（Webhook）を作成して、Google スプレッドシートにコールバック URL を保存し、実行を一時停止して、スプレッドシートの人間による承認を待機し、ワークフローを再起動するワークフローを作成してデプロイする方法を説明します。詳しくは、コールバックの使用方法をご覧ください。

目標

このチュートリアルの内容は次のとおりです。

Google ドライブに新しいフォルダを作成します。このフォルダは、スプレッドシートの保存に使用されます。これにより、ワークフローによるスプレッドシートへの書き込みが可能になります。
Google スプレッドシートを作成して承認を取得し、ワークフローに対するコールバックを開始します。
クラウドベースの JavaScript プラットフォームである Google Apps Script を使用して、Google Workspace プロダクトをプログラムで作成、読み取り、編集し、一時停止したワークフローの再開をスプレッドシートの更新を通してリクエストが承認されるたびにワークフローをトリガーします。
Google Sheets API コネクタを呼び出してデータをスプレッドシートに追加するワークフローを作成してデプロイします。ワークフローが実行され、一時停止し、スプレッドシートでコールバックが承認されると再開します。Workflows コネクタの詳細を確認する。
プロセス全体をテストして、ワークフローが想定どおりに進行することを確認します。

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このチュートリアルでは、Google Workspace も使用します。Google の無料の一般ユーザー向けアプリに含まれていないビジネスレベルのサービスは、課金対象になります。

始める前に

Google Cloud コンソールで次のコマンドを実行するか、ターミナルまたは Cloud Shell で Google Cloud CLI を使用できます。

組織で定義されたセキュリティの制約により、次の手順が完了できない場合があります。トラブルシューティング情報については、制約のある Google Cloud 環境でアプリケーションを開発するをご覧ください。

コンソール

Google Cloud コンソールのプロジェクトセレクタページで、Google Cloud プロジェクトを選択または作成します。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。
プロジェクトセレクタに移動
Google Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
Compute Engine、Google スプレッドシート、Workflows API を有効にします。

API を有効にする
Compute Engine API が有効になっている新しいプロジェクトには、IAM 基本編集者ロールや、以下のメール形式を持つ Compute Engine のデフォルトのサービスアカウントが作成されます。
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
プロジェクト番号は、Google Cloud コンソールの [ようこそ] ページで確認できます。

このサービスアカウントは、テスト目的でこのチュートリアルのワークフローに関連付けるため、メモしておきます。

重要: 本番環境では、新しいサービスアカウントを作成し、必要最小限のアクセス許可を含み、最小権限の原則に従う 1 つ以上の IAM ロールを付与することを強くお勧めします。

gcloud

Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。

Cloud Shell をアクティブにする

Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
Google Cloud プロジェクトの課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

Compute Engine、Google スプレッドシート、Workflows API を有効にします。

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

Compute Engine API が有効になっている新しいプロジェクトには、IAM 基本編集者ロールや、以下のメール形式を持つ Compute Engine のデフォルトのサービスアカウントが作成されます。
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
プロジェクト番号を取得します。
```
gcloud projects describe PROJECT_ID
```
このサービスアカウントは、テスト目的でこのチュートリアルのワークフローに関連付けるため、メモしておきます。

重要: 本番環境では、新しいサービスアカウントを作成し、必要最小限のアクセス許可を含み、最小権限の原則に従う 1 つ以上の IAM ロールを付与することを強くお勧めします。

Google ドライブで新しいフォルダを作成する

Google ドライブに新しいフォルダを作成します。このフォルダはスプレッドシートの保存に使用されます。共有フォルダの権限を設定することで、ワークフローによるスプレッドシートへの書き込みができるようになります。

drive.google.com にアクセスする。
[新規] > [新しいフォルダ] をクリックします。
フォルダ名を入力します。
[作成] をクリックします。
新しいフォルダを右クリックし、[共有] を選択します。
Compute Engine のデフォルトサービスアカウントのメールアドレスを追加します。

これにより、サービスアカウントにフォルダへのアクセスが許可されます。サービスアカウントをワークフローに関連付けると、そのワークフローにはフォルダ内の任意のファイルに対する編集権限が付与されます。ファイル、フォルダ、ドライブの共有の詳細。
編集者のロールを選択します。
[通知] チェックボックスをオフにします。
[共有] をクリックします。

Google スプレッドシートを使用してスプレッドシートを作成する

Google スプレッドシートを使用して作成したスプレッドシートは、Google ドライブに保存されます。デフォルトでは、スプレッドシートはドライブのルートフォルダに保存されます。Google Sheets API を使用して、指定したフォルダ内に直接スプレッドシートを作成するオプションはありません。ただし、この例で示すように、スプレッドシートを作成した後に特定のフォルダに移動するなどの方法もあります。詳細については、Google ドライブフォルダを操作するをご覧ください。

sheets.google.com にアクセスします。
[新規] をクリックします。

新しいスプレッドシートが作成され、開きます。各スプレッドシートには一意の spreadsheetId 値があり、これには文字、数字、ハイフン、アンダースコアが含まれます。スプレッドシート ID は Google スプレッドシートの URL で確認できます。

https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0
この ID はワークフローの作成時に必要になるため、メモしておいてください。
次の例と一致するように列見出しを追加します。

列 [G]、[Approved?] の値は、ワークフローでコールバックを開始するために使用されます。
前に作成した Google ドライブフォルダにスプレッドシートを移動します。
1. スプレッドシートで、[ファイル] > [移動] を選択します。
2. 作成したフォルダに移動します。
3. [移動] をクリックします。

また、Google Sheets API コネクタを使用してスプレッドシートを作成することもできます。コネクタを使用する場合、spreadsheetId は resp の結果から取得できます。例:

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

Apps Script を使用して Google スプレッドシートを拡張する

Apps Script を使用すると、Google スプレッドシートの作成、読み取り、編集をプログラムで行うことができます。Google スプレッドシート用に設計されたほとんどのスクリプトでは、配列を操作してスプレッドシート内のセル、行、列を操作することができます。Google スプレッドシートで Apps Script を使用する方法については、カスタム関数のクイックスタートをご覧ください。

Google スプレッドシートから Apps Script プロジェクトを作成する:
1. Google スプレッドシートを開きます。
2. [拡張機能] > [Apps Script] を選択します。
3. スクリプトエディタで、[無題のプロジェクト] をクリックします。
4. プロジェクトに名前を付けて、[名前を変更する] をクリックします。
これで、スクリプトがスプレッドシートにバインドされます。これにより、スクリプトでユーザーインターフェースを変更したり、スプレッドシートを開いたときに応答したりできます。

スクリプトプロジェクトは、Apps Script のファイルとリソースのコレクションを表します。スクリプトプロジェクトのコードファイルの拡張子は .gs です。

Apps Script を使用すると、組み込み関数のように Google スプレッドシートで使用できるカスタム関数を作成できます。カスタム関数は、標準の JavaScript を使用して作成されます。関数を作成する

Apps Script プロジェクトを開きます。
[編集者] をクリックします。
スクリプトファイルは、Code.gs という名前のプロジェクトファイルとして表示されます。ファイルを編集するには、そのファイルを選択します。

スクリプトエディタのコードを次のコードに置き換えます。このコードは、スプレッドシート内のデータを読み取り、ワークフロー実行への入力として渡します。

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);
}

[保存] をクリックします。

Apps Script のインストール可能なトリガーを使用すると、スプレッドシートを開いたり編集したりしたときなど、特定の条件が満たされたときに、スクリプトプロジェクトが指定された関数を実行できるようになります。トリガーを作成する
1. Apps Script プロジェクトを開きます。
2. [トリガー] をクリックします。
3. [トリガーを追加] をクリックします。
4. [YOUR_PROJECT_NAME のトリガーを追加] ダイアログで、トリガーを構成します。
  1. [実行する関数を選択] リストで、[handleEdit] を選択します。
  2. [実行するデプロイを選択] リストで、[Head] を選択します。
  3. [イベントソースを選択] リストで、[スプレッドシートから] を選択します。
  4. [イベントタイプを選択] リストで、[編集時] を選択します。
  5. [障害通知設定] リストで、[毎日通知] を選択します。
5. [保存] をクリックします。
6. Google アカウントを選択するように求められたら、適切なアカウントを選択して [許可] をクリックします。
  
  これにより、Apps Script プロジェクトが Google スプレッドシートのシートを表示、編集、作成、削除し、外部サービスに接続できるようになります。
Apps Script プロジェクトのマニフェストファイルは、Apps Script がスクリプトを正常に実行するために必要な基本的なプロジェクト情報を指定する JSON ファイルです。Apps Script エディタでは、Apps Script プロジェクト設定を保護するため、デフォルトでマニフェストファイルが非表示になります。マニフェストファイルを編集します。
1. Apps Script プロジェクトを開きます。
2. [プロジェクトの設定] をクリックします。
3. [「appsscript.json」マニフェストファイルをエディタで表示する] チェックボックスをオンにします。
4. [編集者] をクリックします。
5. マニフェストファイルは、appsscript.json という名前のプロジェクトファイルとして表示されます。ファイルを編集するには、そのファイルを選択します。
6. oauthScopes フィールドは、文字列の配列を指定します。プロジェクトで使用する認証スコープを設定するには、サポートするスコープを含む配列を追加します。例:
```
{
  "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"
  ]
}
```
  これにより、明示的なスコープが次のように設定されます。
  - 外部サービスへの接続
  - Google Cloud のデータの表示、編集、設定、削除、および Google アカウントのメールアドレスの表示
  - Google スプレッドシートのすべてのスプレッドシートの参照、編集、作成、削除
7. [保存] をクリックします。
注: プロジェクトの設定を保護するため、編集が終わったらエディタで「appsscript.json」マニフェストファイルを表示するチェックボックスを消去し、マニフェストを非表示にします。

スプレッドシートに書き込み、コールバックを使用するワークフローをデプロイする

実行され、一時停止し、スプレッドシートでコールバックが承認されると再開するワークフローをデプロイします。ワークフローは、Google Sheets API コネクタを使用してスプレッドシートに書き込みます。

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[ 作成] をクリックします。
新しいフィールドの名前を入力します: workflows-awaits-callback-sheets。
[リージョン] リストで [us-central1 (Iowa)] を選択します。
[サービスアカウント] で、Compute Engine のデフォルトのサービスアカウント（PROJECT_NUMBER-compute@developer.gserviceaccount.com）を選択します。
[Next（次へ）] をクリックします。

ワークフローエディタで、次のワークフローの定義を入力します。

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}

プレースホルダ sheetId 値は spreadsheetId に置き換えてください。
[デプロイ] をクリックします。

gcloud

ワークフローのソースコードファイルを作成します。
```
touch workflows-awaits-callback-sheets.yaml
```

テキストエディタで、次のワークフローをソースコードファイルにコピーします。

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}

プレースホルダ sheetId 値は spreadsheetId に置き換えてください。

次のコマンドを入力してワークフローをデプロイします。

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

PROJECT_NUMBER は、実際の Google Cloud プロジェクトの番号に置き換えます。プロジェクト番号を取得します。

gcloud projects describe PROJECT_ID

エンドツーエンドのフローをテストする

ワークフローを実行して、エンドツーエンドのフローをテストします。ワークフローを実行すると、そのワークフローに関連付けられた現在のワークフロー定義が実行されます。

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[Workflows] ページで、[workflows-awaits-callback-sheets] ワークフローを選択して詳細ページに移動します。
[ワークフローの詳細] ページで [ 実行] を選択します。
もう一度 [Execute] をクリックします。

ワークフローが開始され、実行状態が [実行中] になります。ログには、ワークフローが一時停止して待機していることも示されます。
```
Execute steps here before waiting for callback from sheets
...
Started waiting for callback from sheet 1JlNFFnqs760M_KDqeeeDc_qtrABZDxoalyCmRE39dpM
```
ワークフローによって、スプレッドシートの行にコールバックの詳細が書き込まれていることを確認します。

たとえば、ワークフローの実行 ID は実行 ID 列、コールバックエンドポイントはコールバック URL 列、FALSE は承認済みですか？列に表示されます。
スプレッドシートで、FALSE を TRUE に変更します。

1～2 分後に実行が再開され、実行ステータスが [Succeeded] になり完了します。

gcloud

ターミナルを開きます。
ワークフローを実行します。
```
  gcloud workflows run workflows-awaits-callback-sheets
```
ワークフローが開始され、ワークフローが一時停止して待機していることが出力に表示されます。
```
  Waiting for execution [a8361789-90e0-467f-8bd7-ea1c81977820] to complete...working.
```
ワークフローによって、スプレッドシートの行にコールバックの詳細が書き込まれていることを確認します。

たとえば、ワークフローの実行 ID は実行 ID 列、コールバックエンドポイントはコールバック URL 列、FALSE は承認済みですか？列に表示されます。
スプレッドシートで、FALSE を TRUE に変更します。

1～2 分後に実行が再開され、実行ステータスが SUCCEEDED になります。

クリーンアップ

このチュートリアル用に新規プロジェクトを作成した場合は、そのプロジェクトを削除します。既存のプロジェクトを使用し、このチュートリアルで変更を加えずに残す場合は、チュートリアル用に作成したリソースを削除します。

プロジェクトの削除

課金をなくす最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

コールバックと Google スプレッドシートを使用してワークフローを一時停止、再開する

目標

費用

始める前に

コンソール

gcloud

Google ドライブで新しいフォルダを作成する

Google スプレッドシートを使用してスプレッドシートを作成する

Apps Script を使用して Google スプレッドシートを拡張する

スプレッドシートに書き込み、コールバックを使用するワークフローをデプロイする

Console

gcloud

エンドツーエンドのフローをテストする

Console

gcloud

クリーンアップ

プロジェクトの削除

このチュートリアルで作成したリソースを削除する

次のステップ