排查问题

本页面介绍如何解决在使用 Workflows 时可能遇到的问题。

如需了解详情，请参阅监控和调试 Workflows。

部署错误

部署工作流后，Workflows 会检查源代码是否正确无误，并符合语言语法。 如果发现错误，Workflows 会返回该错误。最常见的部署错误类型包括：

• 引用未定义的变量、步骤或子工作流
• 语法不正确
  • 缩进不正确
  • {、}、"、- 或 : 缺失或无关紧要

例如，以下源代码抛出部署错误，因为返回语句引用了未定义的变量 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

如需解决此问题，请修改工作流的源代码。在这种情况下，请参阅 varA 而不是 varC。

HTTP 403 服务账号权限错误

当 HTTP 服务器响应错误代码 403 时，您的工作流执行会失败。例如：

Permission 'iam.serviceaccounts.actAs' denied on service
account [e-mail] (or it may not exist).

或

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).

每个工作流在创建时都会与一个 IAM 服务账号相关联。如需解决此问题，您必须向服务账号授予一个或多个 IAM 角色，这些角色包含管理工作流所需的最小权限。例如，如果您希望让工作流将日志发送到 Cloud Logging，请确保已向执行工作流的服务账号授予了包含 logging.logEntries.create 权限的角色。如需了解详情，请参阅向工作流授予访问 Google Cloud 资源的权限。

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_encode 和 url_encode_plus 函数对这些字符进行编码。例如：

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

如果您未对对象名称进行网址编码，并且您的存储桶包含文件夹，请求将失败。如需了解详情，请参阅对网址路径部分进行编码和 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}']

结果便会如预期所示，是一个包含两个值的列表。

客户管理的加密密钥 (CMEK)

将 Cloud KMS 与 Workflows 搭配使用时，您可能会遇到错误。下表介绍了不同的问题以及如何解决这些问题。

问题	说明
权限 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 连接器时，未找到请求的实体

当 HTTP 服务器在尝试使用连接器方法 googleapis.run.v1.namespaces.jobs.create 时响应 404 错误代码时，您的工作流执行会失败。

此方法要求您指定 HTTP 端点的位置。例如 us-central1 或 asia-southeast1。如果您未指定位置，则系统会使用全局端点 https://run.googleapis.com；不过，此位置仅支持列表方法。

如需解决此问题，请务必在调用连接器时指定 location 参数。如需了解 Cloud Run Admin API 位置选项，请参阅服务端点。

资源限制

如果您遇到资源限制或 ResourceLimitError、MemoryLimitExceededError 或 ResultSizeLimitExceededError 等错误，可以通过清除变量来释放内存。例如，您可能需要释放后续步骤所需的内存。或者，您可能有调用包含不感兴趣的结果，您可以完全忽略这些结果。

YAML 缩进

YAML 缩进是有意义的，每个缩进级别至少应有两个空格。缩进不足可能会导致错误，新级别应该在上一行文本开头的基础上缩进至少两个空格。

例如，以下代码错误地指定了一个包含 stepName 和 call 项的地图的列表项：

- stepName:
  call: sys.log

相反，您应将后续行缩进两个空格，以便将 call 嵌套在 stepName 中：

- stepName:
    call: sys.log

请务必使用空格（而非制表符）缩进代码行。

后续步骤

• Workflows 的已知问题