Zeebe 命令绑定说明

关于 Zeebe 命令绑定组件的详细文档

组件格式说明

要配置 Zeebe 命令绑定，请创建一个类型为 bindings.zeebe.command 的组件。请参考本指南了解如何创建和应用绑定配置。

有关 Zeebe 的更多信息，请查看此处的文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.zeebe.command
  version: v1
  metadata:
  - name: gatewayAddr
    value: "<host>:<port>"
  - name: gatewayKeepAlive
    value: "45s"
  - name: usePlainTextConnection
    value: "true"
  - name: caCertificatePath
    value: "/path/to/ca-cert"

元数据字段说明

字段	必需	绑定支持	详情	示例
`gatewayAddr`	Y	输出	Zeebe 网关地址	`"localhost:26500"`
`gatewayKeepAlive`	N	输出	设置发送到网关的保活消息的频率。默认为 45 秒	`"45s"`
`usePlainTextConnection`	N	输出	是否使用纯文本连接	`"true"`, `"false"`
`caCertificatePath`	N	输出	CA 证书的路径	`"/path/to/ca-cert"`

绑定支持

此组件支持以下操作的输出绑定：

topology
deploy-process
deploy-resource
create-instance
cancel-instance
set-variables
resolve-incident
publish-message
activate-jobs
complete-job
fail-job
update-job-retries
throw-error

输出绑定

Zeebe 在此绑定中使用的客户端底层依赖 gRPC。请查阅 gRPC API 参考以获取更多信息。

topology

topology 操作用于获取网关所属集群的当前拓扑。

要执行 topology 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {},
  "operation": "topology"
}

响应

绑定返回一个包含以下信息的 JSON：

{
  "brokers": [
    {
      "nodeId": null,
      "host": "172.18.0.5",
      "port": 26501,
      "partitions": [
        {
          "partitionId": 1,
          "role": null,
          "health": null
        }
      ],
      "version": "0.26.0"
    }
  ],
  "clusterSize": 1,
  "partitionsCount": 1,
  "replicationFactor": 1,
  "gatewayVersion": "0.26.0"
}

响应值为：

brokers - 集群中的 broker 列表
- nodeId - broker 的唯一节点 ID
- host - broker 的主机名
- port - broker 的端口
- partitions - 此 broker 管理或复制的分区列表
  - partitionId - 分区的唯一 ID
  - role - broker 在此分区中的角色
  - health - 分区的健康状况
- version - broker 版本
clusterSize - 集群中的节点数量
partitionsCount - 集群中分布的分区数量
replicationFactor - 集群配置的复制因子
gatewayVersion - 网关版本

deploy-process

deploy-process 的弃用别名为 ‘deploy-resource’。

deploy-resource

deploy-resource 操作用于将单个资源部署到 Zeebe。资源可以是流程（BPMN）或决策和决策需求（DMN）。

要执行 deploy-resource 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": "YOUR_FILE_CONTENT",
  "metadata": {
    "fileName": "products-process.bpmn"
  },
  "operation": "deploy-resource"
}

元数据参数为：

fileName - 资源文件的名称

响应

绑定返回一个包含以下信息的 JSON：

BPMN
DMN

{
  "key": 2251799813685252,
  "deployments": [
    {
      "Metadata": {
        "Process": {
          "bpmnProcessId": "products-process",
          "version": 2,
          "processDefinitionKey": 2251799813685251,
          "resourceName": "products-process.bpmn"
        }
      }
    }
  ]
}

{
  "key": 2251799813685253,
  "deployments": [
    {
      "Metadata": {
        "Decision": {
          "dmnDecisionId": "products-approval",
          "dmnDecisionName": "Products approval",
          "version": 1,
          "decisionKey": 2251799813685252,
          "dmnDecisionRequirementsId": "Definitions_0c98xne",
          "decisionRequirementsKey": 2251799813685251
        }
      }
    },
    {
      "Metadata": {
        "DecisionRequirements": {
          "dmnDecisionRequirementsId": "Definitions_0c98xne",
          "dmnDecisionRequirementsName": "DRD",
          "version": 1,
          "decisionRequirementsKey": 2251799813685251,
          "resourceName": "products-approval.dmn"
        }
      }
    }
  ]
}

响应值为：

key - 部署的唯一标识键
deployments - 已部署资源的列表，例如流程
- metadata - 部署元数据，每个部署只有一个元数据
  - process- 已部署流程的元数据
    - bpmnProcessId - 部署期间解析的 bpmn 流程 ID；与版本一起构成特定流程定义的唯一标识符
    - version - 分配的流程版本
    - processDefinitionKey - 分配的键，作为此流程的唯一标识符
    - resourceName - 解析此流程的资源名称
  - decision - 已部署决策的元数据
    - dmnDecisionId - 部署期间解析的 dmn 决策 ID；与版本一起构成特定决策的唯一标识符
    - dmnDecisionName - 部署期间解析的决策的 dmn 名称
    - version - 分配的决策版本
    - decisionKey - 分配的决策键，作为此决策的唯一标识符
    - dmnDecisionRequirementsId - 部署期间解析的决策需求图的 dmn ID，此决策是其一部分
    - decisionRequirementsKey - 此决策所属的决策需求图的分配键
  - decisionRequirements - 已部署决策需求的元数据
    - dmnDecisionRequirementsId - 部署期间解析的 dmn 决策需求 ID；与版本一起构成特定决策的唯一标识符
    - dmnDecisionRequirementsName - 部署期间解析的决策需求的 dmn 名称
    - version - 分配的决策需求版本
    - decisionRequirementsKey - 分配的决策需求键，作为此决策需求的唯一标识符
    - resourceName - 解析此决策需求的资源名称

create-instance

create-instance 操作用于创建并启动指定流程的实例。可以使用其唯一键（由 deploy-process 操作返回）或使用 BPMN 流程 ID 和版本来指定要用于创建实例的流程定义。

请注意，只有具有无启动事件的流程才能通过此命令启动。

通常，流程创建和执行是解耦的。这意味着命令创建一个新的流程实例并立即响应流程实例 ID。流程的执行在响应发送后发生。然而，有些用例需要在流程执行完成时收集结果。通过定义 withResult 属性，命令允许“同步”执行流程并通过一组变量接收结果。响应在流程执行完成时发送。

有关更多信息，请访问官方文档。

要执行 create-instance 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "bpmnProcessId": "products-process",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "create-instance"
}

{
  "data": {
    "processDefinitionKey": 2251799813685895,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "create-instance"
}

{
  "data": {
    "bpmnProcessId": "products-process",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    },
    "withResult": true,
    "requestTimeout": "30s",
    "fetchVariables": ["productId"]
  },
  "operation": "create-instance"
}

数据参数为：

bpmnProcessId - 要实例化的流程定义的 BPMN 流程 ID
processDefinitionKey - 要实例化的流程定义的唯一键
version - （可选，默认：最新版本）要实例化的流程版本
variables - （可选）JSON 文档，将为流程实例的根变量范围实例化变量；它必须是一个 JSON 对象，因为变量将以键值对的方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联的值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是一个数组而不是对象
withResult - （可选，默认：false）如果设置为 true，流程将被同步实例化和执行
requestTimeout - （可选，仅在 withResult=true 时使用）如果流程在 requestTimeout 之前未完成，请求将被关闭。如果 requestTimeout = 0，则使用网关中配置的通用 requestTimeout。
fetchVariables - （可选，仅在 withResult=true 时使用）要包含在响应的 variables 属性中的变量名称列表。如果为空，将返回根范围内的所有可见变量。

响应

绑定返回一个包含以下信息的 JSON：

{
  "processDefinitionKey": 2251799813685895,
  "bpmnProcessId": "products-process",
  "version": 3,
  "processInstanceKey": 2251799813687851,
  "variables": "{\"productId\":\"some-product-id\"}"
}

响应值为：

processDefinitionKey - 用于创建流程实例的流程定义的键
bpmnProcessId - 用于创建流程实例的流程定义的 BPMN 流程 ID
version - 用于创建流程实例的流程定义的版本
processInstanceKey - 创建的流程实例的唯一标识符
variables - （可选，仅在请求中使用了 withResult=true 时）JSON 文档，由根范围内的可见变量组成；作为序列化的 JSON 文档返回

cancel-instance

cancel-instance 操作用于取消正在运行的流程实例。

要执行 cancel-instance 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "processInstanceKey": 2251799813687851
  },
  "operation": "cancel-instance"
}

数据参数为：

processInstanceKey - 流程实例键

响应

绑定不返回响应正文。

set-variables

set-variables 操作用于为元素实例（例如流程实例、流程元素实例）创建或更新变量。

要执行 set-variables 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "elementInstanceKey": 2251799813687880,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "set-variables"
}

数据参数为：

elementInstanceKey - 特定元素的唯一标识符；可以是流程实例键（在实例创建期间获得），或给定元素，例如服务任务（请参阅 job 消息上的 elementInstanceKey）
local - （可选，默认：false）如果为 true，变量将严格合并到本地范围（由 elementInstanceKey 指示）；这意味着变量不会传播到上层范围。例如，假设我们有两个范围，‘1’ 和 ‘2’，每个范围的有效变量为： 1 => { "foo" : 2 }，和 2 => { "bar" : 1 }。如果我们发送一个更新请求，elementInstanceKey = 2，变量 { "foo" : 5 }，并且 local 为 true，那么范围 1 将保持不变，范围 2 将变为 { "bar" : 1, "foo" 5 }。然而，如果 local 为 false，那么范围 1 将为 { "foo": 5 }，范围 2 将为 { "bar" : 1 }
variables - 描述变量的键值对的 JSON 序列化文档；文档的根必须是一个对象

响应

绑定返回一个包含以下信息的 JSON：

{
  "key": 2251799813687896
}

响应值为：

key - 设置变量命令的唯一键

resolve-incident

resolve-incident 操作用于解决一个事件。

要执行 resolve-incident 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "incidentKey": 2251799813686123
  },
  "operation": "resolve-incident"
}

数据参数为：

incidentKey - 要解决的事件的唯一 ID

响应

绑定不返回响应正文。

publish-message

publish-message 操作用于发布一条消息。消息发布到从其关联键计算出的特定分区。

要执行 publish-message 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "messageName": "product-message",
    "correlationKey": "2",
    "timeToLive": "1m",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    },
  },  
  "operation": "publish-message"
}

数据参数为：

messageName - 消息的名称
correlationKey - （可选）消息的关联键
timeToLive - （可选）消息在 broker 上缓冲的时间
messageId - （可选）消息的唯一 ID；可以省略。仅用于确保在其生命周期内只有一条具有给定 ID 的消息会被发布
variables - （可选）消息变量作为 JSON 文档；要有效，文档的根必须是一个对象，例如 { “a”: “foo” }。[ “foo” ] 将不是有效的

响应

绑定返回一个包含以下信息的 JSON：

{
  "key": 2251799813688225
}

响应值为：

key - 发布的消息的唯一 ID

activate-jobs

activate-jobs 操作以轮询方式遍历所有已知分区并激活最多请求的最大数量，并在激活时将其流式传输回客户端。

要执行 activate-jobs 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobType": "fetch-products",
    "maxJobsToActivate": 5,
    "timeout": "5m",
    "workerName": "products-worker",
    "fetchVariables": [
      "productId",
      "productName",
      "productKey"
    ],
    "requestTimeout": "30s"
  },
  "operation": "activate-jobs"
}

数据参数为：

jobType - 作业类型，如 BPMN 流程中定义的（例如 <zeebe:taskDefinition type="fetch-products" />）
maxJobsToActivate - 此请求要激活的最大作业数
timeout - （可选，默认：5 分钟）此调用返回的作业在超时之前不会被另一个调用激活
workerName - （可选，默认：default）激活作业的工作者的名称，主要用于日志记录目的
fetchVariables - （可选）要作为作业变量获取的变量列表；如果为空，将返回作业范围内激活时的所有可见变量
requestTimeout - （可选）请求将在至少一个作业被激活或在 requestTimeout 之后完成。如果 requestTimeout = 0，则使用默认超时。如果 requestTimeout < 0，则禁用长轮询，并且请求立即完成，即使没有作业被激活。

响应

绑定返回一个包含以下信息的 JSON：

[
  {
    "key": 2251799813685267,
    "type": "fetch-products",
    "processInstanceKey": 2251799813685260,
    "bpmnProcessId": "products",
    "processDefinitionVersion": 1,
    "processDefinitionKey": 2251799813685249,
    "elementId": "Activity_test",
    "elementInstanceKey": 2251799813685266,
    "customHeaders": "{\"process-header-1\":\"1\",\"process-header-2\":\"2\"}",
    "worker": "test", 
    "retries": 1,
    "deadline": 1694091934039,
    "variables":"{\"productId\":\"some-product-id\"}"
  }
]

响应值为：

key - 作业的键，作业的唯一标识符
type - 作业的类型（应与请求的类型匹配）
processInstanceKey - 作业的流程实例键
bpmnProcessId - 作业流程定义的 bpmn 流程 ID
processDefinitionVersion - 作业流程定义的版本
processDefinitionKey - 作业流程定义的键
elementId - 关联的任务元素 ID
elementInstanceKey - 唯一标识关联任务的唯一键，在流程实例范围内唯一
customHeaders - 在建模期间定义的一组自定义头；作为序列化的 JSON 文档返回
worker - 激活此作业的工作者的名称
retries - 此作业剩余的重试次数（应始终为正）
deadline - 作业可以再次激活的时间，以 UNIX 纪元时间戳发送
variables - 在激活时计算，由任务范围内的所有可见变量组成；作为序列化的 JSON 文档返回

complete-job

complete-job 操作使用给定的负载完成作业，从而允许完成关联的服务任务。

要执行 complete-job 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813686172,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "complete-job"
}

数据参数为：

jobKey - 唯一的作业标识符，从激活作业响应中获得
variables - （可选）表示当前任务范围内变量的 JSON 文档

响应

绑定不返回响应正文。

fail-job

fail-job 操作将作业标记为失败；如果重试参数为正，则作业将立即可再次激活，并且工作者可以再次尝试处理它。然而，如果为零或负数，则会引发事件，并标记为给定的错误消息，并且作业在事件解决之前不会被激活。

要执行 fail-job 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813685739,
    "retries": 5,
    "errorMessage": "some error occurred",
    "retryBackOff": "30s",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "fail-job"
}

数据参数为：

jobKey - 激活作业时获得的唯一作业标识符
retries - 作业应剩余的重试次数
errorMessage - （可选）描述作业失败原因的消息，这在作业用尽重试次数并引发事件时特别有用，因为此消息可以帮助解释为什么引发事件
retryBackOff - （可选）下次重试的回退超时
variables - （可选）JSON 文档，将在作业关联任务的本地范围内实例化变量；它必须是一个 JSON 对象，因为变量将以键值对的方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联的值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

update-job-retries

update-job-retries 操作用于更新作业剩余的重试次数。这对于作业用尽重试次数的情况特别有用，假设底层问题已解决。

要执行 update-job-retries 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813686172,
    "retries": 10
  },
  "operation": "update-job-retries"
}

数据参数为：

jobKey - 通过 activate-jobs 操作获得的唯一作业标识符
retries - 作业的新重试次数；必须为正

响应

绑定不返回响应正文。

throw-error

throw-error 操作用于抛出一个错误，以指示在处理作业时发生了业务错误。错误由错误代码标识，并由流程中具有相同错误代码的错误捕获事件处理。

要执行 throw-error 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813686172,
    "errorCode": "product-fetch-error",
    "errorMessage": "The product could not be fetched",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "throw-error"
}

数据参数为：

jobKey - 激活作业时获得的唯一作业标识符
errorCode - 将与错误捕获事件匹配的错误代码
errorMessage - （可选）提供附加上下文的错误消息
variables - （可选）JSON 文档，将在作业关联任务的本地范围内实例化变量；它必须是一个 JSON 对象，因为变量将以键值对的方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联的值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Zeebe 命令绑定说明

组件格式说明

元数据字段说明

绑定支持

输出绑定

topology

响应

deploy-process

deploy-resource

响应

create-instance

响应

cancel-instance

响应

set-variables

响应

resolve-incident

响应

publish-message

响应

activate-jobs

响应

complete-job

响应

fail-job

响应

update-job-retries

响应

throw-error

响应

相关链接

Feedback