Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

問題のトラブルシューティング

このページでは、Workflows の使用時に発生する可能性のある問題を解決する方法について説明します。

詳細については、Workflows のモニタリングとデバッグをご覧ください。

デプロイエラー

ワークフローがデプロイされると、Workflows により、ソースコードにエラーがなく、言語構文と一致することが確認されます。 Workflows によりエラーが検出された場合は、エラーが返されます。最も一般的な種類のデプロイエラーは、次のとおりです。

未定義の変数、ステップ、サブワークフローの参照
不適切な構文
- 不適切なインデント
- {、}、"、-、: の欠落、または無関係なものがある

たとえば、次のソースコードはデプロイエラーをスローします。これは、return 文で未定義の変数 varC が参照されるためです。

- step1:
    assign:
    - varA: "Hello"
    - varB: "World"
- step2:
    return: ${varC + varB}

この間違ったソースコードは、次の Google Cloud コンソールと gcloud CLI の例で使用されています。

コンソール

デプロイエラーが発生した場合、Workflows の [ワークフローの編集] ページのバナーにエラーメッセージが表示されます。エラーメッセージは、ソースコードの問題を報告します。可能であれば、エラーの原因を指定します。

Could not deploy workflow: failed to build: error in step step2: error
evaluating return value: symbol 'varC' is neither a variable nor a
sub-workflow name (Code: 3)

gcloud

gcloud workflows deploy コマンドを実行すると、デプロイが失敗した場合、Workflows はコマンドラインにエラーメッセージを返します。エラーメッセージは、可能であればエラーの原因を指定して、ソースコードの問題を報告します。

ERROR: (gcloud.workflows.deploy) [INVALID_ARGUMENT] failed to build:
error in step step2: error evaluating return value: symbol 'varC' is neither
a variable nor a sub-workflow name

この問題を解決するには、ワークフローのソースコードを編集します。この場合は、varC ではなく varA を参照してください。

HTTP `403` サービスアカウントの権限に関するエラー

ワークフローの実行時、またはワークフローのデプロイや更新時に、HTTP エラー 403（PERMISSION_DENIED）が発生することがあります。

ワークフローの実行中に権限が拒否されました

ワークフローのサービスアカウントにターゲットリソースへのアクセス権がないため、HTTP サーバーがエラーコード 403 で応答すると、ワークフローの実行が失敗します。次に例を示します。

SERVICE_ACCOUNT does not have storage.objects.create access to the Google Cloud
Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist).

すべてのワークフローは、ワークフローの作成時に Identity and Access Management（IAM）サービスアカウントに関連付けられます。この問題を解決するには、ワークフローが使用するリソースにアクセスするために必要な最小限の権限を含む 1 つ以上の IAM ロールをワークフローのサービスアカウントに付与します。たとえば、ワークフローによって Cloud Logging にログが送信されるようにするには、ワークフローを実行するサービスアカウントに logging.logEntries.create 権限を含むロールが付与されていることを確認します。詳細については、 Google Cloud リソースにアクセスする権限をワークフローに付与するをご覧ください。

ワークフローのデプロイまたは更新時に権限が拒否される

ワークフローをデプロイまたは更新するときに、ワークフローのサービスアカウントとして機能する権限がないと、リクエストが HTTP 403（PERMISSION_DENIED）エラーで失敗することがあります。次に例を示します。

Permission 'iam.serviceaccounts.actAs' denied on service
account PROJECT_NUMBER-compute@ (or it may not exist).

または

permission iam.serviceAccounts.ActAs is required on the workflow's new/current
service account to set it or the workflow source contents

この問題を解決するには、ワークフローをデプロイまたは更新するプリンシパルに、iam.serviceAccounts.actAs 権限を含むロール（サービスアカウントユーザー（roles/iam.serviceAccountUser）など）を付与します。オペレーションに応じて、次のサービスアカウントにこのロールを付与します。

ワークフローのソースコードのみを更新する（サービスアカウントを更新しない）: ワークフローに関連付けられている既存のサービスアカウントにロールを付与します。
ワークフローの作成、サービスアカウントの更新、ソースコードとサービスアカウントの両方の更新: ワークフローに関連付ける新しいサービスアカウントにロールを付与します。

詳細については、サービスアカウント権限をご覧ください。

HTTP `404 No such object` エラーまたは `Not found` エラー

Cloud Storage コネクタを使用している場合、HTTP サーバーが 404 エラーコードで応答すると、ワークフローの実行が失敗します。次に例を示します。

HTTP server responded with error code 404
in step "read_input_file", routine "main", line: 13
{
  "body": "Not Found",
  "code": 404,
  ...
}

オブジェクト名は、パスセーフになるように URL エンコードする必要があります。url_encode 関数と url_encode_plus 関数を使用すると、リクエスト URL のオブジェクト名またはクエリ文字列に該当する文字が含まれている場合に、それらの文字をエンコードできます。次に例を示します。

- init:
    assign:
        - source_bucket: "my-bucket"
        - file_name: "my-folder/my-file.json"
- list_objects:
    call: googleapis.storage.v1.objects.get
    args:
        bucket: ${source_bucket}
        object: ${text.url_encode(file_name)}
        alt: media
    result: r
- returnStep:
    return: ${r}

オブジェクト名を URL エンコードせず、ストレージバケットにフォルダがある場合、リクエストは失敗します。詳細については、URL パス部分のエンコードと Cloud Storage の命名に関する考慮事項をご覧ください。

HTTP `429 Too many requests` エラー

同時に実行できるアクティブなワークフロー実行には最大数があります。この割り当てが使い果たされ、実行バックログが無効になっている場合、またはバックログ実行の割り当てに達した場合、新しい実行は HTTP 429 Too many requests ステータスコードで失敗します。

実行バックログを使用すると、同時実行割り当てに達したとき、ワークフロー実行をキューに入れることができます。デフォルトでは、実行バックログは、次の例外を除いて、すべてのリクエスト（Cloud Tasks によってトリガーされたリクエストを含む）に対して有効になっています。

ワークフローで executions.run コネクタまたは executions.create コネクタを使用して実行を作成する場合、実行バックログはデフォルトで無効になります。実行の disableConcurrencyQuotaOverflowBuffering フィールドを明示的に false に設定することで構成できます。
Pub/Sub によってトリガーされる実行の場合、実行バックログは無効になり、構成できません。

詳細については、実行バックログを管理するをご覧ください。

定義したレートで Cloud Tasks キューが子ワークフローを実行できるようにして、実行速度を向上させることもできます。その場合は、明示的に実行バックログを無効にすることをおすすめします。

プロジェクト間のサービスアカウントの権限に関するエラー

プロジェクト間のサービスアカウントを使用してワークフローをデプロイするときに PERMISSION_DENIED エラーが発生した場合は、プロジェクトに iam.disableCrossProjectServiceAccountUsage ブール型制約が適用されていないことと、サービスアカウントが正しく設定されていることを確認してください。詳細については、プロジェクト間のサービスアカウントを使用してワークフローをデプロイするをご覧ください。

リソース名は RFC 1123 に準拠している必要がある

HTTP サーバーがエラーコード 400 で応答した場合、ワークフローの実行が失敗しています。次に例を示します。

"description": "must conform to RFC 1123: only lowercase, digits, hyphens,
and periods are allowed, must begin and end with letter or digit, and less
than 64 characters."

この問題を解決するには、リソース名が RFC 1123 で定義された DNS ラベル標準に従っていることと、変数を割り当てるときに文字列と式が正しく連結されていることを確認します。

たとえば、- string: hello-${world} のように変数を割り当てることはできません。代わりに、次のようにします。

YAML

  - assign_vars:
      assign:
          - string: "hello"
          - string: ${string+" "+"world"}

JSON

  [
    {
      "assign_vars": {
        "assign": [
          {
            "string": "hello"
          },
          {
            "string": "${string+" "+"world"}"
          },
        ]
      }
    }
  ]

コロンを含む式

YAML でコロンを含む式を使用すると、コロンがマッピングの定義と解釈されたときに予期しない動作が発生する可能性があります。ワークフローをデプロイして実行することはできますが、想定どおりの出力は得られせん。

Google Cloud コンソールを使用してワークフローを作成すると、ワークフローを Google Cloud コンソールで視覚的にレンダリングできず、次のような警告が表示される場合があります。

ワークフロー作成に関する警告

この問題を解決するには、YAML 式を単一引用符で囲みます。

推奨: '${"a: " +string(a)}'

おすすめしません ${"a: " +string(a)}

英数字以外の文字を使用したマップキー

英数字以外の文字（"special!key": value の感嘆符など）を含むマップキーにアクセスする場合は、キーの名前を引用符で囲む必要があります。キーの名前が引用符で囲まれていないと、ワークフローをデプロイできません。たとえば、次のソースコードをデプロイしようとすると、token recognition error がスローされます。

- init:
    assign:
    - var:
        key:
            "special!key": bar
- returnOutput:
    return: '${"foo" + var.key[special!key]}'

この問題を解決するには、次のコードを使用して出力を返します。

'${"foo" + var.key["special!key"]}'

リスト内の複数の式

次の反復処理の範囲の例のようなリスト内で複数の式を使用することは、有効な YAML ではありません。

[${rangeStart}, ${rangeEnd}])

この問題を解決するには、次のいずれかの操作を行います。

リストを式の中に配置します。

${[rangeStart, rangeEnd]}
各式を単一引用符で囲みます。

['${rangeStart}', '${rangeEnd}']

結果は、想定されるとおり 2 つの値のリストです。

顧客管理の暗号鍵（CMEK）

ワークフローで Cloud KMS を使用すると、エラーが発生する可能性があります。次の表にさまざまな問題とその解決方法を示します。

問題	説明
権限 `cloudkms.cryptoKeyVersions.useToEncrypt` が拒否されました	指定された Cloud KMS 鍵が存在しないか、権限が適切に構成されていません。解決方法: Cloud KMS 鍵が存在することを確認します。指定したキーリングの鍵を一覧表示し、その使用状況を確認します。 Workflows サービスエージェントに鍵へのアクセス権があり、`cloudkms.cryptoKeyEncrypterDecrypter` ロールが付与されていることを確認します。
鍵バージョンが有効になっていない	指定された Cloud KMS 鍵バージョンが無効になっています。解決方法: Cloud KMS 鍵バージョンを再度有効にします。
キーリングのリージョンが、保護対象のリソースと一致しません	指定された KMS キーリングリージョンがワークフローのリージョンとは異なります。解決方法: Cloud KMS キーリングと同じリージョンの保護されたワークフローを使用します（異なるプロジェクトに存在することもあります）。詳細については、Cloud KMS のロケーションと Workflows のロケーションをご覧ください。
Cloud KMS の割り当て上限を超えている	Cloud KMS リクエストの割り当て上限に達しました。解決方法: Cloud KMS の呼び出し数を制限するか、割り当ての上限を増やします。詳細については、Cloud KMS の割り当てをご覧ください。

Cloud Run コネクタを使用しているときに、リクエストされたエンティティが見つからない

コネクタメソッド googleapis.run.v1.namespaces.jobs.create を使用しようとしたときに、HTTP サーバーがエラーコード 404 で応答すると、ワークフローの実行が失敗します。

この方法では、HTTP エンドポイントの場所を指定する必要があります。たとえば、us-central1 や、asia-southeast1 です。ロケーションを指定しない場合は、グローバルエンドポイント https://run.googleapis.com が使用されます。ただし、このロケーションでは list メソッドのみがサポートされます。

この問題を解決するには、コネクタを呼び出すときに location 引数を指定します。Cloud Run Admin API のロケーションオプションについては、サービスエンドポイントをご覧ください。

リソースの上限

リソース上限、または ResourceLimitError、MemoryLimitExceededError、ResultSizeLimitExceededError などのエラーが発生した場合は、変数をクリアしてメモリを開放できます。たとえば、後続のステップに必要なメモリを解放する場合などです。また、懸念する点がない結果で呼び出しを行い、それらの結果をすべて省略することもできます。

YAML のインデント

YAML のインデントには意味があります。インデントレベルごとに少なくとも 2 つのスペースが必要です。インデントの不足でエラーが発生する可能性があります。新しいレベルの場合は、前の行のテキストの先頭から 2 個以上のスペースを挿入する必要があります。

たとえば、次の例では、stepName アイテムと call アイテムを持つマップを含むリストアイテムが誤って指定されています。

- stepName:
  call: sys.log

代わりに、次の行を 2 つのスペースでインデントして、stepName 内に call をネストする必要があります。

- stepName:
    call: sys.log

行のインデントには、タブ文字ではなくスペースを使用してください。

次のステップ

Workflows の既知の問題

問題のトラブルシューティング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。