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：

{
  "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 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

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

响应

相关链接