Dapr 参考文档

• 1: Dapr API 参考
• 1.1: Actors API 参考文档
• 1.2: Bindings API 参考
• 1.3: Configuration API 参考
• 1.4: Conversation API 参考
• 1.5: 加密 API 参考
• 1.6: 分布式锁 API 参考
• 1.7: Health API 参考
• 1.8: Jobs API 参考
• 1.9: Metadata API 参考
• 1.10: Placement API 参考
• 1.11: 发布订阅 API 参考
• 1.12: Secrets API 参考
• 1.13: 服务调用 API 参考
• 1.14: 状态管理 API 参考
• 1.15: Workflow API 参考
• 2: Dapr CLI 参考
• 2.1: Dapr 命令行界面（CLI）参考
• 2.2: dapr scheduler
• 2.3: annotate CLI 命令参考
• 2.4: build-info CLI 命令参考
• 2.5: completion CLI 命令参考
• 2.6: components CLI 命令参考
• 2.7: configurations CLI 命令参考
• 2.8: dashboard CLI 命令参考
• 2.9: help CLI 命令参考
• 2.10: init CLI 命令参考
• 2.11: invoke CLI 命令参考
• 2.12: list CLI 命令参考
• 2.13: logs CLI 命令参考
• 2.14: mtls CLI 命令参考
• 2.14.1: mtls export CLI 命令参考
• 2.14.2: mtls expiry CLI 命令参考
• 2.14.3: mtls renew certificate CLI 命令参考
• 2.15: publish CLI 命令参考
• 2.16: run CLI 命令参考
• 2.17: status CLI 命令参考
• 2.18: stop CLI 命令参考
• 2.19: uninstall CLI 命令参考
• 2.20: upgrade CLI 命令参考
• 2.21: version CLI 命令参考
• 2.22: workflow CLI 命令
• 3: daprd、CLI 和 Kubernetes 的 Dapr 参数与注解
• 4: 环境变量参考
• 5: Dapr 组件参考
• 5.1: 绑定组件规格
• 5.1.1: Alibaba Cloud DingTalk binding 规范
• 5.1.2: Alibaba Cloud Tablestore binding 规范
• 5.1.3: Apple Push Notification Service 绑定规范
• 5.1.4: AWS DynamoDB 绑定规范
• 5.1.5: AWS Kinesis 绑定规范
• 5.1.6: AWS S3 绑定规范
• 5.1.7: AWS SES 绑定规范
• 5.1.8: AWS SNS 绑定规范
• 5.1.9: AWS SQS 绑定规范
• 5.1.10: Azure Blob Storage 绑定规范
• 5.1.11: Azure Cosmos DB (Gremlin API) 绑定规范
• 5.1.12: Azure Cosmos DB (SQL API) 绑定规范
• 5.1.13: Azure Event Grid 绑定规范
• 5.1.14: Azure Event Hubs 绑定规约
• 5.1.15: Azure OpenAI binding 规范
• 5.1.16: Azure Service Bus Queues 绑定规范
• 5.1.17: Azure SignalR 绑定规范
• 5.1.18: Azure Storage Queues binding spec
• 5.1.19: Cloudflare Queues 绑定规范
• 5.1.20: commercetools GraphQL 绑定规范
• 5.1.21: Cron 绑定规范
• 5.1.22: Apache Dubbo binding 规范
• 5.1.23: GCP Pub/Sub 绑定规范
• 5.1.24: GCP Storage Bucket binding 规范
• 5.1.25: GraphQL 绑定规范
• 5.1.26: HTTP binding 规范
• 5.1.27: Huawei OBS binding 规范
• 5.1.28: InfluxDB 绑定规范
• 5.1.29: Kafka 绑定规范
• 5.1.30: Kitex
• 5.1.31: KubeMQ 绑定规范
• 5.1.32: Kubernetes Events 绑定规范
• 5.1.33: Local Storage 绑定规范
• 5.1.34: MQTT3 binding 规范
• 5.1.35: MySQL & MariaDB 绑定规范
• 5.1.36: PostgreSQL 绑定规范
• 5.1.37: Postmark binding 规范
• 5.1.38: RabbitMQ 绑定规范
• 5.1.39: Redis binding spec
• 5.1.40: RethinkDB 绑定规范
• 5.1.41: Apache RocketMQ binding 规范
• 5.1.42: SFTP binding spec
• 5.1.43: SMTP 绑接规范
• 5.1.44: Twilio SendGrid binding spec
• 5.1.45: Twilio SMS 绑定规范
• 5.1.46: Wasm
• 5.1.47: Zeebe command binding 规范
• 5.1.48: Zeebe JobWorker 绑定规范
• 5.1.49: 阿里云对象存储服务绑定规范
• 5.1.50: 阿里云日志服务绑定规范
• 5.2: 配置存储组件规格
• 5.2.1: Azure App Configuration
• 5.2.2: PostgreSQL
• 5.2.3: Redis
• 5.3: Conversation 组件规格
• 5.3.1: Anthropic
• 5.3.2: AWS Bedrock
• 5.3.3: DeepSeek
• 5.3.4: 本地测试
• 5.3.5: GoogleAI
• 5.3.6: Huggingface
• 5.3.7: Mistral
• 5.3.8: Ollama
• 5.3.9: OpenAI
• 5.4: 加密组件规范
• 5.4.1: Azure Key Vault
• 5.4.2: JSON Web Key Sets (JWKS)
• 5.4.3: Kubernetes Secrets
• 5.4.4: Local storage
• 5.5: Lock 组件规范
• 5.5.1: Redis
• 5.6: 中间件组件规格
• 5.6.1: Bearer
• 5.6.2: OAuth2
• 5.6.3: OAuth2 客户端凭据
• 5.6.4: 应用 Open Policy Agent (OPA) 策略
• 5.6.5: Router alias http request routing
• 5.6.6: RouterChecker HTTP 请求路由
• 5.6.7: Sentinel 容错中间件组件
• 5.6.8: 将请求体转换为大写
• 5.6.9: Wasm
• 5.6.10: 速率限制
• 5.7: 名称解析提供程序组件规范
• 5.7.1: AWS Cloudmap
• 5.7.2: HashiCorp Consul
• 5.7.3: Kubernetes DNS
• 5.7.4: mDNS
• 5.7.5: Nameformat
• 5.7.6: SQLite
• 5.8: 发布订阅代理组件规范
• 5.8.1: Apache Kafka
• 5.8.2: AWS SNS/SQS
• 5.8.3: Azure Event Hubs
• 5.8.4: Azure Service Bus 队列
• 5.8.5: Azure Service Bus 主题
• 5.8.6: GCP
• 5.8.7: In-memory
• 5.8.8: JetStream
• 5.8.9: KubeMQ
• 5.8.10: MQTT
• 5.8.11: MQTT3
• 5.8.12: Pulsar
• 5.8.13: RabbitMQ
• 5.8.14: Redis Streams
• 5.8.15: RocketMQ
• 5.8.16: Solace-AMQP
• 5.9: 密钥存储组件规格
• 5.9.1: AWS Secrets Manager
• 5.9.2: AWS SSM Parameter Store
• 5.9.3: Azure Key Vault secret store
• 5.9.4: GCP Secret Manager
• 5.9.5: HashiCorp Vault
• 5.9.6: HuaweiCloud Cloud Secret Management Service (CSMS)
• 5.9.7: Kubernetes 密钥
• 5.9.8: Local file (for Development)
• 5.9.9: OpenBao
• 5.9.10: Tencent Cloud Secrets Manager (SSM)
• 5.9.11: 阿里云 OOS Parameter Store
• 5.9.12: 本地环境变量（用于开发）
• 5.10: 状态存储组件规格
• 5.10.1: Aerospike
• 5.10.2: Alibaba Cloud TableStore
• 5.10.3: AWS DynamoDB
• 5.10.4: Azure Blob Storage
• 5.10.5: Azure Cosmos DB (SQL API)
• 5.10.6: Azure Table Storage
• 5.10.7: Cassandra
• 5.10.8: Cloudflare Workers KV
• 5.10.9: CockroachDB
• 5.10.10: Coherence
• 5.10.11: Couchbase
• 5.10.12: Etcd
• 5.10.13: GCP Firestore (Datastore 模式)
• 5.10.14: HashiCorp Consul
• 5.10.15: Hazelcast
• 5.10.16: In-memory
• 5.10.17: JetStream KV
• 5.10.18: Memcached
• 5.10.19: Microsoft SQL Server & Azure SQL
• 5.10.20: Microsoft SQL Server & Azure SQL
• 5.10.21: MongoDB
• 5.10.22: MySQL & MariaDB
• 5.10.23: OCI 对象存储
• 5.10.24: Oracle Database
• 5.10.25: PostgreSQL
• 5.10.26: PostgreSQL v1
• 5.10.27: RavenDB
• 5.10.28: Redis
• 5.10.29: RethinkDB
• 5.10.30: SQLite
• 5.10.31: Zookeeper
• 6: Dapr 资源规范
• 6.1: 组件规范
• 6.2: Subscription 规范
• 6.3: 弹性规范
• 6.4: HTTPEndpoint 规范
• 6.5: 配置规范

1 - Dapr API 参考

1.1 - 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 对象：

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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

示例

获取已注册 actor 的示例：

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

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

{
  "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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

注意，所有 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 响应码

URL 参数

示例

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

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 命名空间下。

1.2 - Bindings 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 响应码

URL 参数

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

绑定负载

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

HTTP 请求

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

HTTP 响应码

URL 参数

注意，所有 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 响应码

负载

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

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

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

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

URL 参数

注意，所有 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"
      }'

常见元数据值

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

1.3 - Configuration API 参考

获取配置

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

HTTP 请求

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

URL 参数

查询参数

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

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

要检索所有配置项：

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

请求体

无

HTTP 响应

响应代码

响应体

每个配置项的键/值对的 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 参数

查询参数

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

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

要订阅所有更改：

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

请求体

无

HTTP 响应

响应代码

响应体

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 参数

查询参数

无

请求体

无

HTTP 响应

响应代码

响应体

{
    "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 参数

请求体

给定订阅 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"
    ]
}

后续步骤

• Configuration API 概述
• 操作指南：从存储管理配置

1.4 - 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 参数

请求体

输入体

消息类型

API 支持不同的消息类型：

工具调用

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

工具选择选项

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

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

元数据

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

常见元数据字段：

除了在请求体中传递元数据外，您还可以将元数据作为 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 响应代码

弹性和超时

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

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

响应内容

outputs 中的每一项可以包含：

使用指标

当存在时，usage 包含：

基本对话响应

{
  "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

后续步骤

• Conversation API 概述
• 支持的对话组件

1.5 - 加密 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 参数

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

请求头

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

HTTP 响应

响应体

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

响应代码

示例

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 参数

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

请求头

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

HTTP 响应

响应体

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

响应代码

示例

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

1.6 - 分布式锁 API 参考

加锁

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

HTTP 请求

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

URL 参数

查询参数

无

HTTP 响应码

HTTP 请求体

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

{
    "resourceId": "",
    "lockOwner": "",
    "expiryInSeconds": 0
}

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 参数

查询参数

无

HTTP 响应码

HTTP 请求体

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

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

HTTP 响应体

解锁端点返回以下负载：

{
    "status": 0
}

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

示例

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

{
    "status": 0
}

1.7 - Health API 参考

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

获取 Dapr 健康状态

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

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

等待 Dapr HTTP 端口变为可用

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

HTTP 请求

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

HTTP 响应代码

URL 参数

示例

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 响应代码

URL 参数

示例

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

相关文章

• 边车健康
• 应用健康

1.8 - 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 参数

schedule

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

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

示例 1

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

示例 2

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

周期字符串表达式：

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 响应代码

响应内容

以下示例 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 参数

HTTP 响应代码

响应内容

运行以下示例 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 参数

HTTP 响应代码

响应内容

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

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

后续步骤

Jobs API 概述

1.9 - Metadata API 参考

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

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

Metadata API

组件

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

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 参数

HTTP 响应代码

HTTP 响应正文

元数据 API 响应对象

元数据 API 响应注册 Actor

元数据 API 响应组件

元数据 API 响应 HttpEndpoint

元数据 API 响应订阅

元数据 API 响应订阅规则

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

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

元数据 API 响应调度器

元数据 API 响应工作流

示例

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 参数

HTTP 请求正文

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

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

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

attributeValue

HTTP 响应代码

示例

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

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

1.10 - 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 响应代码

HTTP 响应体

Placement 表 API 响应对象

Actor 主机信息

示例

 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
}

1.11 - 发布订阅 API 参考

向指定主题发布消息

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

HTTP 请求

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

HTTP 响应码

URL 参数

注意，所有 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. 为前缀，如下所示。

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

向指定主题发布多条消息

此端点允许您向正在监听 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 参数

元数据

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

HTTP 响应

在 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 参数

HTTP 响应体

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

示例：

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

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

元数据

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

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

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

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

HTTP 请求

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

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

URL 参数

预期的 HTTP 响应

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

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

{
  "status": "<status>"
}

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

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

从指定主题订阅多条消息

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

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

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

批量订阅的预期 HTTP 响应

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

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

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

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

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 版本。

相关链接

• 如何发布和消费主题
• 发布/订阅示例

1.12 - Secrets API 参考

获取 Secret

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

HTTP 请求

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

URL 参数

注意，所有 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）作为键值对中的键返回。

响应代码

示例

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 参数

注意，所有 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"
    }
}

响应代码

示例

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

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

1.13 - 服务调用 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。

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 调用服务时，它会自动向请求添加以下标头：

这些标头在 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}'

后续步骤

• 操作指南：调用和发现服务

1.14 - 状态管理 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>

键方案

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 参数

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

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

所有 URL 参数区分大小写。

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

请求正文

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

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

元数据

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

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

HTTP 响应

响应代码

响应正文

无。

示例

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 参数

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

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

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

HTTP 响应

响应代码

响应头

响应正文

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 参数

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

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

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

HTTP 响应

响应代码

响应正文

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 参数