This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dapr API 参考

有关每个 API、关联的端点以及可用功能的信息

1 - Actors API 参考文档

Actors API 的详细文档

Dapr 提供了原生、跨平台且跨语言的 virtual actor 功能。 除了特定语言的 SDK外，开发者还可以使用以下 API 端点来调用 actor。

用户服务代码调用 Dapr

调用 actor 方法

通过 Dapr 调用 actor 方法。

HTTP 请求

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP 响应码

代码描述
200请求成功
500请求失败
XXX来自上游调用的状态码

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
method要调用的方法名称。

注意，所有 URL 参数都区分大小写。

示例

调用 actor 方法的示例：

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
  -H "Content-Type: application/json"

您可以在请求正文中提供方法参数和值，例如在 curl 中使用 -d "{\"param\":\"value\"}"。调用带参数的 actor 方法的示例：

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d '{
        "destination": "Hoth"
      }'

或

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d "{\"destination\":\"Hoth\"}"

来自远程端点的响应（方法返回值）会在请求正文中返回。

Actor 状态事务

将 actor 的状态更改作为多项事务持久化。

请注意，此操作依赖于使用支持多项事务的状态存储组件。

TTL

在启用了 ActorStateTTL 功能的情况下，actor 客户端可以在事务元数据中设置 ttlInSeconds 字段，使状态在指定的秒数后过期。如果未设置 ttlInSeconds 字段，状态将不会过期。

在构建启用此功能的 actor 应用程序时请记住； 目前，所有 actor SDK 都会在其本地缓存中保留 actor 状态，即使在状态已过期之后。这意味着，如果 TTL 已过期，actor 状态不会从本地缓存中移除，直到 actor 重新启动或停用。此行为将在未来版本中更改。

有关 actor 状态 TTL 的更多详细信息，请参阅 Dapr Community Call 80 录像。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state

HTTP 响应码

代码描述
204请求成功
400Actor 未找到
500请求失败

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。

注意，所有 URL 参数都区分大小写。

示例

注意，以下示例使用了 ttlInSeconds 字段，该字段需要启用了 ActorStateTTL 功能。

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
  -H "Content-Type: application/json" \
  -d '[
       {
         "operation": "upsert",
         "request": {
           "key": "key1",
           "value": "myData",
           "metadata": {
             "ttlInSeconds": "3600"
           }
         }
       },
       {
         "operation": "delete",
         "request": {
           "key": "key2"
         }
       }
      ]'

获取 actor 状态

使用指定的键获取 actor 的状态。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP 响应码

代码描述
200请求成功
204键未找到，响应将为空
400Actor 未找到
500请求失败

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
key状态值的键。

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
  -H "Content-Type: application/json"

上述命令返回状态：

{
  "location": "Alderaan"
}

创建 actor 提醒

为 actor 创建持久化提醒。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

提醒请求正文

包含以下字段的 JSON 对象：

字段描述
dueTime指定在提醒被调用之后的时间。其格式应为 time.ParseDuration
period指定不同调用之间的时间间隔。其格式应为 time.ParseDuration 或 ISO 8601 持续时间格式，带有可选的重复。
ttl设置定时器或提醒到期和删除的时间或间隔。其格式应为 time.ParseDuration 格式、RFC3339 日期格式或 ISO 8601 持续时间格式。
data一个字符串值，可以是任何相关内容。提醒过期时返回内容。例如，这对于返回 URL 或与内容相关的任何内容可能很有用。

period 字段支持 time.Duration 格式和 ISO 8601 格式，但有一些限制。对于 period，仅支持 ISO 8601 持续时间 Rn/PnYnMnWnDTnHnMnS 的持续时间格式。Rn/ 指定提醒将被调用 n 次。

  • n 应为大于 0 的正整数。
  • 如果某些值为 0，可以缩短 period；例如，10 秒可以在 ISO 8601 持续时间中指定为 PT10S。

如果未指定 Rn/，提醒将运行无限次，直到被删除。

如果仅设置了 ttl 和 dueTime，则将接受提醒。但是，只有 dueTime 生效。例如，提醒在 dueTime 触发，而 ttl 被忽略。

如果设置了 ttl、dueTime 和 period，提醒将首先在 dueTime 触发，然后根据 period 和 ttl 重复触发和过期。

以下示例指定了 3 秒的 dueTime 和 7 秒的 period。

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

dueTime 为 0 意味着立即触发。以下正文意味着立即触发，然后每 9 秒触发一次。

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

要将提醒配置为仅触发一次，period 应设置为空字符串。以下内容指定了 3 秒的 dueTime，period 为空字符串，这意味着提醒将在 3 秒后触发，然后再也不会触发。

{
  "dueTime":"0h0m3s0ms",
  "period":""
}

当您在 period 和 ttl 中都指定重复次数时，定时器/提醒会在满足任一条件时停止。以下示例的定时器具有 3 秒的 period（ISO 8601 持续时间格式）和 20 秒的 ttl。此定时器在注册后立即触发，然后在 20 秒的持续时间内每 3 秒触发一次，之后由于 ttl 已满足而不再触发

{
  "period":"PT3S",
  "ttl":"20s"
}

需要 data 的描述。

{
  "data": "someData",
  "dueTime": "1m",
  "period": "20s"
}

HTTP 响应码

代码描述
204请求成功
500请求失败
400Actor 未找到或请求格式错误

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
name要创建的提醒的名称。

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s"
    }'

获取 actor 提醒

获取 actor 的提醒。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP 响应码

代码描述
200请求成功
500请求失败

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
name要获取的提醒的名称。

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  "Content-Type: application/json"

上述命令返回提醒：

{
  "dueTime": "1s",
  "period": "5s",
  "data": "0",
}

删除 actor 提醒

删除 actor 的提醒。

HTTP 请求

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP 响应码

代码描述
204请求成功
500请求失败

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
name要删除的提醒的名称。

注意，所有 URL 参数都区分大小写。

示例

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json"

创建 actor 定时器

为 actor 创建定时器。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

定时器请求正文：

定时器请求正文的格式与 actor 提醒 相同。例如：

以下内容指定了 3 秒的 dueTime 和 7 秒的 period。

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

dueTime 为 0 意味着立即触发。以下正文意味着立即触发，然后每 9 秒触发一次。

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

HTTP 响应码

代码描述
204请求成功
500请求失败
400Actor 未找到或请求格式错误

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
name要创建的定时器的名称。

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
    -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s",
      "callback": "myEventHandler"
    }'

删除 actor 定时器

删除 actor 的定时器。

HTTP 请求

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

HTTP 响应码

代码描述
204请求成功
500请求失败

URL 参数

参数描述
daprPortDapr 端口。
actorTypeactor 类型。
actorIdactor ID。
name要删除的定时器的名称。

注意，所有 URL 参数都区分大小写。

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
  -H "Content-Type: application/json"

Dapr 调用用户服务代码

获取已注册的 actor

获取此应用程序的已注册 actor 类型和 Dapr actor 配置设置。

HTTP 请求

GET http://localhost:<appPort>/dapr/config

HTTP 响应码

代码描述
200请求成功
500请求失败

URL 参数

参数描述
appPort应用程序端口。

示例

获取已注册 actor 的示例：

curl -X GET http://localhost:3000/dapr/config \
  -H "Content-Type: application/json"

上述命令返回配置（所有字段都是可选的）：

参数描述
entities此应用程序支持的 actor 类型。
actorIdleTimeout指定在停用空闲 actor 之前等待的时间。如果未调用 actor 方法且未触发提醒，则 actor 处于空闲状态。
actorScanInterval指定扫描 actor 以停用空闲 actor 的频率的持续时间。空闲时间超过 actorIdleTimeout 的 actor 将被停用。
drainOngoingCallTimeout在排空重新平衡的 actor 的过程中使用的持续时间。这指定等待当前活动 actor 方法完成的时间。如果没有当前 actor 方法调用，则忽略此项。
drainRebalancedActors布尔值。如果为 true，Dapr 将等待 drainOngoingCallTimeout 以允许当前 actor 调用在尝试停用 actor 之前完成。如果为 false，则不等待。
reentrancy一个配置对象，保存 actor 重入的选项。
enabled重入配置中的一个标志，需要启用重入。
maxStackDepth重入配置中的一个值，控制对同一 actor 进行多少次重入调用。
entitiesConfig实体配置数组，允许每个 actor 类型设置。此处定义的任何配置都必须有一个映射回根级别实体的实体。
{
  "entities":["actorType1", "actorType2"],
  "actorIdleTimeout": "1h",
  "actorScanInterval": "30s",
  "drainOngoingCallTimeout": "30s",
  "drainRebalancedActors": true,
  "reentrancy": {
    "enabled": true,
    "maxStackDepth": 32
  },
  "entitiesConfig": [
      {
          "entities": ["actorType1"],
          "actorIdleTimeout": "1m",
          "drainOngoingCallTimeout": "10s",
          "reentrancy": {
              "enabled": false
          }
      }
  ]
}

停用 actor

通过将 actor 的实例持久化到具有指定 actorId 的状态存储来停用 actor。

HTTP 请求

DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>

HTTP 响应码

代码描述
200请求成功
400Actor 未找到
500请求失败

URL 参数

参数描述
appPort应用程序端口。
actorTypeactor 类型。
actorIdactor ID。

注意，所有 URL 参数都区分大小写。

示例

以下示例停用 actorId 为 50 的 actor 类型 stormtrooper。

curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
  -H "Content-Type: application/json"

调用 actor 方法

使用指定的 methodName 调用 actor 的方法，其中：

  • 方法的参数在请求消息的正文中传递。
  • 返回值在响应消息的正文中提供。

如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/<methodName>

HTTP 响应码

代码描述
200请求成功
500请求失败
404Actor 未找到

URL 参数

参数描述
appPort应用程序端口。
actorTypeactor 类型。
actorIdactor ID。
methodName要调用的方法的名称。

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 performAction 方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
  -H "Content-Type: application/json"

调用提醒

使用指定的 reminderName 为 actor 调用提醒。如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>

HTTP 响应码

代码描述
200请求成功
500请求失败
404Actor 未找到

URL 参数

参数描述
appPort应用程序端口。
actorTypeactor 类型。
actorIdactor ID。
reminderName要调用的提醒的名称。

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 checkRebels 提醒方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
  -H "Content-Type: application/json"

调用定时器

使用指定的 timerName 为 actor 调用定时器。如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>

HTTP 响应码

代码描述
200请求成功
500请求失败
404Actor 未找到

URL 参数

参数描述
appPort应用程序端口。
actorTypeactor 类型。
actorIdactor ID。
timerName要调用的定时器的名称。

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 checkRebels 定时器方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
  -H "Content-Type: application/json"

健康检查

探测应用程序以向 Dapr 发出信号，表明应用程序运行正常。 除 200 以外的任何响应状态码都将被视为不健康的响应。

不需要响应正文。

HTTP 请求

GET http://localhost:<appPort>/healthz

HTTP 响应码

代码描述
200应用程序健康

URL 参数

参数描述
appPort应用程序端口。

示例

从应用程序获取健康检查响应的示例：

curl -X GET http://localhost:3000/healthz \

激活 Actor

从概念上讲，激活 actor 意味着创建 actor 的对象并将 actor 添加到跟踪表中。查看 .NET SDK 中的示例。

外部查询 actor 状态

为了提高 actor 状态的可见性并允许复杂场景（如状态聚合），Dapr 将 actor 状态保存在外部状态存储（如数据库）中。因此，可以通过组合正确的键或查询来外部查询 actor 状态。

Dapr 为 actor 创建的状态命名空间由以下项目组成：

  • 应用程序 ID：分配给 Dapr 应用程序的唯一 ID。
  • Actor 类型：表示 actor 的类型。
  • Actor ID：表示 actor 类型的 actor 实例的唯一 ID。
  • 键：特定状态值的键。Actor ID 可以保存多个状态键。

以下示例显示如何为 myapp 应用程序 ID 命名空间下的 actor 实例的状态构造键：

myapp||cat||hobbit||food

在上面的示例中，我们获取状态键 food 的值，对于 actor ID hobbit 和 actor 类型 cat，在 myapp 应用程序 ID 命名空间下。

2 - Bindings API 参考

绑定 API 的详细文档

Dapr 为应用程序提供双向绑定能力，以及与不同云/本地服务或系统交互的一致方法。 开发者可以使用 Dapr API 调用输出绑定，并让 Dapr 运行时通过输入绑定触发应用程序。

绑定的示例包括 Kafka、Rabbit MQ、Azure Event Hubs、AWS SQS、GCP Storage 等。

Bindings 结构

Dapr Binding yaml 文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.<TYPE>
  version: v1
  metadata:
  - name: <NAME>
    value: <VALUE>

metadata.name 是绑定的名称。

如果在本地自行托管，请将此文件放置在你的 components 文件夹中，与你的状态存储和消息队列 yml 配置放在一起。

如果在 kubernetes 上运行，请将组件应用到集群。

注意： 在生产环境中，切勿将密码或机密信息放置在 Dapr 组件文件中。有关使用状态存储安全存储和检索机密信息的信息，请参阅设置状态存储

绑定方向（可选）

在某些场景中，向 Dapr 提供附加信息以指示绑定组件支持的方向会很有帮助。

提供绑定 direction 可以帮助 Dapr 边车避免 "wait for the app to become ready" 状态，即无限期等待应用程序变为可用。这解耦了 Dapr 边车和应用程序之间的生命周期依赖关系。

你可以在组件的元数据中指定 direction 字段。该字段的有效值为：

  • "input"
  • "output"
  • "input, output"

以下是 "direction" 元数据字段可能有用的几个场景：

  • 当应用程序（与边车分离）作为无服务器工作负载运行并缩放为零时，Dapr 边车执行的 "wait for the app to become ready" 检查变得毫无意义。

  • 如果分离的 Dapr 边车缩放为零，应用程序在边车启动 HTTP 服务器之前就到达边车，"wait for the app to become ready" 会导致应用程序和边车相互等待的死锁。

示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafkaevent
spec:
  type: bindings.kafka
  version: v1
  metadata:
  - name: brokers
    value: "http://localhost:5050"
  - name: topics
    value: "someTopic"
  - name: publishTopic
    value: "someTopic2"
  - name: consumerGroup
    value: "group1"
  - name: "direction"
    value: "input, output"

通过输入绑定调用服务代码

想要使用输入绑定触发其应用程序的开发者可以监听一个 POST http 端点，路由名称与 metadata.name 相同。

启动时，Dapr 向 metadata.name 端点发送 OPTIONS 请求，如果此应用程序想要订阅该绑定，则期望返回不同于 NOT FOUND (404) 的状态码。

metadata 部分是一个开放的键/值元数据对，允许绑定定义连接属性以及组件实现独有的自定义属性。

示例

例如，以下是一个 Python 应用程序如何使用符合 Dapr API 规范的平台订阅来自 Kafka 的事件。请注意，组件中的 metadata.name 值 kafkaevent 如何与 Python 代码中的 POST 路由名称匹配。

Kafka 组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafkaevent
spec:
  type: bindings.kafka
  version: v1
  metadata:
  - name: brokers
    value: "http://localhost:5050"
  - name: topics
    value: "someTopic"
  - name: publishTopic
    value: "someTopic2"
  - name: consumerGroup
    value: "group1"

Python 代码

from flask import Flask
app = Flask(__name__)

@app.route("/kafkaevent", methods=['POST'])
def incoming():
    print("Hello from Kafka!", flush=True)

    return "Kafka Event Processed!"

绑定端点

绑定从组件 yaml 文件中发现。Dapr 在启动时调用此端点以确保应用程序可以处理此调用。如果应用程序没有该端点，Dapr 将忽略它。

HTTP 请求

OPTIONS http://localhost:<appPort>/<name>

HTTP 响应码

代码描述
404应用程序不想绑定到该绑定
2xx 或 405应用程序想要绑定到该绑定

URL 参数

参数描述
appPort应用程序端口
name绑定的名称

注意，所有 URL 参数都区分大小写。

绑定负载

为了传递绑定输入，会使用绑定名称作为 URL 路径向用户代码发出 POST 调用。

HTTP 请求

POST http://localhost:<appPort>/<name>

HTTP 响应码

代码描述
200应用程序成功处理了输入绑定

URL 参数

参数描述
appPort应用程序端口
name绑定的名称

注意，所有 URL 参数都区分大小写。

HTTP 响应主体（可选）

可选地，可以使用响应主体直接将输入绑定与状态存储或输出绑定绑定。

示例： Dapr 将 stateDataToStore 存储到名为 “stateStore” 的状态存储中。 Dapr 并行将 jsonObject 发送到名为 “storage” 和 “queue” 的输出绑定。 如果未设置 concurrency，则按顺序发送（下面的示例显示这些操作是并行完成的）

{
    "storeName": "stateStore",
    "state": stateDataToStore,

    "to": ['storage', 'queue'],
    "concurrency": "parallel",
    "data": jsonObject,
}

调用输出绑定

此端点允许你调用 Dapr 输出绑定。 Dapr 绑定支持各种操作，例如 create。

请参阅每个绑定的不同规范以查看支持的操作列表。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/bindings/<name>

HTTP 响应码

代码描述
200请求成功
204空响应
400格式错误的请求
500请求失败

负载

绑定端点接收以下 JSON 负载：

{
  "data": "",
  "metadata": {
    "": ""
  },
  "operation": ""
}

注意，所有 URL 参数都区分大小写。

data 字段接受任何可 JSON 序列化的值，并充当要发送到输出绑定的负载。 metadata 字段是键/值对数组，允许你为每次调用设置绑定特定的元数据。 operation 字段告诉 Dapr 绑定它应该执行哪个操作。

URL 参数

参数描述
daprPortDapr 端口
name要调用的输出绑定的名称

注意，所有 URL 参数都区分大小写。

示例

curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "key": "redis-key-1"
        },
        "operation": "create"
      }'

常见元数据值

有一些常见的元数据属性在多个绑定组件中受支持。下面的列表说明了它们：

属性描述绑定定义可用于
ttlInSeconds以秒为单位定义消息的存活时间如果在绑定定义中设置，将导致所有消息具有默认的存活时间。消息 ttl 会覆盖绑定定义中的任何值。RabbitMQ, Azure Service Bus, Azure Storage Queue

3 - Configuration API 参考

配置 API 的详细文档

获取配置

此端点允许您从存储中获取配置。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/configuration/<storename>

URL 参数

参数描述
daprPortDapr 端口
storename组件文件中的 metadata.name 字段。参考 组件规范

查询参数

如果未提供查询参数，则返回所有配置项。 要指定要获取的配置项的键，请使用一个或多个 key 查询参数。例如：

GET http://localhost:<daprPort>/v1.0/configuration/mystore?key=config1&key=config2

要检索所有配置项：

GET http://localhost:<daprPort>/v1.0/configuration/mystore

请求体

无

HTTP 响应

响应代码

代码描述
204获取操作成功
400配置存储缺失或配置错误或请求格式错误
500获取配置失败

响应体

每个配置项的键/值对的 JSON 编码值。

示例

curl -X GET 'http://localhost:3500/v1.0/configuration/mystore?key=myConfigKey'

上述命令返回以下 JSON：

{
    "myConfigKey": {
        "value":"myConfigValue"
    }
}

订阅配置

此端点允许您订阅配置更改。当配置存储中的值被更新或删除时，会发送通知。这使应用程序能够对配置更改做出反应。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/configuration/<storename>/subscribe

URL 参数

参数描述
daprPortDapr 端口
storename组件文件中的 metadata.name 字段。参考 组件规范

查询参数

如果未提供查询参数，则订阅所有配置项。 要指定要订阅的配置项的键，请使用一个或多个 key 查询参数。例如：

GET http://localhost:<daprPort>/v1.0/configuration/mystore/subscribe?key=config1&key=config2

要订阅所有更改：

GET http://localhost:<daprPort>/v1.0/configuration/mystore/subscribe

请求体

无

HTTP 响应

响应代码

代码描述
200订阅操作成功
400配置存储缺失或配置错误或请求格式错误
500订阅配置更改失败

响应体

JSON 编码值

示例

curl -X GET 'http://localhost:3500/v1.0/configuration/mystore/subscribe?key=myConfigKey'

上述命令返回以下 JSON：

{
  "id": "<unique-id>"
}

返回的 id 参数可用于取消订阅订阅 API 调用中提供的特定键集。应用程序应保留此值。

取消订阅配置

此端点允许您取消订阅配置更改。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/configuration/<storename>/<subscription-id>/unsubscribe

URL 参数

参数描述
daprPortDapr 端口
storename组件文件中的 metadata.name 字段。参考 组件规范
subscription-id订阅端点响应中返回的 id 字段的值

查询参数

无

请求体

无

HTTP 响应

响应代码

代码描述
200取消订阅操作成功
400配置存储缺失或配置错误或请求格式错误
500取消订阅配置更改失败

响应体

{
    "ok" : true
}

示例

curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore/bf3aa454-312d-403c-af95-6dec65058fa2/unsubscribe'

上述命令返回以下 JSON：

操作成功时：

{
  "ok": true
}

操作失败时：

{
  "ok": false,
  "message": "<dapr 返回的错误消息>"
}

可选的应用程序（用户代码）路由

提供一个路由供 Dapr 发送配置更改

订阅配置更改后，每当配置项更改时，Dapr 会调用应用程序。您的应用程序可以有一个 /configuration 端点，该端点会为所有订阅的键更新调用。可以通过添加 /<store-name> 使端点更具体地针对给定的配置存储，并通过向路由添加 /<store-name>/<key> 使其针对特定键。

HTTP 请求

POST http://localhost:<appPort>/configuration/<store-name>/<key>

URL 参数

参数描述
appPort应用程序端口
storename组件文件中的 metadata.name 字段。参考 组件规范
key订阅的键

请求体

给定订阅 ID 的配置项列表。配置项可以具有与之关联的版本，该版本在通知中返回。

{
    "id": "<subscription-id>",
    "items": [
        "key": "<key-of-configuration-item>",
        "value": "<new-value>",
        "version": "<version-of-item>"
    ]
}

示例

{
    "id": "bf3aa454-312d-403c-af95-6dec65058fa2",
    "items": [
        "key": "config-1",
        "value": "abcdefgh",
        "version": "1.1"
    ]
}

后续步骤

4 - Conversation API 参考

Conversation API 的详细文档

Dapr 提供了一个与大型语言模型（LLM）交互的 API，并通过提示缓存、PII 数据混淆和工具调用等功能实现关键的性能和安全特性。

工具调用遵循 OpenAI 的函数调用格式，便于与现有的 AI 开发工作流和工具集成。

Converse

此端点允许您使用 Alpha2 版本的 API 与 LLM 进行对话，该版本提供了增强的工具调用支持，并与 OpenAI 的接口保持一致。

POST http://localhost:<daprPort>/v1.0-alpha2/conversation/<llm-name>/converse

URL 参数

参数描述
llm-nameLLM 组件的名称。查看所有可用的对话组件列表。

请求体

字段描述
contextId现有聊天的 ID（类似 ChatGPT）。可选
inputs对话的输入。支持同时传入多个输入。必填
parameters所有自定义字段的参数。可选
metadata传递给对话组件的元数据。可选
scrubPii布尔值，用于启用对从 LLM 返回的敏感信息进行混淆。可选
temperature浮点值，用于控制模型的温度。用于优化一致性（0）或创造性（1）。可选
tools工具注册了 LLM 在对话期间可以使用的工具。可选
toolChoice控制模型调用哪个工具（如果有）。值：auto、required 或特定工具名称。如果存在工具，默认为 auto。可选
responseFormat使用 JSON Schema 对象描述的结构化输出。当您需要类型化的结构化输出时使用。由 Deepseek、Google AI、Hugging Face、OpenAI 和 Anthropic 组件支持。可选
promptCacheRetention提示缓存的保留时长。设置后，启用扩展的提示缓存，使缓存的前缀保持更长时间。在 OpenAI 上，支持最长 24 小时。参见 OpenAI 提示缓存。可选

输入体

字段描述
messages对话消息数组。必填
scrubPii布尔值，用于启用对内容字段中存在的敏感信息进行混淆。可选

消息类型

API 支持不同的消息类型：

类型描述
ofDeveloper开发者角色消息，带有可选的名称和内容
ofSystem系统角色消息，带有可选的名称和内容
ofUser用户角色消息，带有可选的名称和内容
ofAssistant助手角色消息，带有可选的名称、内容和工具调用
ofTool工具角色消息，带有工具 ID、名称和内容

工具调用

可以使用 tools 字段定义工具，其中包含函数定义：

字段描述
function.name要调用的函数名称。必填
function.description函数功能的描述。可选
function.parameters描述函数参数的 JSON Schema 对象。可选

工具选择选项

toolChoice 是一个可选参数，用于控制模型如何使用可用工具：

  • auto: 模型可以在生成消息或调用一个或多个工具之间选择（存在工具时的默认值）
  • required: 要求调用一个或多个函数
  • {tool_name}: 强制模型按名称调用特定工具

元数据

metadata 字段作为一种动态配置机制，允许您在每次请求的基础上将额外的配置和身份验证信息传递给对话组件。此元数据会覆盖组件 YAML 配置文件中配置的相应字段，从而在不修改静态组件定义的情况下实现动态配置。

常见元数据字段：

字段描述示例
api_key用于与 LLM 服务进行身份验证的 API 密钥"sk-1234567890abcdef"
model特定模型标识符"gpt-4-turbo", "claude-3-sonnet"
versionAPI 版本或服务版本"1.0", "2023-12-01"
endpoint服务的自定义端点 URL"https://api.custom-llm.com/v1"

除了在请求体中传递元数据外，您还可以将元数据作为 URL 查询参数传递，而无需修改请求负载。格式如下：

  • 前缀：所有元数据参数必须以 metadata. 为前缀
  • 格式：?metadata.<field_name>=<value>
  • 多个参数：使用 & 分隔（例如 ?metadata.api_key=sk-123&metadata.model=gpt-4）

模型覆盖示例：

POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse?metadata.model=sk-gpt-4-turbo

URL 元数据参数与请求体元数据合并，如果存在冲突，URL 参数优先，并且两者都会覆盖 YAML 文件中的组件配置。

请求内容示例

基本对话

curl -X POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "messages": [
              {
                "ofUser": {
                  "content": [
                    {
                      "text": "What is Dapr?"
                    }
                  ]
                }
              }
            ]
          }
        ],
        "parameters": {},
        "metadata": {}
      }'

带工具调用的对话

curl -X POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "messages": [
              {
                "ofUser": {
                  "content": [
                    {
                      "text": "What is the weather like in San Francisco in celsius?"
                    }
                  ]
                }
              }
            ],
            "scrubPii": false
          }
        ],
        "parameters": {
          "max_tokens": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "100"
          },
          "model": {
            "@type": "type.googleapis.com/google.protobuf.StringValue",
            "value": "claude-3-5-sonnet-20240620"
          }
        },
        "metadata": {
          "api_key": "test-key",
          "version": "1.0"
        },
        "scrubPii": false,
        "temperature": 0.7,
        "tools": [
          {
            "function": {
              "name": "get_weather",
              "description": "Get the current weather for a location",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                  },
                  "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The temperature unit to use"
                  }
                },
                "required": ["location"]
              }
            }
          }
        ],
        "toolChoice": "auto"
      }'

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500请求格式正确，Dapr 代码或底层组件出错

弹性和超时

对话组件调用使用 Dapr 的弹性策略。您可以在 targets/components/<component-name>/outbound 下按组件名称定位对话组件，并附加超时、重试和断路器策略。

  • 超时：超时应用于请求上下文。该上下文会传递给对话组件（进而传递给边车中的 LLM 提供商）。如果 LLM 在配置的持续时间内未响应，上下文将被取消，请求将以错误终止。设置一个考虑典型 LLM 响应时间的超时。
  • 重试和断路器：这些适用于整个 Converse 调用。重试会在失败时重新运行整个对话调用（例如，超时或网络错误后）。断路器在打开时会跳过调用组件并立即返回错误。这些不会作为配置传递给 LLM。

响应内容

outputs 中的每一项可以包含：

字段描述
choices完成选项。
model用于对话的模型。可选
usage请求的 token 使用指标。可选

使用指标

当存在时，usage 包含：

字段描述
promptTokens提示中的 token 数量。
completionTokens生成的完成中的 token 数量。
totalTokens使用的总 token 数（提示 + 完成）。
promptTokensDetails可选。可以包含 audioTokens（提示中的音频输入 token）和 cachedTokens（从提示缓存中提供的 token）。
completionTokensDetails可选。可以包含 reasoningTokens、acceptedPredictionTokens、rejectedPredictionTokens、audioTokens。

基本对话响应

{
  "outputs": [
    {
      "choices": [
        {
          "finishReason": "stop",
          "message": {
            "content": "Distributed application runtime, open-source."
          }
        }
      ],
      "model": "gpt-4o",
      "usage": {
        "promptTokens": 12,
        "completionTokens": 8,
        "totalTokens": 20,
        "promptTokensDetails": {
          "audioTokens": 0,
          "cachedTokens": 0
        },
        "completionTokensDetails": {
          "acceptedPredictionTokens": 0,
          "audioTokens": 0,
          "reasoningTokens": 0,
          "rejectedPredictionTokens": 0
        }
      }
    }
  ]
}

工具调用响应

{
  "outputs": [
    {
      "choices": [
        {
          "finishReason": "tool_calls",
          "message": {
            "toolCalls": [
              {
                "id": "call_Uwa41pG0UqGA2zp0Fec0KwOq",
                "function": {
                  "name": "get_weather",
                  "arguments": "{\"location\":\"San Francisco, CA\",\"unit\":\"celsius\"}"
                }
              }
            ]
          }
        }
      ],
      "model": "gpt-4o",
      "usage": {
        "promptTokens": 25,
        "completionTokens": 18,
        "totalTokens": 43,
        "promptTokensDetails": {
          "audioTokens": 0,
          "cachedTokens": 0
        },
        "completionTokensDetails": {
          "acceptedPredictionTokens": 0,
          "audioTokens": 0,
          "reasoningTokens": 0,
          "rejectedPredictionTokens": 0
        }
      }
    }
  ]
}

旧版 Alpha1 API

之前的 Alpha1 版本 API 为了向后兼容仍然受到支持，但已被弃用。对于新的实现，请使用上面描述的 Alpha2 版本。

POST http://localhost:<daprPort>/v1.0-alpha2/conversation/<llm-name>/converse

后续步骤

5 - 加密 API 参考

加密 API 的详细文档

Dapr 通过加密构建块为加密和解密功能提供跨平台和跨语言支持。除了特定语言的 SDK，开发者还可以使用以下 HTTP API 端点调用这些功能。

HTTP API 仅适用于开发和测试场景。在生产场景中，强烈建议使用 SDK，因为它们实现了 gRPC API，相比 HTTP API 提供更高的性能和更强的功能。

加密负载

此端点允许您使用指定的密钥和加密组件加密以字节数组形式提供的值。

HTTP 请求

PUT http://localhost:<daprPort>/v1.0-alpha1/crypto/<crypto-store-name>/encrypt

URL 参数

参数描述
daprPortDapr 端口
crypto-store-name用于获取加密密钥的加密存储名称

注意，所有 URL 参数都区分大小写。

请求头

通过设置具有适当值的请求头来配置额外的加密参数。下表详述了每个加密请求需要设置的必选和可选请求头。

请求头键描述允许的值必填
dapr-key-name用于加密操作的密钥名称是
dapr-key-wrap-algorithm要使用的密钥包装算法A256KW、A128CBC、A192CBC、RSA-OAEP-256是
dapr-omit-decryption-key-name如果为 true，则从输出中省略请求头 dapr-decryption-key-name 中的解密密钥名称。如果为 false，则包含请求头 dapr-decryption-key-name 中指定的解密密钥名称。以下值将被视为 true：y、yes、true、t、on、1否
dapr-decryption-key-name如果 dapr-omit-decryption-key-name 为 true，则此字段包含要包含在输出中的预期解密密钥的名称。仅当 dapr-omit-decryption-key-name 为 true 时必填
dapr-data-encryption-cipher用于加密操作的密码aes-gcm 或 chacha20-poly1305否

HTTP 响应

响应体

加密请求的响应的内容类型请求头将被设置为 application/octet-stream，因为它返回包含加密负载的字节数组。

响应代码

代码描述
200OK
400未找到加密提供程序
500请求格式正确，但在 dapr 代码或底层组件中发生错误

示例

curl http://localhost:3500/v1.0-alpha1/crypto/myAzureKeyVault/encrypt \
    -X PUT \
    -H "dapr-key-name: myCryptoKey" \
    -H "dapr-key-wrap-algorithm: aes-gcm" \ 
    -H "Content-Type: application/octet-string" \ 
    --data-binary "\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64"

以上命令发送表示 “hello world” 的 UTF-8 编码字节数组，并将返回类似于以下包含加密负载的 8 位值流：

gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A==

解密负载

此端点允许您使用指定的密钥和加密组件解密以字节数组形式提供的值。

HTTP 请求

PUT curl http://localhost:3500/v1.0-alpha1/crypto/<crypto-store-name>/decrypt

URL 参数

参数描述
daprPortDapr 端口
crypto-store-name用于获取解密密钥的加密存储名称

注意，所有参数都区分大小写。

请求头

通过设置具有适当值的请求头来配置额外的解密参数。下表详述了每个解密请求需要设置的必选和可选请求头。

请求头键描述必填
dapr-key-name用于解密操作的密钥名称。是

HTTP 响应

响应体

解密请求的响应的内容类型请求头将被设置为 application/octet-stream，因为它返回表示解密负载的字节数组。

响应代码

代码描述
200OK
400未找到加密提供程序
500请求格式正确，但在 dapr 代码或底层组件中发生错误

示例

curl http://localhost:3500/v1.0-alpha1/crypto/myAzureKeyVault/decrypt \
    -X PUT
    -H "dapr-key-name: myCryptoKey"\
    -H "Content-Type: application/octet-stream" \
    --data-binary "gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A=="

以上命令发送加密消息负载的 base-64 编码字符串，并将返回内容类型请求头设置为 application/octet-stream 的响应，响应体为 hello world。

hello world

6 - 分布式锁 API 参考

分布式锁 API 详细文档

加锁

此端点允许您通过提供指定的锁所有者和要锁定的资源 ID 来获取锁。

HTTP 请求

POST http://localhost:<daprPort>/v1.0-alpha1/lock/<storename>

URL 参数

参数描述
daprPortDapr 端口
storename组件文件中的 metadata.name 字段。请参阅组件 schema

查询参数

无

HTTP 响应码

代码描述
200请求成功
204空响应
400请求格式错误
500请求失败

HTTP 请求体

加锁端点接收以下 JSON 负载：

{
    "resourceId": "",
    "lockOwner": "",
    "expiryInSeconds": 0
}
字段描述
resourceId要锁定的资源 ID。可以是任何值
lockOwner锁所有者的名称。应针对每个请求设置为唯一值
expiryInSeconds锁在过期前持有的时间（秒）

HTTP 响应体

加锁端点返回以下负载：

{
    "success": true
}

示例

curl -X POST http://localhost:3500/v1.0-alpha/lock/redisStore \
  -H "Content-Type: application/json" \
  -d '{
        "resourceId": "lock1",
        "lockOwner": "vader",
        "expiryInSeconds": 60
      }'

{
    "success": "true"
}

解锁

此端点允许您根据锁所有者和资源 ID 解除现有的锁。

HTTP 请求

POST http://localhost:<daprPort>/v1.0-alpha1/unlock/<storename>

URL 参数

参数描述
daprPortDapr 端口
storename组件文件中的 metadata.name 字段。请参阅组件 schema

查询参数

无

HTTP 响应码

代码描述
200请求成功
204空响应
400请求格式错误
500请求失败

HTTP 请求体

解锁端点接收以下 JSON 负载：

{
    "resourceId": "",
    "lockOwner": ""
}

HTTP 响应体

解锁端点返回以下负载：

{
    "status": 0
}

status 字段包含以下响应代码：

代码描述
0成功
1锁不存在
2锁属于其他所有者
3内部错误

示例

curl -X POST http://localhost:3500/v1.0-alpha/unlock/redisStore \
  -H "Content-Type: application/json" \
  -d '{
        "resourceId": "lock1",
        "lockOwner": "vader"
      }'

{
    "status": 0
}

7 - Health API 参考

Health API 的详细文档

Dapr 提供了可用于 Dapr 就绪或存活检测以及 SDK 初始化就绪的健康检查探针。

获取 Dapr 健康状态

通过以下方式获取 Dapr 的健康状态：

  • 检查边车健康状态
  • 检查边车健康状态，包括组件就绪状态，用于初始化期间。

等待 Dapr HTTP 端口变为可用

等待所有组件初始化完成，Dapr HTTP 端口可用_并且_应用通道已初始化。例如，此端点与 Kubernetes 存活探针一起使用。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/healthz

HTTP 响应代码

代码描述
204Dapr 健康
500Dapr 不健康

URL 参数

参数描述
daprPortDapr 端口

示例

curl -i http://localhost:3500/v1.0/healthz

等待针对 /outbound 路径的特定健康检查

等待所有组件初始化完成，Dapr HTTP 端口可用，但应用通道尚未建立。此端点使您的应用能够在应用通道初始化之前对 Dapr 边车 API 执行调用，例如使用 secrets API 读取机密。例如，在 Dapr SDK 的 waitForSidecar 方法中使用（例如 .NET 和 Java SDK）来检查边车是否已正确初始化并准备好接受任何调用。

例如，Java SDK 和 .NET SDK 使用此端点进行初始化。

目前，.NET SDK、Java SDK、Python SDK 和 JavaScript SDK 中支持 v1.0/healthz/outbound 端点。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/healthz/outbound

HTTP 响应代码

代码描述
204Dapr 健康
500Dapr 不健康

URL 参数

参数描述
daprPortDapr 端口

示例

curl -i http://localhost:3500/v1.0/healthz/outbound

相关文章

8 - Jobs API 参考

Jobs API 的详细文档

使用 jobs API，您可以在将来安排作业和任务。

HTTP API 仅用于开发和测试。对于生产场景，强烈建议使用 SDK，因为它们实现了 gRPC API，提供了比 HTTP API 更高的性能和功能。这是因为 HTTP 进行 JSON 序列化可能会很昂贵，而使用 gRPC，数据按原样传输和存储，性能更高。

调度作业

使用名称调度作业。作业基于运行 Scheduler 服务的服务器时钟进行调度。时间戳不会转换为 UTC。您可以在 RFC3339 格式的时间戳中提供时区，以指定作业应遵循的时区。如果未提供时区，则使用服务器的本地时间。

POST http://localhost:<daprPort>/v1.0-alpha1/jobs/<name>

URL 参数

参数描述
name您正在调度的作业的名称
dataJSON 序列化值或对象。
schedule作业运行的可选调度。格式详情见下文。
dueTime作业应激活的可选时间，或在未提供其他调度类型字段时的"一次性"时间。接受 RFC3339 格式的"时间点"字符串、Go duration 字符串（从创建时间计算）或非重复的 ISO8601 格式。
repeats作业应触发的可选次数。如果未设置，作业将无限期运行或直到过期。
ttl作业的可选生存时间或过期时间。接受 RFC3339 格式的"时间点"字符串、Go duration 字符串（从作业创建时间计算）或非重复的 ISO8601 格式。
overwrite一个布尔值，指定作业是否可以覆盖同名的现有作业。默认值为 false
failure_policy作业的可选失败策略。格式详情见下文。如果未设置，作业将重试最多 3 次，重试之间延迟 1 秒。

schedule

schedule 接受 systemd timer 风格的 cron 表达式以及人类可读的"@“前缀周期字符串，定义如下。

Systemd timer 风格的 cron 接受 6 个字段：

秒分钟小时日（月）月日（周）
0-590-590-231-311-12/jan-dec0-6/sun-sat
示例 1

“0 30 * * * *” - 每小时的半小时时

示例 2

“0 15 3 * * *” - 每天 03:15

周期字符串表达式：

条目描述等效于
@every 每 运行一次（例如 ‘@every 1h30m’）N/A
@yearly（或 @annually）每年运行一次，1 月 1 日午夜0 0 0 1 1 *
@monthly每月运行一次，月初午夜0 0 0 1 * *
@weekly每周运行一次，周日午夜0 0 0 * * 0
@daily（或 @midnight）每天运行一次，午夜0 0 0 * * *
@hourly每小时运行一次，小时开始0 0 * * * *

failure_policy

failure_policy 指定作业应如何处理失败。

它可以设置为 constant 或 drop。

  • constant 策略使用以下配置选项持续重试作业。
    • max_retries 配置作业应重试的次数。默认为无限重试。nil 表示无限重试，而 0 表示不会重试请求。
    • interval 配置重试之间的延迟。默认为立即重试。有效值的形式为 200ms、15s、2m 等。
  • drop 策略在第一次失败后丢弃作业，不进行重试。
示例 1
{
  //...
  "failure_policy": {
    "constant": {
      "max_retries": 3,
      "interval": "10s"
    }
  }
}
示例 2
{
  //...
  "failure_policy": {
    "drop": {}
  }
}

请求体

{
  "data": "some data",
  "dueTime": "30s"
}

HTTP 响应代码

代码描述
204已接受
400请求格式错误
500请求格式正确，但 dapr 代码或 Scheduler 控制平面服务中出现错误

响应内容

以下示例 curl 命令创建一个作业，将作业命名为 jobforjabba 并指定 schedule、repeats 和 data。

$ curl -X POST \
  http://localhost:3500/v1.0-alpha1/jobs/jobforjabba \
  -H "Content-Type: application/json" \
  -d '{
        "data": "{\"value\":\"Running spice\"}",
        "schedule": "@every 1m",
        "repeats": 5
    }'

获取作业数据

根据名称获取作业。

GET http://localhost:<daprPort>/v1.0-alpha1/jobs/<name>

URL 参数

参数描述
name您正在检索的已调度作业的名称

HTTP 响应代码

代码描述
200已接受
400请求格式错误
500请求格式正确，作业不存在或 dapr 代码或 Scheduler 控制平面服务中出现错误

响应内容

运行以下示例 curl 命令后，返回的响应是包含作业的 name、dueTime 和 data 的 JSON。

$ curl -X GET http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json"

{
  "name": "jobforjabba",
  "schedule": "@every 1m",
  "repeats": 5,
  "data": 123
}

删除作业

删除命名作业。

DELETE http://localhost:<daprPort>/v1.0-alpha1/jobs/<name>

URL 参数

参数描述
name您正在删除的作业的名称

HTTP 响应代码

代码描述
204已接受
400请求格式错误
500请求格式正确，但 dapr 代码或 Scheduler 控制平面服务中出现错误

响应内容

在以下示例 curl 命令中，将删除名为 test1 且 app-id 为 sub 的作业

$ curl -X DELETE http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json"

后续步骤

Jobs API 概述

9 - Metadata API 参考

Metadata API 的详细文档

Dapr 有一个元数据 API，返回关于边车的信息，允许运行时可发现性。元数据端点返回以下信息。

  • 运行时版本
  • 已加载资源列表（components、subscriptions 和 HttpEndpoints）
  • 注册的 actor 类型
  • 启用的功能
  • 应用程序连接详情
  • 包含信息的自定义临时属性。

Metadata API

组件

每个已加载的组件提供其名称、类型和版本，以及关于组件功能形式的支持功能信息。 这些功能可用于状态存储和绑定组件类型。下表显示了给定版本的组件类型及其功能列表。此列表可能会在未来增长，仅代表已加载组件的功能。

组件类型功能
状态存储ETAG, TRANSACTION, ACTOR, QUERY_API
绑定INPUT_BINDING, OUTPUT_BINDING

HTTPEndpoints

每个已加载的 HttpEndpoint 提供一个名称，以轻松识别与运行时关联的 Dapr 资源。

订阅

元数据 API 返回应用程序已向 Dapr 运行时注册的发布订阅订阅列表。这包括发布订阅名称、主题、路由、死信主题、订阅类型以及与订阅关联的元数据。

启用的功能

通过 Configuration 规范启用的功能列表（包括构建时覆盖）。

应用连接详情

元数据 API 返回与 Dapr 到应用程序的连接相关的信息。这包括应用端口、协议、主机、最大并发数以及健康检查详情。

Scheduler 连接详情

与到一个或多个 scheduler 主机的连接相关的信息。

工作流 API 运行时详情

与工作流 API 运行时详情相关的信息。

属性

元数据 API 允许您以键值对的格式存储额外的属性信息。这些是临时的内存中的数据，如果边车重新加载则不会持久化。此信息应在边车创建时添加（例如，应用程序启动后）。

获取 Dapr 边车信息

获取由元数据端点提供的 Dapr 边车信息。

用例：

获取元数据 API 可用于发现已加载组件支持的不同功能。它可以帮助运维人员确定要为所需功能配置哪些组件。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/metadata

URL 参数

参数描述
daprPortDapr 端口。

HTTP 响应代码

代码描述
200返回元数据信息
500Dapr 无法返回元数据信息

HTTP 响应正文

元数据 API 响应对象

名称类型描述
idstring应用程序 ID
runtimeVersionstringDapr 运行时版本
enabledFeaturesstring[]由 Dapr 配置启用的功能列表，请参阅 https://docs.dapr.io/operations/configuration/preview-features/
actors元数据 API 响应注册 Actor[]注册的 actor 元数据的 json 编码数组。
extended.attributeNamestring自定义属性列表，以键值对形式，其中键是属性名称。
components元数据 API 响应组件[]已加载组件元数据的 json 编码数组。
httpEndpoints元数据 API 响应 HttpEndpoint[]已加载 HttpEndpoints 元数据的 json 编码数组。
subscriptions元数据 API 响应订阅[]发布订阅订阅元数据的 json 编码数组。
appConnectionProperties元数据 API 响应应用连接属性应用连接属性的 json 编码对象。
scheduler元数据 API 响应调度器调度器连接属性的 json 编码对象。
workflows元数据 API 响应工作流工作流运行时属性的 json 编码对象

元数据 API 响应注册 Actor

名称类型描述
typestring注册的 actor 类型。
countinteger运行中的 actor 数量。

元数据 API 响应组件

名称类型描述
namestring组件名称。
typestring组件类型。
versionstring组件版本。
capabilitiesarray此组件类型和版本支持的功能。

元数据 API 响应 HttpEndpoint

名称类型描述
namestringHttpEndpoint 的名称。

元数据 API 响应订阅

名称类型描述
pubsubnamestring发布订阅的名称。
topicstring主题名称。
metadataobject与订阅关联的元数据。
rules元数据 API 响应订阅规则[]与订阅关联的规则列表。
deadLetterTopicstring死信主题名称。
typestring订阅类型，可以是 DECLARATIVE、STREAMING 或 PROGRAMMATIC。

元数据 API 响应订阅规则

名称类型描述
matchstring用于匹配消息的 CEL 表达式，请参阅 https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-route-messages/#common-expression-language-cel
pathstring如果匹配表达式为 true，则路由消息的路径。

元数据 API 响应应用连接属性

名称类型描述
portinteger应用程序正在侦听的端口。
protocolstring应用程序使用的协议。
channelAddressstring应用程序正在侦听的主机地址。
maxConcurrencyinteger应用程序可以处理的最大并发请求数。
health元数据 API 响应应用连接属性健康检查应用程序的健康检查详情。

元数据 API 响应应用连接属性健康检查

名称类型描述
healthCheckPathstring健康检查路径，适用于 HTTP 协议。
healthProbeIntervalstring每次健康探测之间的时间，以 go duration 格式。
healthProbeTimeoutstring每次健康探测的超时时间，以 go duration 格式。
healthThresholdinteger在应用程序被视为不健康之前的最大失败健康探测次数。

元数据 API 响应调度器

名称类型描述
connected_addressesstring[]表示已连接的调度器主机的地址的字符串列表。

元数据 API 响应工作流

名称类型描述
connectedWorkersinteger已连接的工作流工作者的数量。

示例

curl http://localhost:3500/v1.0/metadata

{
  "id": "myApp",
  "runtimeVersion": "1.12.0",
  "enabledFeatures": [
    "ServiceInvocationStreaming"
  ],
  "actors": [
    {
      "type": "DemoActor"
    }
  ],
  "components": [
    {
      "name": "pubsub",
      "type": "pubsub.redis",
      "version": "v1"
    },
    {
      "name": "statestore",
      "type": "state.redis",
      "version": "v1",
      "capabilities": [
        "ETAG",
        "TRANSACTIONAL",
        "ACTOR"
      ]
    }
  ],
  "httpEndpoints": [
    {
      "name": "my-backend-api"
    }
  ],
  "subscriptions": [
    {
      "type": "DECLARATIVE",
      "pubsubname": "pubsub",
      "topic": "orders",
      "deadLetterTopic": "",
      "metadata": {
        "ttlInSeconds": "30"
      },
      "rules": [
          {
              "match": "%!s(<nil>)",
              "path": "orders"
          }
      ]
    }
  ],
  "extended": {
    "appCommand": "uvicorn --port 3000 demo_actor_service:app",
    "appPID": "98121",
    "cliPID": "98114",
    "daprRuntimeVersion": "1.12.0"
  },
  "appConnectionProperties": {
    "port": 3000,
    "protocol": "http",
    "channelAddress": "127.0.0.1",
    "health": {
      "healthProbeInterval": "5s",
      "healthProbeTimeout": "500ms",
      "healthThreshold": 3
    }
  },
  "scheduler": {
    "connected_addresses": [
      "10.244.0.47:50006",
      "10.244.0.48:50006",
      "10.244.0.49:50006"
    ]
  },
  "workflows": {
    "connectedWorkers": 1
  }
}

向 Dapr 边车信息添加自定义标签

向由元数据端点存储的 Dapr 边车信息添加自定义标签。

用例：

例如，Dapr CLI 在自托管模式下运行 dapr 时使用元数据端点来存储托管边车的进程的 PID 以及用于运行应用程序的命令。应用程序也可以在启动后添加属性作为键。

HTTP 请求

PUT http://localhost:<daprPort>/v1.0/metadata/attributeName

URL 参数

参数描述
daprPortDapr 端口。
attributeName自定义属性名称。这是键值对中的键名称。

HTTP 请求正文

在请求中，您需要将自定义属性值作为 RAW 数据传递：

{
  "Content-Type": "text/plain"
}

在请求的正文中放置您要存储的自定义属性值：

attributeValue

HTTP 响应代码

代码描述
204自定义属性已添加到元数据信息

示例

向元数据端点添加自定义属性：

curl -X PUT -H "Content-Type: text/plain" --data "myDemoAttributeValue" http://localhost:3500/v1.0/metadata/myDemoAttribute

获取元数据信息以确认您的自定义属性已添加：

{
  "id": "myApp",
  "runtimeVersion": "1.12.0",
  "enabledFeatures": [
    "ServiceInvocationStreaming"
  ],
  "actors": [
    {
      "type": "DemoActor"
    }
  ],
  "components": [
    {
      "name": "pubsub",
      "type": "pubsub.redis",
      "version": "v1"
    },
    {
      "name": "statestore",
      "type": "state.redis",
      "version": "v1",
      "capabilities": [
        "ETAG",
        "TRANSACTIONAL",
        "ACTOR"
      ]
    }
  ],
  "httpEndpoints": [
    {
      "name": "my-backend-api"
    }
  ],
  "subscriptions": [
    {
      "type": "PROGRAMMATIC",
      "pubsubname": "pubsub",
      "topic": "orders",
      "deadLetterTopic": "",
      "metadata": {
        "ttlInSeconds": "30"
      },
      "rules": [
          {
              "match": "%!s(<nil>)",
              "path": "orders"
          }
      ]
    }
  ],
  "extended": {
    "myDemoAttribute": "myDemoAttributeValue",
    "appCommand": "uvicorn --port 3000 demo_actor_service:app",
    "appPID": "98121",
    "cliPID": "98114",
    "daprRuntimeVersion": "1.12.0"
  },
  "appConnectionProperties": {
    "port": 3000,
    "protocol": "http",
    "channelAddress": "127.0.0.1",
    "health": {
      "healthProbeInterval": "5s",
      "healthProbeTimeout": "500ms",
      "healthThreshold": 3
    }
  },
  "scheduler": {
    "connected_addresses": [
      "10.244.0.47:50006",
      "10.244.0.48:50006",
      "10.244.0.49:50006"
    ]
  },
  "workflows": {
    "connectedWorkers": 1
  }
}

10 - Placement API 参考

Placement API 的详细文档

Dapr 为 Placement 服务提供了一个 HTTP API /placement/state，用于暴露 placement 表信息。该 API 在边车的 healthz 相同端口上暴露。这是一个未经身份验证的端点，默认情况下处于禁用状态。

若要在自承载模式下启用 placement 元数据，您可以在 Placement 服务上将 DAPR_PLACEMENT_METADATA_ENABLED 环境变量或 metadata-enabled 命令行参数设置为 true。参见如何在自承载模式下运行 Placement 服务。

如果您使用 Helm 在 Kubernetes 上部署 Placement 服务，若要启用 placement 元数据，请将 dapr_placement.metadataEnabled 设置为 true。

用例

placement 表 API 可用于获取当前的 placement 表，其中包含所有已注册的 actor。这对于调试很有帮助，并允许工具提取和展示有关 actor 的信息。

HTTP 请求

GET http://localhost:<healthzPort>/placement/state

HTTP 响应代码

代码描述
200返回 placement 表信息
500Placement 无法返回 placement 表信息

HTTP 响应体

Placement 表 API 响应对象

名称类型描述
tableVersionintplacement 表版本
hostListActor Host Info[]已注册 actor 主机信息的 json 数组。

Actor 主机信息

名称类型描述
namestringactor 的 host:port 地址。
appIdstringapp id。
actorTypesjson 字符串数组其托管的 actor 类型列表。
updatedAttimestampactor 注册/更新的时间戳。

示例

 curl localhost:8080/placement/state

{
    "hostList": [{
            "name": "198.18.0.1:49347",
            "namespace": "ns1",
            "appId": "actor1",
            "actorTypes": ["testActorType1", "testActorType3"],
            "updatedAt": 1690274322325260000
        },
        {
            "name": "198.18.0.2:49347",
            "namespace": "ns2",
            "appId": "actor2",
            "actorTypes": ["testActorType2"],
            "updatedAt": 1690274322325260000
        },
        {
            "name": "198.18.0.3:49347",
            "namespace": "ns2",
            "appId": "actor2",
            "actorTypes": ["testActorType2"],
            "updatedAt": 1690274322325260000
        }
    ],
    "tableVersion": 1
}

11 - 发布订阅 API 参考

发布订阅 API 的详细文档

向指定主题发布消息

此端点允许您向正在监听 topic 的多个消费者发布数据。 Dapr 保证此端点至少一次（At-Least-Once）语义。

HTTP 请求

POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP 响应码

代码描述
204消息已投递
403消息被访问控制拒绝
404未提供 pubsub 名称或主题
500投递失败

URL 参数

参数描述
daprPortDapr 端口
pubsubname发布订阅组件的名称
topic主题的名称
metadata元数据的查询参数，如下所述

注意，所有 URL 参数区分大小写。

curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
  -H "Content-Type: application/json" \
 -d '{
       "status": "completed"
     }'

请求头

Content-Type 请求头告诉 Dapr 在构造 CloudEvent 信封时您的数据遵循的内容类型。Content-Type 请求头值会填充 CloudEvent 中的 datacontenttype 字段。

除非另有说明，Dapr 假定为 text/plain。如果您的 content type 是 JSON，请使用值为 application/json 的 Content-Type 请求头。

如果要发送自己的自定义 CloudEvent，请为 Content-Type 请求头使用 application/cloudevents+json 值。

元数据

元数据可以通过请求 URL 中的查询参数发送。必须以 metadata. 为前缀，如下所示。

参数描述
metadata.ttlInSeconds消息过期的秒数，如此处所述
metadata.rawPayload布尔值，确定 Dapr 是否应在不将其包装为 CloudEvent 的情况下发布事件，如此处所述

根据每个发布订阅组件，可提供其他元数据参数。

向指定主题发布多条消息

此端点允许您向正在监听 topic 的消费者发布多条消息。

HTTP 请求

POST http://localhost:<daprPort>/v1.0/publish/bulk/<pubsubname>/<topic>[?<metadata>]

请求体应包含一个 JSON 条目数组，其中包含：

  • 唯一的条目 ID
  • 要发布的事件
  • 事件的内容类型

如果事件的 content type 不是 application/cloudevents+json，它将自动包装为 CloudEvent（除非 metadata.rawPayload 设置为 true）。

示例：

curl -X POST http://localhost:3500/v1.0/publish/bulk/pubsubName/deathStarStatus \
  -H 'Content-Type: application/json' \
  -d '[
        {
            "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
            "event":  "first text message",
            "contentType": "text/plain"
        },
        {
            "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
            "event":  {
                "message": "second JSON message"   
            },
            "contentType": "application/json"
        },
      ]'

请求头

Content-Type 请求头应始终设置为 application/json，因为请求体是一个 JSON 数组。

URL 参数

参数描述
daprPortDapr 端口
pubsubname发布/订阅组件的名称
topic主题的名称
metadata元数据的查询参数

元数据

元数据可以通过请求 URL 中的查询参数发送。必须以 metadata. 为前缀，如下表所示。

参数描述
metadata.rawPayload布尔值，确定 Dapr 是否应在不将消息包装为 CloudEvent 的情况下发布消息。
metadata.maxBulkPubBytes在批量发布请求中发布的最大字节数。

HTTP 响应

HTTP 状态描述
204所有消息已投递
400发布/订阅不存在
403被访问控制拒绝
500至少有一条消息未能投递

在 500 状态码的情况下，响应体将包含一个 JSON 对象，其中包含未能投递的条目列表。例如，从上面的请求中，如果事件为 "first text message" 的条目未能投递，响应将包含其条目 ID 和来自底层发布/订阅组件的错误消息。

{
  "failedEntries": [
    {
      "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
      "error": "some error message"
    },
  ],
  "errorCode": "ERR_PUBSUB_PUBLISH_MESSAGE"
}

可选的应用程序（用户代码）路由

提供路由供 Dapr 发现主题订阅

Dapr 将调用用户代码上的以下端点以发现主题订阅：

HTTP 请求

GET http://localhost:<appPort>/dapr/subscribe

URL 参数

参数描述
appPort应用程序端口

HTTP 响应体

一个 JSON 编码的字符串数组。

示例：

[
  {
    "pubsubname": "pubsub",
    "topic": "newOrder",
    "routes": {
      "rules": [
        {
          "match": "event.type == order",
          "path": "/orders"
        }
      ]
      "default" : "/otherorders"
    },
    "metadata": {
      "rawPayload": "true"
    }
  }
]

注意，所有订阅参数区分大小写。

元数据

可选地，可以通过请求体发送元数据。

参数描述
rawPayload布尔值，用于订阅不符合 CloudEvent 规范的事件，如此处所述

提供路由供 Dapr 投递主题事件

为了投递主题事件，将使用订阅响应中指定的路由对用户代码进行 POST 调用。在 routes 下，您可以提供在接收到消息主题时将特定条件匹配到特定路径的规则。 您还可以为没有特定匹配的规则提供默认路由。

以下示例说明了这一点，考虑在端口 3000 上为路由 orders 订阅主题 newOrder：POST http://localhost:3000/orders

HTTP 请求

POST http://localhost:<appPort>/<path>

注意，所有 URL 参数区分大小写。

URL 参数

参数描述
appPort应用程序端口
path订阅配置中的路由路径

预期的 HTTP 响应

HTTP 2xx 响应表示消息已成功处理。

为了更丰富的响应处理，可以发送带有处理状态的 JSON 编码的有效载荷体：

{
  "status": "<status>"
}
状态描述
SUCCESS消息已成功处理
RETRY消息将由 Dapr 重试
DROP记录警告并丢弃消息
其他错误，消息将由 Dapr 重试

Dapr 假定没有 status 字段的 JSON 编码有效载荷响应或 HTTP 2xx 的空有效载荷响应为 SUCCESS。

HTTP 响应可能不同于 HTTP 2xx。以下是 Dapr 在不同 HTTP 状态下的行为：

HTTP 状态描述
2xx消息根据有效载荷中的状态进行处理（如果为空则为 SUCCESS；如果有效载荷无效则忽略）。
404记录错误并丢弃消息
其他记录警告并重试消息

从指定主题订阅多条消息

这允许您在监听 topic 时从代理订阅多条消息。

为了以批量方式接收主题订阅的消息，应用程序：

  • 需要在发送要订阅的主题列表时选择 bulkSubscribe
  • 可选地，可以配置 maxMessagesCount 和/或 maxAwaitDurationMs 有关如何选择加入的更多详细信息，请参阅批量发送和接收消息 指南。

批量订阅的预期 HTTP 响应

HTTP 2xx 响应表示此批量消息中的条目（单个消息）已被应用程序处理，Dapr 现在将检查每个 EntryId 的状态。 需要发送带有针对每个条目的处理状态的 JSON 编码有效载荷体：

{
  "statuses": 
  [ 
    {
    "entryId": "<entryId1>",
    "status": "<status>"
    }, 
    {
    "entryId": "<entryId2>",
    "status": "<status>"
    } 
  ]
}

注意：如果 Dapr 在从应用程序收到的响应中找不到 EntryId 状态，则该条目的状态被视为 RETRY。

状态描述
SUCCESS消息已成功处理
RETRY消息将由 Dapr 重试
DROP记录警告并丢弃消息

HTTP 响应可能不同于 HTTP 2xx。以下是 Dapr 在不同 HTTP 状态下的行为：

HTTP 状态描述
2xx消息根据有效载荷中的状态进行处理。
404记录错误并丢弃所有消息
其他记录警告并重试所有消息

CloudEvents 二进制模式

支持发布使用 CloudEvents HTTP 绑定定义的二进制模式的 CloudEvents。在此模式下，HTTP 主体仅包含有效载荷字节，CloudEvent 属性作为带有 ce_ 前缀的请求头传递。提供所需的请求头（ce_specversion、ce_type、ce_source、ce_id）以及任何可选的请求头（例如 ce_subject 或 ce_time）。 Dapr 将 HTTP Content-Type 请求头复制到 CloudEvent 的 datacontenttype 属性中，并将生成的事件转发给订阅者。

示例发送四个原始字节：

curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
  -H "Content-Type: application/octet-stream" \
  -H "ce_specversion: 1.0" \
  -H "ce_type: com.example.deathstar.status.changed" \
  -H "ce_source: urn:example:/deathstar" \
  -H "ce_id: 3a58b9b8-24d2-4f62-84f4-6177c2fe0633" \
  --data-binary $'\x01\x02\x03\x04'

消息信封

Dapr 发布订阅遵循 CloudEvents 1.0 版本。

相关链接

12 - Secrets API 参考

Secrets API 的详细文档

获取 Secret

此端点允许你从指定的 secret store 中获取 secret 的值。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>

URL 参数

参数描述
daprPortDapr 端口
secret-store-name要获取 secret 的 secret store 名称
name要获取的 secret 名称

注意，所有 URL 参数区分大小写。

查询参数

某些 secret store 支持可选的、每个请求的 metadata 属性。使用查询参数来提供这些属性。例如：

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>?metadata.version_id=15

请注意，并非所有 secret store 都支持相同的参数集。例如：

  • Hashicorp Vault、GCP Secret Manager 和 AWS Secret Manager 支持 version_id 参数
  • 仅 AWS Secret Manager 支持 version_stage 参数
  • 仅 Kubernetes Secrets 支持 namespace 参数 查看每个 secret store 的文档 以获取支持的参数列表。

HTTP 响应

响应体

如果 secret store 支持在 secret 中包含多个键值对，则返回一个 JSON payload，其中键名作为字段，对应的值作为字段值。

对于仅具有名称/值语义的 secret store，则返回一个 JSON payload，其中 secret 名称作为字段，secret 的值作为值。

参见 secret store 的分类，了解哪些支持 secret 中的多个键以及名称/值语义。

包含多个键的 secret 响应（例如 Kubernetes）：
curl http://localhost:3500/v1.0/secrets/kubernetes/db-secret

{
  "key1": "value1",
  "key2": "value2"
}

以上示例演示了来自包含多个键的 secret 的 secret store 的响应。请注意，secret 名称（db-secret）不会作为结果的一部分返回。

来自具有名称/值语义的 secret store 的响应：
curl http://localhost:3500/v1.0/secrets/vault/db-secret

{
  "db-secret": "value1"
}

以上示例演示了来自具有名称/值语义的 secret store 的响应。与包含多个键的 secret 的 secret store 的结果相比，此结果返回单个键值对，其中 secret 名称（db-secret）作为键值对中的键返回。

响应代码

代码描述
200OK
204Secret 未找到
400Secret store 缺失或配置错误
403访问被拒绝
500获取 secret 失败或未定义 secret store

示例

curl http://localhost:3500/v1.0/secrets/mySecretStore/db-secret

curl http://localhost:3500/v1.0/secrets/myAwsSecretStore/db-secret?metadata.version_id=15&metadata.version_stage=production

批量获取 Secret

此端点允许你获取 secret store 中的所有 secret。 如果配置 secret store，建议为 Dapr 使用 token 认证。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/bulk

URL 参数

参数描述
daprPortDapr 端口
secret-store-name要获取 secret 的 secret store 名称

注意，所有 URL 参数区分大小写。

HTTP 响应

响应体

返回的响应是一个包含 secret 的 JSON。JSON 对象将包含 secret 名称作为字段，以及 secret 键和值的映射作为字段值。

包含多个 secret 且 secret 中包含多个键/值的响应（例如 Kubernetes）：
curl http://localhost:3500/v1.0/secrets/kubernetes/bulk

{
    "secret1": {
        "key1": "value1",
        "key2": "value2"
    },
    "secret2": {
        "key3": "value3",
        "key4": "value4"
    }
}

响应代码

代码描述
200OK
400Secret store 缺失或配置错误
403访问被拒绝
500获取 secret 失败或未定义 secret store

示例

curl http://localhost:3500/v1.0/secrets/vault/bulk

{
    "key1": {
        "key1": "value1"
    },
    "key2": {
        "key2": "value2"
    }
}

13 - 服务调用 API 参考

服务调用 API 的详细文档

Dapr 为用户提供了使用唯一命名标识符（appId）调用其他正在使用 Dapr 的应用程序，或不使用 Dapr 的 HTTP 端点的能力。 这使得应用程序可以通过命名标识符相互交互，并将服务发现的负担交给 Dapr 运行时。

调用远程 Dapr 应用程序的方法

此端点允许您调用另一个启用了 Dapr 的应用程序中的方法。

HTTP 请求

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appID>/method/<method-name>

调用非 Dapr 端点的方法

此端点允许您使用 HTTPEndpoint 资源名称或完全限定域名（FQDN）URL 调用非 Dapr 端点上的方法。

HTTP 请求

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<HTTPEndpoint name>/method/<method-name>

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<FQDN URL>/method/<method-name>

HTTP 响应代码

当服务使用 Dapr 调用另一个服务时，被调用服务的状态代码将返回给调用者。 如果存在网络错误或其他瞬态错误，Dapr 将返回带有详细错误消息的 500 错误。

如果用户通过 HTTP 调用 Dapr 以与启用了 gRPC 的服务通信，来自被调用的 gRPC 服务的错误将返回为 500，成功响应将返回为 200OK。

代码描述
XXX返回的上游状态
400未提供方法名称
403访问控制禁止调用
500请求失败

URL 参数

参数描述
daprPortDapr 端口
appID与远程应用关联的 App ID
HTTPEndpoint name与外部端点关联的 HTTPEndpoint 资源
FQDN URL要在外部端点上调用的完全限定域名 URL
method-name要在远程应用上调用的方法或 url 的名称

注意，所有 URL 参数都区分大小写。

请求内容

在请求中，您可以传递标头：

{
  "Content-Type": "application/json"
}

在请求正文中，放置您要发送到服务的数据：

{
  "arg1": 10,
  "arg2": 23,
  "operator": "+"
}

被调用服务接收的请求

一旦您的服务代码调用另一个启用了 Dapr 的应用程序或非 Dapr 端点中的方法，Dapr 将连同标头和正文一起在 <method-name> 端点上发送请求。

被调用的 Dapr 应用程序或非 Dapr 端点需要在该端点上监听并响应请求。

跨命名空间调用

在支持命名空间的托管平台上，Dapr 应用 ID 符合包含目标命名空间的有效 FQDN 格式。 例如，以下字符串包含应用 ID（myApp）以及应用运行的命名空间（production）。

myApp.production

支持命名空间的平台

  • Kubernetes

示例

您可以通过发送以下内容来调用 mathService 服务上的 add 方法：

curl http://localhost:3500/v1.0/invoke/mathService/method/add \
  -H "Content-Type: application/json"
  -d '{ "arg1": 10, "arg2": 23}'

mathService 服务需要监听 /add 端点才能接收和处理请求。

对于 Node 应用，它看起来像这样：

app.post('/add', (req, res) => {
  let args = req.body;
  const [operandOne, operandTwo] = [Number(args['arg1']), Number(args['arg2'])];

  let result = operandOne + operandTwo;
  res.send(result.toString());
});

app.listen(port, () => console.log(`Listening on port ${port}!`));

远程端点的响应将在响应正文中返回。

如果您的服务监听在更嵌套的路径（例如 /api/v1/add），Dapr 会实现完整的反向代理，因此您可以将所有必要的路径片段附加到您的请求 URL，如下所示：

http://localhost:3500/v1.0/invoke/mathService/method/api/v1/add

如果您在不同命名空间上调用 mathService，可以使用以下 URL：

http://localhost:3500/v1.0/invoke/mathService.testing/method/api/v1/add

在此 URL 中，testing 是 mathService 运行所在的命名空间。

服务调用请求中的标头

当 Dapr 调用服务时，它会自动向请求添加以下标头：

标头描述示例
dapr-caller-app-id调用应用程序的 IDmyapp
dapr-caller-namespace调用应用程序的命名空间production
dapr-callee-app-id被调用应用程序的 IDmathService

这些标头在 HTTP 和 gRPC 服务调用请求中都可用。

非 Dapr 端点示例

如果 mathService 服务是非 Dapr 应用程序，则可以通过 HTTPEndpoint 以及完全限定域名（FQDN）URL 使用服务调用对其进行调用。

curl http://localhost:3500/v1.0/invoke/mathHTTPEndpoint/method/add \
  -H "Content-Type: application/json"
  -d '{ "arg1": 10, "arg2": 23}'

curl http://localhost:3500/v1.0/invoke/http://mathServiceURL.com/method/add \
  -H "Content-Type: application/json"
  -d '{ "arg1": 10, "arg2": 23}'

后续步骤

14 - 状态管理 API 参考

状态管理 API 的详细文档

组件文件

Dapr statestore.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: state.<TYPE>
  version: v1
  metadata:
  - name:<KEY>
    value:<VALUE>
  - name: <KEY>
    value: <VALUE>
设置描述
metadata.name状态存储的名称。
spec/metadata一个开放的键值对元数据，允许绑定定义连接属性。

键方案

Dapr 状态存储是键/值存储。为确保数据兼容性，Dapr 要求这些数据存储遵循固定的键方案。对于常规状态，键格式为：

<App ID>||<state key>

对于 Actor 状态，键格式为：

<App ID>||<Actor type>||<Actor id>||<state key>

保存状态

此端点允许您保存状态对象数组。

HTTP 请求

POST http://localhost:<daprPort>/v1.0/state/<storename>

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。

可选的请求元数据通过 URL 查询参数传递。例如，

POST http://localhost:3500/v1.0/state/myStore?metadata.contentType=application/json

所有 URL 参数区分大小写。

由于 || 是保留字符串，因此不能在 <state key> 字段中使用。

请求正文

状态对象的 JSON 数组。每个状态对象包含以下字段：

字段描述
key状态键
value状态值，可以是任何字节数组
etag（可选）状态 ETag
metadata（可选）要传递给状态存储的附加键值对
options（可选）状态操作选项；请参阅状态操作选项

ETag 格式： Dapr 运行时将 ETag 视为不透明字符串。确切的 ETag 格式由相应的数据存储定义。

元数据

元数据可以通过请求 URL 中的查询参数发送。必须以 metadata. 为前缀，如下所示。

参数描述
metadata.ttlInSeconds消息过期的秒数，如此处所述

TTL： 只有特定的状态存储支持 TTL 选项，根据支持的状态存储。

HTTP 响应

响应代码

代码描述
204状态已保存
400状态存储缺失或配置错误或请求格式错误
500保存状态失败

响应正文

无。

示例

curl -X POST http://localhost:3500/v1.0/state/starwars?metadata.contentType=application/json \
  -H "Content-Type: application/json" \
  -d '[
        {
          "key": "weapon",
          "value": "DeathStar",
          "etag": "1234"
        },
        {
          "key": "planet",
          "value": {
            "name": "Tatooine"
          }
        }
      ]'

获取状态

此端点允许您获取特定键的状态。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/state/<storename>/<key>

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。
key所需状态的键
consistency（可选）读取一致性模式；请参阅状态操作选项
metadata（可选）作为查询参数传递给状态存储的元数据

可选的请求元数据通过 URL 查询参数传递。例如，

GET http://localhost:3500/v1.0/state/myStore/myKey?metadata.contentType=application/json

注意，所有 URL 参数区分大小写。

HTTP 响应

响应代码

代码描述
200获取状态成功
204未找到键
400状态存储缺失或配置错误
500获取状态失败

响应头

头描述
ETag返回值的 ETag

响应正文

JSON 编码的值

示例

curl http://localhost:3500/v1.0/state/starwars/planet?metadata.contentType=application/json

以上命令返回状态：

{
  "name": "Tatooine"
}

将元数据作为查询参数传递：

GET http://localhost:3500/v1.0/state/starwars/planet?metadata.partitionKey=mypartitionKey&metadata.contentType=application/json

批量获取状态

此端点允许您获取给定键列表的值列表。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/bulk

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。
metadata（可选）作为查询参数传递给状态存储的元数据

可选的请求元数据通过 URL 查询参数传递。例如，

POST/PUT http://localhost:3500/v1.0/state/myStore/bulk?metadata.partitionKey=mypartitionKey

注意，所有 URL 参数区分大小写。

HTTP 响应

响应代码

代码描述
200获取状态成功
400状态存储缺失或配置错误
500批量获取状态失败

响应正文

JSON 编码值的数组

示例

curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
  -H "Content-Type: application/json" \
  -d '{
          "keys": [ "key1", "key2" ],
          "parallelism": 10
      }'

以上命令返回键/值对象数组：

[
  {
    "key": "key1",
    "value": "value1",
    "etag": "1"
  },
  {
    "key": "key2",
    "value": "value2",
    "etag": "1"
  }
]

将元数据作为查询参数传递：

POST http://localhost:3500/v1.0/state/myRedisStore/bulk?metadata.partitionKey=mypartitionKey

删除状态

此端点允许您删除特定键的状态。

HTTP 请求

DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。
key所需状态的键
concurrency（可选）first-write 或 last-write；请参阅状态操作选项
consistency（可选）strong 或 eventual；请参阅状态操作选项

可选的请求元数据通过 URL 查询参数传递。例如，

DELETE http://localhost:3500/v1.0/state/myStore/myKey?metadata.contentType=application/json

注意，所有 URL 参数区分大小写。

请求头

头描述
If-Match（可选）与要删除的键关联的 ETag

HTTP 响应

响应代码

代码描述
204删除状态成功
400状态存储缺失或配置错误
500删除状态失败

响应正文

无。

示例

curl -X DELETE http://localhost:3500/v1.0/state/starwars/planet -H "If-Match: xxxxxxx"

查询状态

此端点允许您查询键/值状态。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0-alpha1/state/<storename>/query

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。
metadata（可选）作为查询参数传递给状态存储的元数据

可选的请求元数据通过 URL 查询参数传递。例如，

POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.contentType=application/json

注意，所有 URL 参数区分大小写。

响应代码

代码描述
200状态查询成功
400状态存储缺失或配置错误
500状态查询失败

响应正文

JSON 编码值的数组

示例

curl -X POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.contentType=application/json \
  -H "Content-Type: application/json" \
  -d '{
        "filter": {
          "OR": [
            {
              "EQ": { "person.org": "Dev Ops" }
            },
            {
              "AND": [
                {
                  "EQ": { "person.org": "Finance" }
                },
                {
                  "IN": { "state": [ "CA", "WA" ] }
                }
              ]
            }
          ]
        },
        "sort": [
          {
            "key": "state",
            "order": "DESC"
          },
          {
            "key": "person.id"
          }
        ],
        "page": {
          "limit": 3
        }
      }'

以上命令返回对象数组以及令牌：

{
  "results": [
    {
      "key": "1",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1036
        },
        "city": "Seattle",
        "state": "WA"
      },
      "etag": "6f54ad94-dfb9-46f0-a371-e42d550adb7d"
    },
    {
      "key": "4",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1042
        },
        "city": "Spokane",
        "state": "WA"
      },
      "etag": "7415707b-82ce-44d0-bf15-6dc6305af3b1"
    },
    {
      "key": "10",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1054
        },
        "city": "New York",
        "state": "NY"
      },
      "etag": "26bbba88-9461-48d1-8a35-db07c374e5aa"
    }
  ],
  "token": "3"
}

将元数据作为查询参数传递：

POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.partitionKey=mypartitionKey

状态事务

将更改持久化到状态存储作为事务操作。

此 API 依赖于支持事务的状态存储组件。

有关支持事务的状态存储的完整当前列表，请参阅状态存储组件规范。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/transaction

HTTP 响应代码

代码描述
204请求成功
400状态存储缺失或配置错误或请求格式错误
500请求失败

URL 参数

参数描述
daprPortDapr 端口
storename用户配置的 statestore.yaml 组件文件中的 metadata.name 字段。请参阅上文提到的 Dapr 状态存储配置结构。

可选的请求元数据通过 URL 查询参数传递。例如，

POST http://localhost:3500/v1.0/state/myStore/transaction?metadata.contentType=application/json

注意，所有 URL 参数区分大小写。

请求正文

字段描述
operations状态 operation 的 JSON 数组
metadata（可选）适用于所有操作的事务的 metadata

所有事务数据库都实现以下必需的操作：

操作描述
upsert添加或更新值
delete删除值

每个操作都有一个关联的 request，包含以下字段：

请求描述
key状态键
value状态值，可以是任何字节数组
etag（可选）状态 ETag
metadata（可选）要传递给状态存储的附加键值对，适用于此操作
options（可选）状态操作选项；请参阅状态操作选项

示例

以下示例显示了对 key1 的 upsert 操作和对 key2 的 delete 操作。这应用于状态存储中名为 “planet” 的分区。两个操作要么成功要么失败。

curl -X POST http://localhost:3500/v1.0/state/starwars/transaction \
  -H "Content-Type: application/json" \
  -d '{
        "operations": [
          {
            "operation": "upsert",
            "request": {
              "key": "key1",
              "value": "myData"
            }
          },
          {
            "operation": "delete",
            "request": {
              "key": "key2"
            }
          }
        ],
        "metadata": {
          "partitionKey": "planet"
        }
      }'

为 Actor 配置状态存储

Actor 不支持多个状态存储，并且需要与 Dapr 一起使用事务状态存储。查看当前实现事务状态存储接口的服务。如果您的状态存储由分布式数据库支持，您必须确保它提供强一致性。

在 statestore.yaml 组件文件的元数据部分中，为属性 actorStateStore 使用 true 值来指定要用于 Actor 的状态存储。 例如，以下组件 yaml 将配置 Redis 用作 Actor 的状态存储。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: <redis host>
  - name: redisPassword
    value: ""
  - name: actorStateStore
    value: "true"

可选行为

键方案

兼容 Dapr 的状态存储应使用以下键方案：

  • <App ID>||<state key> 常规状态的键格式
  • <App ID>||<Actor type>||<Actor id>||<state key> Actor 状态的键格式。

并发

Dapr 使用带有 ETag 的优化并发控制（OCC）。Dapr 对状态存储提出以下可选要求：

  • 兼容 Dapr 的状态存储可以使用 ETag 支持乐观并发控制。当 ETag 满足以下条件时，存储允许更新：
    • 与 save 或 delete 请求关联。
    • 与数据库中的最新 ETag 匹配。
  • 当写入请求中缺少 ETag 时，状态存储应以 last-write-wins 方式处理请求。这允许针对高吞吐量写入场景进行优化，在这些场景中数据争用较低或没有负面影响。
  • 存储在向调用者返回状态时应 始终 返回 ETag。

一致性

Dapr 允许客户端为 get、set 和 delete 操作附加一致性提示。Dapr 支持两个一致性级别：强 和 最终。

最终一致性

Dapr 假定数据存储默认是最终一致的。状态应该：

  • 对于 read 请求，从任何副本返回数据。
  • 对于 write 请求，在确认更新请求后异步将更新复制到配置的仲裁。

强一致性

当附加强一致性提示时，状态存储应该：

  • 对于 read 请求，在副本之间一致地返回最新数据。
  • 对于 write/delete 请求，在完成写入请求之前将更新后的数据同步复制到配置的仲裁。

示例：完整的选项请求示例

以下是带有完整 options 定义的 set 请求示例：

curl -X POST http://localhost:3500/v1.0/state/starwars \
  -H "Content-Type: application/json" \
  -d '[
        {
          "key": "weapon",
          "value": "DeathStar",
          "etag": "xxxxx",
          "options": {
            "concurrency": "first-write",
            "consistency": "strong"
          }
        }
      ]'

示例：使用 ETag

以下是在兼容的状态存储中 设置/删除 对象时使用 ETag 的示例演练。此示例将 Redis 定义为 statestore。

  1. 在状态存储中存储一个对象：

    curl -X POST http://localhost:3500/v1.0/state/statestore \
    -H "Content-Type: application/json" \
    -d '[
            {
                "key": "sampleData",
                "value": "1"
            }
    ]'

  2. 获取对象以查找状态存储自动设置的 ETag：

    curl http://localhost:3500/v1.0/state/statestore/sampleData -v
* Connected to localhost (127.0.0.1) port 3500 (#0)
> GET /v1.0/state/statestore/sampleData HTTP/1.1
> Host: localhost:3500
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: fasthttp
< Date: Sun, 14 Feb 2021 04:51:50 GMT
< Content-Type: application/json
< Content-Length: 3
< Etag: 1
< Traceparent: 00-3452582897d134dc9793a244025256b1-b58d8d773e4d661d-01
<
* Connection #0 to host localhost left intact
"1"* Closing connection 0

    上面返回的 ETag 是 1。如果您发送带有错误 ETag 的新请求来更新或删除数据，它将返回错误。省略 ETag 将允许请求。

    # Update
curl -X POST http://localhost:3500/v1.0/state/statestore \
    -H "Content-Type: application/json" \
    -d '[
            {
                "key": "sampleData",
                "value": "2",
                "etag": "2"
            }
    ]'
{"errorCode":"ERR_STATE_SAVE","message":"failed saving state in state store statestore: possible etag mismatch. error from state store: ERR Error running script (call to f_83e03ec05d6a3b6fb48483accf5e594597b6058f): @user_script:1: user_script:1: failed to set key nodeapp||sampleData"}

# Delete
curl -X DELETE -H 'If-Match: 5' http://localhost:3500/v1.0/state/statestore/sampleData
{"errorCode":"ERR_STATE_DELETE","message":"failed deleting state with key sampleData: possible etag mismatch. error from state store: ERR Error running script (call to f_9b5da7354cb61e2ca9faff50f6c43b81c73c0b94): @user_script:1: user_script:1: failed to delete node
app||sampleData"}

  3. 通过在请求正文（更新）或 If-Match 头（删除）中匹配 ETag 来更新或删除对象。当状态更新时，它会收到一个新的 ETag，未来的更新或删除将需要使用该 ETag。

    # Update
curl -X POST http://localhost:3500/v1.0/state/statestore \
    -H "Content-Type: application/json" \
    -d '[
        {
            "key": "sampleData",
            "value": "2",
            "etag": "1"
        }
    ]'

# Delete
curl -X DELETE -H 'If-Match: 1' http://localhost:3500/v1.0/state/statestore/sampleData

后续步骤

15 - Workflow API 参考

Dapr 为用户提供了通过其内置工作流引擎与工作流交互的能力，该引擎使用 Dapr Actors 实现。

要了解如何与工作流引擎交互，请参阅[如何编写](https://docs.dapr.io/zh-hans/developing-applications/building-blocks/workflow/howto-author-workflow/和[管理工作流](https://docs.dapr.io/zh-hans/developing-applications/building-blocks/workflow/howto-manage-workflow/。

HTTP API 参考（已弃用）

以下是 Dapr Workflow API 的参考文档。 该 API 已弃用，最终将被移除。

启动工作流请求

使用给定名称启动工作流实例，可选择指定实例 ID。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<workflowName>/start[?instanceID=<instanceID>]

请注意，工作流实例 ID 只能包含字母数字字符、下划线和短横线。

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
workflowName标识工作流类型
instanceID（可选）为特定工作流的每次运行创建的唯一值

请求内容

任何请求内容都将作为输入传递给工作流。Dapr API 会原样传递内容，而不会尝试解释它。

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500请求格式正确，dapr 代码中存在错误

响应内容

API 调用将提供类似以下的响应：

{
    "instanceID": "12345678"
}

终止工作流请求

使用给定名称和实例 ID 终止正在运行的工作流实例。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/terminate

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500请求格式正确，dapr 代码中存在错误

响应内容

此 API 不返回任何内容。

触发事件请求

对于支持订阅外部事件的工作流组件（如 Dapr Workflow 引擎），您可以使用以下"触发事件" API 向特定工作流实例传递命名事件。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceID>/raiseEvent/<eventName>

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值
eventName要触发的事件名称

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500请求格式正确，dapr 代码或底层组件中存在错误

响应内容

无。

暂停工作流请求

暂停正在运行的工作流实例。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/pause

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500Dapr 代码或底层组件中存在错误

响应内容

无。

恢复工作流请求

恢复已暂停的工作流实例。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/resume

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500Dapr 代码中存在错误

响应内容

无。

清除工作流请求

使用工作流的实例 ID 从状态存储中清除工作流状态。

POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>/purge

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码描述
202已接受
400请求格式错误
500Dapr 代码中存在错误

响应内容

无。

获取工作流请求

获取给定工作流实例的信息。

GET http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<instanceId>

URL 参数

参数描述
workflowComponentName对于 Dapr Workflows 使用 dapr
instanceId为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码描述
200OK
400请求格式错误
500Dapr 代码中存在错误

响应内容

API 调用将提供类似以下的 JSON 响应：

{
  "createdAt": "2023-01-12T21:31:13Z",
  "instanceID": "12345678",
  "lastUpdatedAt": "2023-01-12T21:31:13Z",
  "properties": {
    "property1": "value1",
    "property2": "value2"
  },
  "runtimeStatus": "RUNNING"
}
参数描述
runtimeStatus工作流实例的状态。值包括："RUNNING"、"COMPLETED"、"CONTINUED_AS_NEW"、"FAILED"、"CANCELED"、"TERMINATED"、"PENDING"、"SUSPENDED"