执行工作流

执行某个工作流会运行与该工作流关联的当前工作流定义。

您可以在工作流执行请求中传递运行时参数，以及使用工作流变量访问这些参数。如需了解详情，请参阅 在执行请求中传递运行时参数。

工作流执行完成后，其历史记录和结果将保留有限的一段时间。如需了解详情，请参阅配额和限制。

准备工作

您的组织定义的安全限制条件可能会导致您无法完成以下步骤。如需了解相关问题排查信息，请参阅 在受限的环境中开发应用 Google Cloud 。

登录您的 Google Cloud 账号。如果您是 Google Cloud新手， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 如果工作流访问其他 Google Cloud 资源，请确保它与具有正确权限来执行此操作的服务帐号相关联。如需了解与现有工作流关联的服务帐号，请参阅验证工作流的关联服务账号。

   请注意，如需创建资源并关联服务帐号，您需要具备创建该资源的权限以及模拟您将关联到该资源的服务帐号的权限。如需了解详情，请参阅 服务账号权限。

2. 使用 Google Cloud 控制台 或 Google Cloud CLI部署工作流。

注意 ：要向 Cloud Logging 发送日志，请确保已执行工作流的服务帐号被授予了包含 logging.logEntries.create 权限的角色（例如 Logs Writer 角色）。

执行工作流

您可以通过以下方式执行工作流：

• 在 Google Cloud 控制台中
• 在终端或 Cloud Shell 中使用 Google Cloud CLI
• 向 Workflows API 发送直接请求

您还可以使用 Cloud 客户端库执行工作流。如需了解详情，请参阅 使用 Cloud 客户端库执行工作流。

控制台

1. 如需执行工作流，请在 Google Cloud 控制台中，转到 Workflows 页面：

   进入 Workflows

2. 在 Workflows 页面上，选择一个工作流以转到其详情页面。

3. 在工作流详情 页面上，点击 执行。

4. 在执行工作流 页面的输入 窗格中，输入 可选的运行时参数 ，以传递给工作流执行。参数必须采用 JSON 格式；例如 {"animal":"cat"}。如果您的工作流不使用运行时参数，请将此字段留空。

5. （可选）指定要应用于工作流执行的 调用日志记录级别。在通话记录级别 列表中，选择以下选项之一：

   • 未指定：未指定日志记录级别。这是默认设置。 除非未指定执行日志级别（默认），否则执行日志级别优先于任何工作流日志级别；在这种情况下，工作流日志级别适用。
   • 仅限错误：记录所有已捕获的异常；或者调用因异常而停止时。
   • 所有调用：记录对子工作流或库函数及其结果的所有调用。
   • 无日志：无调用日志记录。

6. （可选）指定要应用于工作流执行的 执行历史记录级别 。在执行历史记录 列表中，选择以下选项之一：

   • 继承自工作流：应用 工作流的执行历史记录设置。这是默认设置。
   • 基本：启用基本执行历史记录。
   • 详细：启用详细执行历史记录 包括任何范围内的变量值和预期迭代次数。

7. 点击执行 。

8. 在执行详情 页面上，您可以查看执行结果，包括任何输出、执行 ID 和状态，以及工作流执行的当前或最终步骤。如需了解详情， 请参阅 访问工作流执行结果。

   注意：如需访问执行详情 页面，您必须具有包含workflows.workflows.get、workflows.executions.get 和 workflows.stepEntries.list 权限的角色。如需了解详情，请参阅 Workflows 角色和 权限以及 管理访问权限。

gcloud

1. 打开终端。

2. 找到您要执行的工作流的名称。如果您不知道工作流的名称，则可以输入以下命令列出所有工作流：

   gcloud workflows list

3. 您可以使用 gcloud workflows run命令或 gcloud workflows execute 命令执行工作流：

   • 执行工作流并等待执行完成：

     gcloud workflows run WORKFLOW_NAME \
         --call-log-level=CALL_LOGGING_LEVEL \
         --execution-history-level="EXECUTION_HISTORY_LEVEL" \
         --data=DATA

   • 执行工作流，而无需等待执行尝试完成：

     gcloud workflows execute WORKFLOW_NAME \
         --call-log-level=CALL_LOGGING_LEVEL \
         --execution-history-level="EXECUTION_HISTORY_LEVEL" \
         --data=DATA

     替换以下内容：

     • WORKFLOW_NAME：工作流的名称。

     • CALL_LOGGING_LEVEL（可选）：在执行期间应用的调用日志记录级别。可以是以下之一：

       • none：未指定日志记录级别。这是默认设置。除非未指定执行日志级别（默认），否则执行日志级别优先于任何工作流日志级别；在这种情况下，工作流日志级别适用。
       • log-errors-only：记录所有已捕获的异常；或者调用因异常而停止时。
       • log-all-calls：记录对子工作流或库函数及其调用的所有调用。
       • log-none：无调用日志记录。

     • EXECUTION_HISTORY_LEVEL（可选）：在执行期间应用的执行历史记录级别。可以是以下之一：

       • none：未指定执行历史记录级别。这是 默认设置。如果未为执行指定执行历史记录级别，则该级别 由应用于工作流的级别确定。如果级别不同，则应用于执行级别的设置会替换应用于此执行的工作流级别的设置。
       • execution-history-basic：启用基本执行历史记录。
       • execution-history-detailed：启用详细执行历史记录 ，包括任何范围内的变量值和预期迭代次数。

     • DATA （可选）：您的工作流的运行时参数，其采用 JSON 格式。

4. 如果运行 gcloud workflows execute，则返回工作流执行尝试的唯一 ID，输出类似于以下内容：

    To view the workflow status, you can use following command:
    gcloud workflows executions describe b113b589-8eff-4968-b830-8d35696f0b33 --workflow workflow-2 --location us-central1

   如需查看执行状态，请输入上一步返回的命令。

如果执行尝试成功，则输出类似于以下内容，其中 state 表示工作流成功，status 指定执行的最终工作流步骤。

argument: '{"searchTerm":"Friday"}'
endTime: '2022-06-22T12:17:53.086073678Z'
name: projects/1051295516635/locations/us-central1/workflows/myFirstWorkflow/executions/c4dffd1f-13db-46a0-8a4a-ee39c144cb96
result: '["Friday","Friday the 13th (franchise)","Friday Night Lights (TV series)","Friday
    the 13th (1980 film)","Friday the 13th","Friday the 13th (2009 film)","Friday the
    13th Part III","Friday the 13th Part 2","Friday (Rebecca Black song)","Friday Night
    Lights (film)"]'
startTime: '2022-06-22T12:17:52.799387653Z'
state: SUCCEEDED
status:
    currentSteps:
    - routine: main
        step: returnOutput
workflowRevisionId: 000001-ac2

REST API

如需使用给定工作流的最新修订版本创建新的执行作业，请使用 the projects.locations.workflows.executions.create 方法。

注意 ：如需进行身份验证，您需要一个具有足够权限来执行工作流的服务帐号。例如，您可以向服务 账号授予 Workflows Invoker 角色 (roles/workflows.invoker)，以便该账号有权 触发您的工作流执行。如需了解详情，请参阅 调用 Workflows。

在使用任何请求数据之前， 请先进行以下替换：

• PROJECT_NUMBER：您的 Google Cloud 项目编号，列在IAM 和管理 设置页面中。
• LOCATION：部署此工作流的区域，例如 us-central1。
• WORKFLOW_NAME：用户为工作流定义的名称，例如 myFirstWorkflow。
• PARAMETER：可选。如果正在执行的工作流 可以接收您在执行请求中传递给它的运行时参数， 您可以向请求正文添加一个 JSON 格式的字符串，该字符串的值是一个或多个转义的 “参数-值”对，例如 "{\"searchTerm\":\"asia\"}"。
• VALUE：可选。您的工作流可以作为运行时参数接收的 “参数-值”对的值。
• CALL_LOGGING_LEVEL：可选。 在执行期间应用的调用日志记录级别。默认情况下，未指定日志记录级别，而是应用工作流日志级别。如需了解详情，请参阅 将日志发送到 Logging。以下选项之一：
  • CALL_LOG_LEVEL_UNSPECIFIED：未指定日志记录级别，而是应用 工作流日志级别。这是默认设置。否则，执行日志级别 适用，并且优先于工作流日志级别。
  • LOG_ERRORS_ONLY：记录所有已捕获的异常；或者调用因异常而停止时。
  • LOG_ALL_CALLS：记录对子工作流或库函数及其结果的所有调用。
  • LOG_NONE：无调用日志记录。
• BACKLOG_EXECUTION： 可选。如果设置为 true，则在并发配额用尽时，执行不会积压。如需了解详情，请参阅 管理执行积压。
• EXECUTION_HISTORY_LEVEL： 可选。在执行期间应用的执行历史记录级别。如需了解详情，请参阅 查看执行步骤的历史记录。以下选项之一：
  • EXECUTION_HISTORY_LEVEL_UNSPECIFIED：未指定执行历史记录级别。这是默认设置。如果未为执行指定执行历史记录级别，则该级别由应用于工作流的级别确定。如果级别不同，则应用于执行级别的设置会替换应用于此执行的工作流级别的设置。
  • EXECUTION_HISTORY_BASIC：启用基本执行历史记录。
  • EXECUTION_HISTORY_ADVANCED：启用详细执行历史记录 包括任何范围内的变量值和预期迭代次数。

请求 JSON 正文：

{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "disableConcurrencyQuotaOverflowBuffering": "BACKLOG_EXECUTION",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL"
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions" | Select-Object -Expand Content

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行 。

如果成功，响应正文将包含一个新创建的 Execution 实例：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID",
  "startTime": "2023-11-07T14:35:27.215337069Z",
  "state": "ACTIVE",
  "argument": "{\"PARAMETER\":\"VALUE\"}",
  "workflowRevisionId": "000001-2df",
  "callLogLevel": "CALL_LOGGING_LEVEL",
  "executionHistoryLevel": "EXECUTION_HISTORY_LEVEL",
  "status": {}
}

检查执行状态

您可以使用多个命令来帮助检查工作流执行的状态。

• 如需检索工作流的执行尝试及其 ID 列表，请输入以下命令：

  gcloud workflows executions list WORKFLOW_NAME

  将 WORKFLOW_NAME 替换为工作流的名称。

  该命令会返回类似于以下内容的 NAME 值：

  projects/PROJECT_NUMBER/locations/REGION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID

  复制执行 ID 以在下一个命令中使用。

• 如需检查执行尝试的状态并等待尝试完成，请输入以下命令：

  gcloud workflows executions wait EXECUTION_ID

  将 EXECUTION_ID 替换为执行尝试的 ID。

  该命令会等到执行尝试完成后，再返回结果。

• 如需等到上次执行完成，然后返回已完成执行的结果，请输入以下命令：

  gcloud workflows executions wait-last

  如果您在同一个 gcloud 会话中进行了先前的执行尝试，该命令将等到前一个执行尝试完成后，再返回已完成执行的结果。如果前一个尝试不存在，gcloud 将返回以下错误：

  ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
  

• 如需获取上次执行的状态，请输入以下命令：

  gcloud workflows executions describe-last

  如果您在同一个 gcloud 会话中进行了先前的执行尝试，该命令会返回上次执行的结果，即使该执行正在运行也是如此。如果前一个尝试不存在，gcloud 将返回以下错误：

  ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
  

过滤执行

您可以将过滤条件应用于工作流执行列表，该列表由 workflows.executions.list方法返回。

您可以根据以下字段进行过滤：

• createTime
• disableOverflowBuffering
• duration
• endTime
• executionId
• label
• startTime
• state
• stepName
• workflowRevisionId

例如，如需根据标签 (labels."fruit":"apple") 进行过滤，您可以发出类似于以下内容的 API 请求：

GET https://workflowexecutions.googleapis.com/v1/projects/MY_PROJECT/locations/MY_LOCATION/workflows/MY_WORKFLOW/executions?view=full&filter=labels.%22fruit%22%3A%22apple%22"

其中：

• view=full 指定一个视图，用于定义应在返回的执行中填充哪些字段；在本例中，为所有数据
• labels.%22fruit%22%3A%22apple%22 是网址编码的过滤条件语法

如需了解详情，请参阅 AIP-160 过滤。

管理执行积压

您可以使用执行积压来避免客户端重试、消除执行延迟并最大限度地提高吞吐量。积压的执行作业会在执行并发配额可用后自动运行。

最佳实践：如果运行工作流执行作业的时间有限 或时间敏感，则不建议使用执行积压，并且 您应考虑停用此功能。

可以同时运行的活跃工作流 执行作业数量上限。一旦此配额用尽，并且停用了执行积压，或者达到了积压执行作业的配额，任何新的执行作业都会失败，并返回 HTTP 429 Too many requests 状态代码。启用执行积压后，新的执行作业会成功，并以 QUEUED 状态创建。执行并发配额可用后，执行作业会自动运行并进入 ACTIVE 状态。

默认情况下，所有请求（包括由 Cloud Tasks 触发的请求）都启用了执行积压，但以下情况除外：

• 在工作流中使用 executions.run 或 executions.create 连接器创建执行作业时，默认情况下会停用执行积压。您可以通过将执行作业的 disableConcurrencyQuotaOverflowBuffering 字段明确设置为 false 来配置它。
• 对于由 Pub/Sub 触发的执行作业，执行积压处于 停用状态，并且 无法配置。

请注意以下几点：

• 系统会尽力按先进先出 (FIFO) 顺序启动排队的执行作业。
• createTime 时间戳字段表示执行作业的创建时间。startTime 时间戳表示执行作业自动从积压队列中弹出并开始运行的时间。对于未积压的执行作业，这两个时间戳值相同。
• 您可以使用 workflowexecutions.googleapis.com/executionbacklogentries 配额指标来观察积压执行作业的限制。如需了解详情，请参阅查看和管理配额。

停用执行积压

您可以在使用 Google Cloud CLI 时设置标志来停用执行积压。例如：

gcloud workflows execute WORKFLOW_NAME
    --disable-concurrency-quota-overflow-buffering

或者，您可以在向 Workflows REST API 发送执行请求时，在请求 JSON 正文中将 disableConcurrencyQuotaOverflowBuffering 字段设置为 true，以停用执行积压。 例如：

{
  "argument": {"arg1":"value1"},
  "callLogLevel": "LOG_NONE",
  "disableConcurrencyQuotaOverflowBuffering": true
}

如需了解详情，请参阅执行工作流。

后续步骤

• 访问工作流执行结果
• 控制工作流中的执行顺序
• 将执行日志发送到 Cloud Logging
• 更新现有工作流