Dapr API 文档指南 on Dapr 文档库

服务调用API参考

Mon, 01 Jan 0001 00:00:00 +0000

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。

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

URL参数

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

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

请求内容

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

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

在请求体中放置您想要发送给服务的数据：

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

被调用服务接收到的请求

一旦您的服务代码在另一个启用了Dapr的应用或非Dapr端点中调用了方法，Dapr会在<method-name>端点上发送请求，并附带头信息和请求体。

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

跨命名空间调用

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

myApp.production

支持命名空间的平台

Kubernetes

示例

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

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

mathService服务需要在/add端点上监听以接收和处理请求。

发布/订阅 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

向指定主题发布消息

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

HTTP 请求

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

HTTP 响应代码

代码	描述
204	消息已送达
403	访问控制禁止消息
404	未提供 pubsub 名称或主题
500	传递失败

URL 参数

参数	描述
`daprPort`	Dapr 端口
`pubsubname`	pubsub 组件的名称
`topic`	主题的名称
`metadata`	查询参数，用于元数据，如下所述

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

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

头部

Content-Type 头部告知 Dapr 在构建 CloudEvent 信封时您的数据遵循哪种内容类型。Content-Type 头部的值填充 CloudEvent 中的 datacontenttype 字段。

除非指定，否则 Dapr 假定为 text/plain。如果您的内容类型是 JSON，请使用值为 application/json 的 Content-Type 头部。

工作流 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

启动工作流请求

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

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

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

URL 参数

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

请求内容

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

HTTP 响应代码

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

响应内容

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

{
 "instanceID": "12345678"
}

终止工作流请求

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

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

注意

终止一个工作流将同时终止该实例创建的所有子工作流。

终止一个工作流不会影响由该实例启动的任何正在进行的活动。

URL 参数

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

HTTP 响应代码

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

响应内容

此 API 不返回任何内容。

状态管理API参考

Mon, 01 Jan 0001 00:00:00 +0000

组件文件

Dapr的statestore.yaml组件文件结构如下：

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

设置	描述
`metadata.name`	状态存储的名称。
`spec/metadata`	一个开放的键值对元数据，允许绑定定义连接属性。

键方案

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

<App ID>||<state key>

对于actor状态，键格式为：

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

保存状态

通过该端点可以保存一组状态对象。

HTTP请求

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

URL参数

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

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

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

所有URL参数区分大小写。

由于||是用作键方案中的分隔符，因此不能在<state key>字段中使用。

请求体

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

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

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

Bindings API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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 提供额外的信息以指示绑定组件支持的方向是有帮助的。

Actors API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

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

URL 参数

参数	描述
`daprPort`	Dapr 端口。
`actorType`	actor 类型。
`actorId`	actor ID。
`method`	要调用的方法名称。

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

示例

调用 actor 上的方法示例：

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

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

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

或

Secrets API 参考

Mon, 01 Jan 0001 00:00:00 +0000

获取 Secret

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

HTTP 请求

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

URL 参数

参数	描述
daprPort	Dapr 端口
secret-store-name	要从中获取 secret 的 secret 存储名称
name	要获取的 secret 名称

请注意，所有 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 负载，其中键名作为字段及其各自的值。

配置 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

获取配置

该端点用于从存储中获取配置。

HTTP 请求

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

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段组件文件。请参阅组件规范

查询参数

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

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

要检索所有配置项：

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

请求体

无

HTTP 响应

响应代码

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

响应体

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

示例

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

上述命令返回以下 JSON：

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

订阅配置

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

HTTP 请求

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

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段组件文件。请参阅组件规范

查询参数

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

分布式锁 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

锁

通过此端点，您可以通过提供锁所有者的名称和要锁定的资源 ID 来获取锁。

HTTP 请求

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

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段的组件文件。请参阅组件模式

查询参数

无

HTTP 响应代码

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

HTTP 请求体

锁端点需要接收以下 JSON 负载：

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

字段	描述
resourceId	要锁定的资源 ID。可以是任何值
lockOwner	锁所有者的名称。每次请求都应设置为唯一值
expiryInSeconds	锁定在过期前保持的时间（秒）

HTTP 响应体

锁端点会返回以下负载：

{
 "success": true
}

示例

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

{
 "success": "true"
}

解锁

通过此端点，您可以根据锁所有者和资源 ID 解锁现有锁。

健康 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

获取 Dapr 健康状态

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

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

等待 Dapr HTTP 端口可用

等待所有组件初始化完成，Dapr HTTP 端口可用，同时应用程序通道已初始化。例如，此端点用于 Kubernetes 的存活性探针。

HTTP 请求

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

HTTP 响应代码

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

URL 参数

参数	描述
daprPort	Dapr 端口

示例

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

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

等待所有组件初始化完成，Dapr HTTP 端口可用，但应用程序通道尚未建立。此端点允许您的应用程序在应用程序通道初始化之前调用 Dapr sidecar 的 API，例如使用 secret API 读取机密信息。在 Dapr SDKs 中，可以使用 waitForSidecar 方法（例如 .NET 和 Java SDKs）来检查 sidecar 是否已正确初始化，以便进行后续调用。

元数据 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

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

元数据 API

组件

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

组件类型	能力
State Store	ETAG, TRANSACTION, ACTOR, QUERY_API
Binding	INPUT_BINDING, OUTPUT_BINDING

HTTPEndpoints

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

启用的功能

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

应用程序连接详细信息

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

属性

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

获取 Dapr sidecar 信息

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

Placement API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

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

重要

在多租户模式下运行 placement 时，请禁用 metadata-enabled 命令行参数，以防止不同命名空间之间的数据泄露。

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

使用场景

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

HTTP 请求

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

HTTP 响应代码

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

HTTP 响应体

Placement 表 API 响应对象

加密 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

请求头

通过设置请求头来配置其他加密参数。下表详细说明了每个加密请求需要设置的必需和可选请求头。

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

HTTP 响应

响应体

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

作业API参考

Mon, 01 Jan 0001 00:00:00 +0000

注意

作业API目前处于测试阶段。

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

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

调度作业

通过名称来调度作业。

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

URL参数

注意

必须提供schedule或dueTime中的至少一个，也可以同时提供。

参数	描述
`name`	您正在调度的作业的名称
`data`	一个JSON格式的值或对象。
`schedule`	作业的可选计划。格式详情如下。
`dueTime`	作业应激活的时间，或"一次性"时间，如果未提供其他调度类型字段。接受RFC3339格式的时间字符串、Go持续时间字符串（从创建时间计算）或非重复的ISO8601格式。
`repeats`	作业应触发的次数。如果未设置，作业将无限期运行或直到过期。
`ttl`	作业的生存时间或过期时间。接受RFC3339格式的时间字符串、Go持续时间字符串（从作业创建时间计算）或非重复的ISO8601格式。

schedule

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

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

秒	分钟	小时	月中的某天	月份	星期中的某天
0-59	0-59	0-23	1-31	1-12/jan-dec	0-6/sun-sat

示例 1

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

示例 2

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

周期字符串表达式：

条目	描述	等同于
@every	每隔运行一次 (例如 ‘@every 1h30m’)	N/A
@yearly (或 @annually)	每年运行一次，午夜，1月1日	0 0 0 1 1 *
@monthly	每月运行一次，午夜，月初	0 0 0 1 * *
@weekly	每周运行一次，周日午夜	0 0 0 * * 0
@daily (或 @midnight)	每天运行一次，午夜	0 0 0 * * *
@hourly	每小时运行一次，整点	0 0 * * * *

请求体

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

HTTP响应代码

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

响应内容

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

会话API参考

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

会话API目前为alpha阶段。

Dapr提供了一种API，用于与大型语言模型（LLMs）进行交互。通过提示缓存和模糊化个人身份信息（PII）等功能，提升了性能和安全性。

会话

通过此端点可以与LLMs进行会话。

POST /v1.0-alpha1/conversation/<llm-name>/converse

URL参数

参数	描述
`llm-name`	LLM组件的名称。查看所有可用会话组件的列表。

请求体

字段	描述
`conversationContext`	会话的上下文信息，用于维持对话状态。
`inputs`	用户输入的文本数组。
`parameters`	额外的参数配置。

请求示例

REQUEST = {
 "inputs": ["什么是Dapr", "为什么使用Dapr"],
 "parameters": {},
}

HTTP响应代码

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

响应示例

RESPONSE = {
 "outputs": [
 {
 "result": "Dapr是分布式应用运行时...",
 "parameters": {},
 },
 {
 "result": "Dapr可以帮助开发者...",
 "parameters": {},
 }
 ],
}

下一步

会话API概述