Dapr 文档资料

• 1: Dapr API 文档指南
• 1.1: 服务调用API参考
• 1.2: 发布/订阅 API 参考
• 1.3: 工作流 API 参考
• 1.4: 状态管理API参考
• 1.5: Bindings API 参考
• 1.6: Actors API 参考
• 1.7: Secrets API 参考
• 1.8: 配置 API 参考
• 1.9: 分布式锁 API 参考
• 1.10: 健康 API 参考
• 1.11: 元数据 API 参考
• 1.12: Placement API 参考
• 1.13: 加密 API 参考
• 1.14: 作业API参考
• 1.15: 会话API参考
• 2: Dapr CLI 参考文档
• 2.1: Dapr 命令行界面 (CLI) 参考
• 2.2: annotate CLI 命令参考
• 2.3: build-info CLI 命令指南
• 2.4: completion CLI 命令参考
• 2.5: components CLI 命令指南
• 2.6: dashboard CLI 命令参考
• 2.7: help 命令行界面命令参考
• 2.8: init CLI 命令参考
• 2.9: invoke CLI 命令参考
• 2.10: list CLI 命令参考
• 2.11: logs CLI 命令参考
• 2.12: mtls CLI 命令参考
• 2.12.1: mtls export CLI 命令参考
• 2.12.2: mtls expiry CLI 命令指南
• 2.12.3: mtls renew certificate CLI 命令参考
• 2.13: status CLI 命令参考
• 2.14: stop CLI 命令参考
• 2.15: version CLI 命令参考
• 2.16: 发布命令行工具参考
• 2.17: 配置 CLI 命令参考
• 2.18: 升级 CLI 命令参考
• 2.19: 卸载 CLI 命令参考
• 2.20: 运行 CLI 命令参考
• 3: Dapr 参数和注解用于 daprd、CLI 和 Kubernetes
• 4: 环境变量参考
• 5: Dapr 组件指南
• 5.1: 发布/订阅代理组件规范
• 5.1.1: Apache Kafka
• 5.1.2: AWS SNS/SQS
• 5.1.3: Azure Event Hubs
• 5.1.4: Azure Service Bus Topics
• 5.1.5: Azure Service Bus 队列
• 5.1.6: GCP
• 5.1.7: JetStream
• 5.1.8: KubeMQ
• 5.1.9: MQTT
• 5.1.10: MQTT3
• 5.1.11: Pulsar
• 5.1.12: RabbitMQ
• 5.1.13: Redis Streams
• 5.1.14: RocketMQ
• 5.1.15: Solace-AMQP
• 5.1.16: 内存
• 5.2: 工作流后端组件规范
• 5.2.1: Actor 工作流后端
• 5.3: Bindings 组件规格
• 5.3.1: Apple 推送通知服务绑定说明
• 5.3.2: AWS DynamoDB 绑定说明
• 5.3.3: AWS Kinesis 绑定规范
• 5.3.4: AWS S3 绑定规范
• 5.3.5: AWS SES 绑定说明
• 5.3.6: AWS SNS 绑定组件规范
• 5.3.7: AWS SQS 绑定规范
• 5.3.8: Azure Blob Storage 绑定指南
• 5.3.9: Azure Cosmos DB (Gremlin API) 绑定组件说明
• 5.3.10: Azure Cosmos DB (SQL API) 绑定说明
• 5.3.11: Azure Event Grid 绑定规范
• 5.3.12: Azure Event Hubs 绑定规范
• 5.3.13: Azure OpenAI 绑定组件规范
• 5.3.14: Azure Service Bus Queues 绑定规范
• 5.3.15: Azure SignalR 绑定规范
• 5.3.16: Azure Storage Queues 绑定规范
• 5.3.17: Cloudflare Queues 绑定规范
• 5.3.18: commercetools GraphQL 绑定说明
• 5.3.19: Cron 绑定规范
• 5.3.20: GCP Pub/Sub 绑定规范
• 5.3.21: GCP 存储桶绑定指南
• 5.3.22: GraphQL 绑定说明
• 5.3.23: HTTP 绑定规范
• 5.3.24: InfluxDB 绑定规范
• 5.3.25: Kafka 绑定规范
• 5.3.26: Kitex
• 5.3.27: KubeMQ 绑定规范
• 5.3.28: Kubernetes Events 绑定指南
• 5.3.29: MQTT3 绑定规范
• 5.3.30: MySQL & MariaDB 绑定规范
• 5.3.31: PostgreSQL 绑定组件规范
• 5.3.32: Postmark 绑定说明
• 5.3.33: RabbitMQ 绑定规范
• 5.3.34: Redis 绑定规范
• 5.3.35: RethinkDB 绑定规范
• 5.3.36: SFTP 绑定规范
• 5.3.37: SMTP 绑定规范
• 5.3.38: Twilio SendGrid 绑定规范
• 5.3.39: Twilio SMS 绑定说明
• 5.3.40: Wasm
• 5.3.41: Zeebe JobWorker 绑定说明
• 5.3.42: Zeebe 命令绑定说明
• 5.3.43: 阿里云 Tablestore 绑定组件规范
• 5.3.44: 阿里云钉钉绑定组件规范
• 5.3.45: 阿里云对象存储服务绑定指南
• 5.3.46: 阿里云日志存储服务绑定指南
• 5.3.47: 本地存储绑定规范
• 5.3.48: 华为 OBS 绑定规范
• 5.4: 状态存储组件说明
• 5.4.1: Aerospike
• 5.4.2: AWS DynamoDB
• 5.4.3: Azure Blob 存储
• 5.4.4: Azure Cosmos DB（SQL API）
• 5.4.5: Azure 表存储
• 5.4.6: Cassandra
• 5.4.7: Cloudflare Workers KV
• 5.4.8: CockroachDB
• 5.4.9: Couchbase
• 5.4.10: Etcd
• 5.4.11: GCP Firestore（Datastore 模式）
• 5.4.12: HashiCorp Consul
• 5.4.13: Hazelcast
• 5.4.14: JetStream KV
• 5.4.15: Memcached
• 5.4.16: Microsoft SQL Server & Azure SQL
• 5.4.17: MongoDB
• 5.4.18: MySQL & MariaDB
• 5.4.19: OCI 对象存储
• 5.4.20: Oracle 数据库
• 5.4.21: PostgreSQL
• 5.4.22: PostgreSQL v1
• 5.4.23: Redis
• 5.4.24: RethinkDB
• 5.4.25: SQLite
• 5.4.26: Zookeeper
• 5.4.27: 内存
• 5.5: Secret 存储组件规范
• 5.5.1: AWS Secrets Manager
• 5.5.2: AWS SSM 参数存储
• 5.5.3: Azure Key Vault 密钥存储
• 5.5.4: GCP Secret Manager
• 5.5.5: HashiCorp Vault
• 5.5.6: Kubernetes secrets
• 5.5.7: 阿里云 OOS 参数存储
• 5.5.8: 本地环境变量（用于开发）
• 5.5.9: 本地文件（用于开发）
• 5.5.10: 华为云密钥管理服务 (CSMS)
• 5.6: 配置存储组件说明
• 5.6.1: Azure 应用配置
• 5.6.2: PostgreSQL
• 5.6.3: Redis
• 5.7: 锁组件规格
• 5.7.1: Redis
• 5.8: 密码学组件规范
• 5.8.1: Azure Key Vault
• 5.8.2: JSON Web Key Sets (JWKS)
• 5.8.3: Kubernetes Secrets
• 5.8.4: 本地存储
• 5.9: 会话组件规范
• 5.9.1:
• 5.9.2: Anthropic
• 5.9.3: Huggingface
• 5.9.4: Mistral
• 5.9.5: OpenAI
• 5.10: 名称解析提供者组件规范
• 5.10.1: HashiCorp Consul
• 5.10.2: Kubernetes DNS
• 5.10.3: mDNS
• 5.10.4: SQLite
• 5.11: 中间件组件说明
• 5.11.1: Bearer
• 5.11.2: OAuth2
• 5.11.3: OAuth2 客户端凭证
• 5.11.4: 应用 Open Policy Agent (OPA) 策略
• 5.11.5: RouterChecker HTTP 请求路由检查
• 5.11.6: Sentinel 容错中间件组件
• 5.11.7: Wasm
• 5.11.8: 将请求体转换为大写
• 5.11.9: HTTP 路由别名
• 5.11.10: 速率限制
• 6: Dapr 资源规格
• 6.1: 组件规范
• 6.2: 订阅规范
• 6.3: 弹性说明
• 6.4: HTTPEndpoint 规范
• 6.5: 配置规范

1 - Dapr API 文档指南

1.1 - 服务调用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，而成功的响应将返回为200 OK。

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端点示例

如果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.2 - 发布/订阅 API 参考

向指定主题发布消息

此端点允许您将数据发布到多个正在监听某个 topic 的消费者。Dapr 保证此端点至少会被调用一次。

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。如果您的内容类型是 JSON，请使用值为 application/json 的 Content-Type 头部。

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

元数据

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

根据每个 pubsub 组件，还可以使用其他元数据参数。

向指定主题发布多条消息

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

HTTP 请求

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

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

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

如果事件的内容类型不是 application/cloudevents+json，则会自动包装为 CloudEvent（除非 metadata.rawPayload 设置为 true）。

示例：

curl -X POST http://localhost:3500/v1.0-alpha1/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"
        },
      ]'

头部

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

URL 参数

元数据

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

HTTP 响应

如果状态码为 500，响应体将包含一个 JSON 对象，其中包含未能送达的条目列表。例如，在我们上面的请求中，如果事件 "first text message" 的条目未能送达，响应将包含其条目 ID 和来自底层 pub/sub 组件的错误消息。

{
  "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 下，您可以提供在接收到消息主题时匹配特定条件到特定路径的规则。 您还可以为没有特定匹配的任何规则提供默认路由。

以下示例说明了这一点，考虑到主题 newOrder 的订阅和端口 3000 上的路由 orders：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 状态下的行为：

消息信封

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

相关链接

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

1.3 - 工作流 API 参考

Dapr 提供了与工作流交互的功能，并自带一个内置的 dapr 组件。

启动工作流请求

使用指定名称启动一个工作流实例，并可选地指定一个实例 ID。

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

请注意，工作流实例 ID 只能包含字母、数字、下划线和破折号。

URL 参数

请求内容

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

HTTP 响应代码

响应内容

API 调用将返回如下的响应：

{
    "instanceID": "12345678"
}

终止工作流请求

终止具有指定名称和实例 ID 的正在运行的工作流实例。

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

URL 参数

HTTP 响应代码

响应内容

此 API 不返回任何内容。

触发事件请求

对于支持订阅外部事件的工作流组件，例如 Dapr 工作流引擎，可以使用以下“触发事件”API 将命名事件传递给特定的工作流实例。

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

URL 参数

HTTP 响应代码

响应内容

无。

暂停工作流请求

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

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

URL 参数

HTTP 响应代码

响应内容

无。

恢复工作流请求

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

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

URL 参数

HTTP 响应代码

响应内容

无。

清除工作流请求

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

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

URL 参数

HTTP 响应代码

响应内容

无。

获取工作流请求

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

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

URL 参数

HTTP 响应代码

响应内容

API 调用将返回如下的 JSON 响应：

{
  "createdAt": "2023-01-12T21:31:13Z",
  "instanceID": "12345678",
  "lastUpdatedAt": "2023-01-12T21:31:13Z",
  "properties": {
    "property1": "value1",
    "property2": "value2",
  },
  "runtimeStatus": "RUNNING",
 }

组件格式

一个 Dapr workflow.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: workflow.<TYPE>
  version: v1.0-alpha1
  metadata:
  - name: <NAME>
    value: <VALUE>

然而，Dapr 附带一个内置的基于 Dapr actor 的 dapr 工作流组件。使用内置的 Dapr 工作流组件不需要组件文件。

下一步

• 工作流 API 概述
• 将用户路由到工作流模式

1.4 - 状态管理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运行时将ETags视为不透明字符串。确切的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参数

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

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

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

请求头

HTTP响应

响应代码

响应体

无。

示例

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

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

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

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

响应代码

响应体

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

URL参数

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

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

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

请求体

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

每个操作都有一个关联的request，由以下字段组成：

示例

下面的示例显示了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使用带有ETags的乐观并发控制（OCC）。Dapr对状态存储提出以下可选要求：

• 一个Dapr兼容的状态存储可以支持使用ETags的乐观并发控制。存储允许在ETag：
  • 与保存或删除请求相关联时。
  • 匹配数据库中的最新ETag时。
• 当写请求中缺少ETag时，状态存储应以最后写入优先的方式处理请求。这允许对高吞吐量写入场景进行优化，其中数据争用较低或没有负面影响。
• 存储在返回状态给调用者时应始终返回ETags。

一致性

Dapr允许客户端将一致性提示附加到获取、设置和删除操作。Dapr支持两种一致性级别：强一致性和最终一致性。

最终一致性

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

• 对于读取请求，从任何副本返回数据。
• 对于写入请求，在确认更新请求后异步复制更新到配置的法定人数。

强一致性

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

• 对于读取请求，始终返回跨副本一致的最新数据。
• 对于写入/删除请求，在完成写入请求之前同步复制更新的数据到配置的法定人数。

示例：完整选项请求示例

以下是一个带有完整options定义的设置请求示例：

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"
          }
        }
      ]'

示例：使用ETags

以下是一个在兼容状态存储中设置/删除对象时使用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将允许请求。

   # 更新
   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"}
   
   # 删除
   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，未来的更新或删除将需要使用。

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

下一步

• 状态管理概述
• 如何：保存和获取状态

1.5 - Bindings API 参考

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

bindings 的示例包括 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 组件文件中放置密码或秘密。有关使用 secret 存储安全存储和检索秘密的信息，请参阅 设置 Secret Store

绑定方向（可选）

在某些情况下，向 Dapr 提供额外的信息以指示绑定组件支持的方向是有帮助的。

指定绑定的 direction 可以帮助 Dapr sidecar 避免进入“等待应用程序准备就绪”的状态，这种状态下它会无限期地等待应用程序可用。这解耦了 Dapr sidecar 和应用程序之间的生命周期依赖。

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

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

以下是一些 direction 元数据字段可能有帮助的场景：

• 当一个应用程序（与 sidecar 分离）作为无服务器工作负载运行并缩放到零时，Dapr sidecar 执行的“等待应用程序准备就绪”检查变得毫无意义。

• 如果分离的 Dapr sidecar 缩放到零，并且应用程序在启动 HTTP 服务器之前到达 sidecar，“等待应用程序准备就绪”会导致应用程序和 sidecar 互相等待而陷入死锁。

示例

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

绑定端点

bindings 是从组件 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 bindings 支持各种操作，例如 create。

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

HTTP 请求

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

HTTP 响应代码

负载

bindings 端点接收以下 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.6 - Actors API 参考

Dapr 提供了原生、跨平台和跨语言的虚拟 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 社区电话会议 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 秒的周期。

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

dueTime 为 0 表示立即触发。以下请求体表示立即触发，然后每 9 秒触发一次。

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

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

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

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

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

需要对数据进行描述。

{
  "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 秒的周期。

{
  "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 的 stormtrooper actor 类型。

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 的 stormtrooper actor 类型的 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 的 stormtrooper actor 类型的 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 的 stormtrooper actor 类型的 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

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

1.7 - Secrets API 参考

获取 Secret

此接口允许您获取指定 secret 存储中的 secret 值。

HTTP 请求

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

URL 参数

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

查询参数

某些 secret 存储支持可选的、每个请求的元数据属性。您可以通过查询参数来提供这些属性。例如：

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

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

• Hashicorp Vault、GCP Secret Manager 和 AWS Secret Manager 支持 version_id 参数
• 只有 AWS Secret Manager 支持 version_stage 参数
• 只有 Kubernetes Secrets 支持 namespace 参数 请查阅每个 secret 存储的文档 以获取支持的参数列表。

HTTP 响应

响应体

如果 secret 存储支持 secret 中的多个键值，将返回一个 JSON 负载，其中键名作为字段及其各自的值。

如果 secret 存储仅具有名称/值语义，将返回一个 JSON 负载，其中 secret 的名称作为字段，secret 的值作为值。

查看支持 secret 中多个键和名称/值语义的 secret 存储的分类。

secret 中有多个键的响应（例如 Kubernetes）：

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

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

上面的示例展示了来自具有多个键的 secret 存储的响应。请注意，secret 名称 (db-secret) 不作为结果的一部分返回。

具有名称/值语义的 secret 存储的响应：

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

{
  "db-secret": "value1"
}

上面的示例展示了来自具有名称/值语义的 secret 存储的响应。与来自具有多个键的 secret 存储的结果相比，此结果返回一个键值对，其中 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 存储中的所有 secret。 建议为 Dapr 配置 secret 存储时使用 令牌认证。

HTTP 请求

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

URL 参数

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

HTTP 响应

响应体

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

具有多个 secrets 和 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.8 - 配置 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"
        }
    ]
}

下一步

• 配置 API 概述
• 如何：从存储管理配置

1.9 - 分布式锁 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.10 - 健康 API 参考

Dapr 提供健康检查功能，用于检查 Dapr 的就绪状态或存活状态，以及从 SDKs 检查初始化的就绪性。

获取 Dapr 健康状态

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

• 检查 sidecar 的健康状况
• 检查 sidecar 的健康状况，包括组件的就绪性，适用于初始化期间。

等待 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 sidecar 的 API，例如使用 secret API 读取机密信息。在 Dapr SDKs 中，可以使用 waitForSidecar 方法（例如 .NET 和 Java SDKs）来检查 sidecar 是否已正确初始化，以便进行后续调用。

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

目前，v1.0/healthz/outbound 端点在以下 SDK 中支持：

• .NET SDK
• Java SDK
• Python SDK
• JavaScript SDK

HTTP 请求

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

HTTP 响应代码

URL 参数

示例

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

相关文章

• Sidecar 健康
• 应用程序健康

1.11 - 元数据 API 参考

Dapr 提供了一个元数据 API，可以返回有关 sidecar 的信息，从而支持运行时发现。元数据端点返回以下信息：

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

元数据 API

组件

每个加载的组件提供其名称、类型和版本，以及支持的功能信息。这些功能适用于 state store 和 binding 组件类型。下表显示了给定版本的组件类型和能力列表。此列表可能会在将来扩展，仅代表当前已加载组件的能力。

HTTPEndpoints

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

订阅

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

启用的功能

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

应用程序连接详细信息

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

属性

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

获取 Dapr sidecar 信息

从元数据端点获取 Dapr sidecar 信息。

用例：

获取元数据 API 可用于发现已加载组件支持的不同能力。它可以帮助操作员确定要为所需能力提供哪些组件。

HTTP 请求

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

URL 参数

HTTP 响应代码

HTTP 响应体

元数据 API 响应对象

元数据 API 响应注册的 actor

元数据 API 响应组件

元数据 API 响应 HttpEndpoint

元数据 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
    }
  }
}

向 Dapr sidecar 信息添加自定义标签

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

用例：

例如，元数据端点被 Dapr CLI 用于在 selfhost 模式下运行 Dapr 时存储托管 sidecar 的进程的 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
    }
  }
}

1.12 - Placement API 参考

Dapr 提供了一个 HTTP API /placement/state，用于 Placement 服务，公开 placement 表信息。该 API 在 sidecar 上与 healthz 使用相同的端口。这是一个未经身份验证的端点，默认情况下是禁用的。

要在自托管模式下启用 placement 元数据，可以设置 DAPR_PLACEMENT_METADATA_ENABLED 环境变量为 true，或者在 Placement 服务上使用 metadata-enabled 命令行参数。请参阅如何在自托管模式下运行 Placement 服务。

如果您在 Kubernetes 上使用 Helm 部署 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.13 - 加密 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-stream" \ 
    --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.14 - 作业API参考

使用作业API，您可以预定未来的作业和任务。

HTTP API仅供开发和测试使用。在生产环境中，强烈推荐使用SDK，因为它们实现了gRPC API，提供比HTTP API更高的性能和功能。

调度作业

通过名称来调度作业。

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

URL参数

schedule

schedule接受systemd计时器风格的cron表达式，以及以’@‘为前缀的人类可读周期字符串。

systemd计时器风格的cron表达式包含6个字段：

示例 1

“0 30 * * * *” - 每小时的30分钟

示例 2

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

周期字符串表达式：