Workflows

解決する課題

複数のサービスを「呼んで、結果を見て、次を呼ぶ」という連携処理を、アプリ側のコードや常駐サーバーで書くと、状態管理・リトライ・エラー処理が複雑になりがちです。Workflows はこの一連の流れを宣言的な手順書として外に切り出し、実行状態の管理をマネージドに任せます。

• 複数の API 呼び出しを 順番・分岐・条件に従ってつなぎたいが、状態管理を自前で書きたくない
• 一時的な失敗に対する リトライやバックオフを、各サービスごとに実装せず共通化したい
• 連携を 常駐サーバーなしのサーバーレスで動かし、待機中はコストを払いたくない
• 処理の流れを 可視化し、どのステップで失敗したかを追跡したい
• 長時間かかる処理の 完了待ち（ポーリングや一定時間の待機） を低コストに実現したい

主要概念と用語

• ワークフロー（Workflow）: 一連の手順を定義したリソース。YAML または JSON で記述する。デプロイすると不変のリビジョンとして保存される
• ステップ（Step）: 手順を構成する最小単位。API 呼び出し、代入、条件分岐、待機などを表す
• 実行（Execution）: デプロイ済みワークフローを起動して走らせた 1 回分のインスタンス。実行ごとに ID と状態を持つ
• コネクタ（Connector）: Google Cloud サービス（Pub/Sub、Cloud Storage、BigQuery など）を呼び出すための組み込み部品。リトライや長時間処理の完了待ちを内包する
• 式（Expression）と変数: 二重波かっこの記法でデータを参照・加工し、ステップ間で受け渡す
• HTTP リクエストステップ: 任意の外部 API や Cloud Run / Cloud Run functions を HTTP で呼び出すステップ。認証情報の付与にも対応する
• コールバック（Callback）: 実行を一時停止し、外部からのコールバック URL への通知を待ってから再開する仕組み。人手の承認や非同期完了の待機に使う
• サブワークフロー: 手順を関数のように切り出して再利用する単位

仕様・制限・クォータ

• 記述言語は YAML / JSON ベースの宣言的構文。分岐（switch）、ループ（for）、並列（parallel）、リトライ、例外処理（try/except）、待機（sleep）などを表現できる
• 状態はサービス側が保持するため、アプリ側でジョブの進行状況を管理する必要がない
• 1 実行の 最大実行時間は長時間（年単位）に対応し、待機やコールバックを挟む長期プロセスも組める。一方で同期 HTTP 呼び出し 1 回あたりのタイムアウトには上限がある
• 1 実行で扱える ステップ数・変数のメモリサイズ・並列分岐の同時実行数などに上限（クォータ）があり、これらは引き上げ申請が可能なものもある
• ワークフローは リージョン単位のリソースとして作成・実行される
• 具体的な上限値やタイムアウト秒数、クォータの数値は変動するため、最新は公式ドキュメントで確認すること

内部の仕組み

ワークフローを起動すると、Workflows のマネージドエンジンが手順書を上から評価し、各ステップ（API 呼び出し・代入・分岐など）を順に実行します。実行中の 変数の値・現在位置・リトライ状態などはサービス側に永続化されるため、待機やコールバックで止まっている間も状態が失われません。

• HTTP リクエストステップや各種コネクタを通じて外部サービスを呼び出し、レスポンスを変数に取り込んで次のステップへ渡す
• sleep ステップで待機している間は実質的に処理リソースを消費せず、長時間のポーリングや遅延を低コストに実現できる
• 失敗時は try/except とリトライポリシーでハンドリングでき、指数バックオフなどの再試行戦略を宣言的に指定する
• コネクタは内部で対象サービスの 長時間オペレーションの完了待ち（ポーリング） を肩代わりするため、利用者は完了結果だけを受け取れる

設計パターン / ベストプラクティス

• サービスオーケストレーション: 複数のマイクロサービスや API を順序立てて呼び出し、結果を集約する中心役として使う
• 疎結合との使い分け: イベント発生をきっかけに非同期で広く配信したいなら Pub/Sub や Eventarc、明確な手順と状態を持つ一連のフローなら Workflows、と役割を分ける（オーケストレーション対コレオグラフィー）
• 冪等性の確保: リトライにより同じステップが再実行されうるため、副作用を伴う呼び出しは冪等に設計する
• エラー処理の集中化: 各ステップのリトライ/例外処理をワークフロー側にまとめ、個々のサービス実装をシンプルに保つ
• 長時間処理はコールバックで待つ: 人手の承認や外部の非同期完了は、ポーリングのループより コールバックで待機させるとシンプルで低コスト
• トリガーの組み合わせ: 定期実行は Cloud Scheduler、イベント起動は Eventarc から Workflows を呼び出す形でつなぐ

運用・監視

• 各実行は 状態（成功・失敗・実行中・キャンセル）と入出力、ステップごとの経過を保持し、コンソールや CLI で追跡できる
• Cloud Logging に実行ログが出力され、どのステップで何が起きたかを確認できる。ステップログの出力レベルは調整可能
• Cloud Monitoring で実行回数・失敗率・所要時間などのメトリクスを監視し、アラートを設定する
• 失敗した実行は入力と発生箇所を確認して原因を切り分ける。リトライ設定が意図通りか、認証や権限エラーでないかを点検する
• ワークフローは リビジョン管理され、デプロイ済みの定義は不変なので、変更履歴の追跡やロールバックがしやすい

コスト

Workflows は実行した ステップ数に対する従量課金が基本で、待機（sleep）中はステップを消費しません。常駐サーバーが不要なため、起動していない間の固定費が発生しないのが特徴です。

セキュリティ

• 各ワークフローには サービスアカウントを割り当て、そのアカウントの権限でステップが実行される。最小権限の IAM ロールのみを付与する
• HTTP リクエストステップでは、Google Cloud の宛先に対して OAuth トークンや OIDC トークンを自動付与し、認証付きで安全に呼び出せる
• ワークフローの起動には呼び出し側に適切なロール（例: roles/workflows.invoker）が必要で、編集や管理は別のロールで分離する
• 機密情報をワークフロー定義に直接埋め込まず、Secret Manager 等から取得する設計にする
• 保存データは暗号化され、要件に応じて CMEK（顧客管理鍵） での保護にも対応する

Well-Architected の観点

• 運用上の優秀性（operational excellence）: 連携手順を宣言的な手順書として外部化し、実行状態・ステップ履歴・ログを可視化することで、障害時の原因特定（MTTR 短縮）と変更管理が容易になる。リビジョン管理で変更を追跡できる
• 信頼性（reliability）: リトライ・指数バックオフ・例外処理を宣言的に組み込み、一時障害に強い連携を実現する。状態がマネージドに永続化されるため、長時間プロセスでも進行状況を失わない。冪等な宛先設計と組み合わせて再実行に耐えるようにする

試験で問われるポイント

関連サービス・比較

ハンズオン / CLI例

# 1) ワークフロー定義ファイル(workflow.yaml)を用意する想定
#    例: 公開 API を呼び、結果を返すだけの最小ワークフロー
#
#    main:
#      steps:
#        - callApi:
#            call: http.get
#            args:
#              url: https://example.com/api/status
#            result: apiResult
#        - returnResult:
#            return: ${apiResult.body}

# 2) ワークフローをデプロイ（専用サービスアカウントを指定）
gcloud workflows deploy my-workflow \
  --location=asia-northeast1 \
  --source=workflow.yaml \
  --service-account=workflow-sa@PROJECT_ID.iam.gserviceaccount.com

# 3) ワークフローを実行（入力データを渡す場合は --data を使用）
gcloud workflows run my-workflow \
  --location=asia-northeast1 \
  --data='{"target":"status"}'

# 4) 実行状況・履歴の確認
gcloud workflows executions list my-workflow --location=asia-northeast1
gcloud workflows executions describe EXECUTION_ID \
  --workflow=my-workflow --location=asia-northeast1