This is the multi-page printable view of this section. Click here to print.
Dapr API 文档指南
- 1: 服务调用API参考
- 2: 发布/订阅 API 参考
- 3: 工作流 API 参考
- 4: 状态管理API参考
- 5: Bindings API 参考
- 6: Actors API 参考
- 7: Secrets API 参考
- 8: 配置 API 参考
- 9: 分布式锁 API 参考
- 10: 健康 API 参考
- 11: 元数据 API 参考
- 12: Placement API 参考
- 13: 加密 API 参考
- 14: 作业API参考
- 15: 会话API参考
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
。
代码 | 描述 |
---|---|
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
端点上监听以接收和处理请求。
对于一个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}'
下一步
2 - 发布/订阅 API 参考
向指定主题发布消息
此端点允许您将数据发布到多个正在监听某个 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
头部。
如果您想发送自定义的 CloudEvent,请为 Content-Type
头部使用 application/cloudevents+json
值。
元数据
元数据可以通过请求 URL 中的查询参数发送。它必须以 metadata.
为前缀,如下所示。
参数 | 描述 |
---|---|
metadata.ttlInSeconds |
消息过期的秒数,如此处所述 |
metadata.rawPayload |
布尔值,决定 Dapr 是否应在不将事件包装为 CloudEvent 的情况下发布事件,如此处所述 |
根据每个 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 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口 |
pubsubname |
发布/订阅组件的名称 |
topic |
主题的名称 |
metadata |
元数据的查询参数 |
元数据
元数据可以通过请求 URL 中的查询参数发送。它必须以 metadata.
为前缀,如下表所示。
参数 | 描述 |
---|---|
metadata.rawPayload |
布尔值,决定 Dapr 是否应在不将消息包装为 CloudEvent 的情况下发布消息。 |
metadata.maxBulkPubBytes |
批量发布请求中要发布的最大字节数。 |
HTTP 响应
HTTP 状态 | 描述 |
---|---|
204 | 所有消息已送达 |
400 | 发布/订阅不存在 |
403 | 访问控制禁止 |
500 | 至少一条消息未能送达 |
如果状态码为 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 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口 |
HTTP 响应体
一个 JSON 编码的字符串数组。
示例:
[
{
"pubsubname": "pubsub",
"topic": "newOrder",
"routes": {
"rules": [
{
"match": "event.type == order",
"path": "/orders"
}
]
"default" : "/otherorders"
},
"metadata": {
"rawPayload": "true"
}
}
]
注意,所有订阅参数区分大小写。
元数据
可选地,元数据可以通过请求体发送。
参数 | 描述 |
---|---|
rawPayload |
布尔值,订阅不符合 CloudEvent 规范的事件,如此处所述 |
提供路由以供 Dapr 传递主题事件
为了传递主题事件,将使用订阅响应中指定的路由对用户代码进行 POST
调用。在 routes
下,您可以提供在接收到消息主题时匹配特定条件到特定路径的规则。 您还可以为没有特定匹配的任何规则提供默认路由。
以下示例说明了这一点,考虑到主题 newOrder
的订阅和端口 3000 上的路由 orders
:POST http://localhost:3000/orders
HTTP 请求
POST http://localhost:<appPort>/<path>
注意,所有 URL 参数区分大小写。
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口 |
path |
订阅配置中的路由路径 |
预期的 HTTP 响应
HTTP 2xx 响应表示消息处理成功。
为了更丰富的响应处理,可以发送一个带有处理状态的 JSON 编码的负载体:
{
"status": "<status>"
}
状态 | 描述 |
---|---|
SUCCESS |
消息处理成功 |
RETRY |
消息由 Dapr 重试 |
DROP |
记录警告并丢弃消息 |
其他 | 错误,消息由 Dapr 重试 |
Dapr 假定没有 status
字段的 JSON 编码负载响应或带有 HTTP 2xx 的空负载响应为 SUCCESS
。
HTTP 响应可能与 HTTP 2xx 不同。以下是 Dapr 在不同 HTTP 状态下的行为:
HTTP 状态 | 描述 |
---|---|
2xx | 消息根据负载中的状态处理(如果为空则为 SUCCESS ;如果负载无效则忽略)。 |
404 | 记录错误并丢弃消息 |
其他 | 记录警告并重试消息 |
从指定主题订阅多条消息
这允许您在监听某个 topic
时从代理订阅多条消息。
为了以批量方式接收主题订阅中的消息,应用程序:
- 需要在发送要订阅的主题列表时选择
bulkSubscribe
- 可选地,可以配置
maxMessagesCount
和/或maxAwaitDurationMs
有关如何选择的更多详细信息,请参阅批量发送和接收消息指南。
批量订阅的预期 HTTP 响应
HTTP 2xx 响应表示应用程序已处理此批量消息中的条目(单个消息),Dapr 现在将检查每个 EntryId 状态。 需要发送一个带有每个条目处理状态的 JSON 编码负载体:
{
"statuses":
[
{
"entryId": "<entryId1>",
"status": "<status>"
},
{
"entryId": "<entryId2>",
"status": "<status>"
}
]
}
注意:如果 Dapr 在从应用程序接收到的响应中找不到 EntryId 状态,则该条目的状态被视为
RETRY
。
状态 | 描述 |
---|---|
SUCCESS |
消息处理成功 |
RETRY |
消息由 Dapr 重试 |
DROP |
记录警告并丢弃消息 |
HTTP 响应可能与 HTTP 2xx 不同。以下是 Dapr 在不同 HTTP 状态下的行为:
HTTP 状态 | 描述 |
---|---|
2xx | 消息根据负载中的状态处理。 |
404 | 记录错误并丢弃所有消息 |
其他 | 记录警告并重试所有消息 |
消息信封
Dapr 发布/订阅遵循 CloudEvents 1.0 版本。
相关链接
3 - 工作流 API 参考
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 不返回任何内容。
触发事件请求
对于支持订阅外部事件的工作流组件,例如 Dapr 工作流引擎,可以使用以下“触发事件”API 将命名事件传递给特定的工作流实例。
POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceID>/raiseEvent/<eventName>
注意
订阅事件的具体机制取决于您使用的工作流组件。Dapr 工作流有一种订阅外部事件的方式,但其他工作流组件可能有不同的方式。URL 参数
参数 | 描述 |
---|---|
workflowComponentName |
对于 Dapr 工作流使用 dapr |
instanceId |
为特定工作流的每次运行创建的唯一值 |
eventName |
要触发的事件名称 |
HTTP 响应代码
代码 | 描述 |
---|---|
202 |
已接受 |
400 |
请求格式错误 |
500 |
请求格式正确,但 Dapr 代码或底层组件出错 |
响应内容
无。
暂停工作流请求
暂停一个正在运行的工作流实例。
POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceId>/pause
URL 参数
参数 | 描述 |
---|---|
workflowComponentName |
对于 Dapr 工作流使用 dapr |
instanceId |
为特定工作流的每次运行创建的唯一值 |
HTTP 响应代码
代码 | 描述 |
---|---|
202 |
已接受 |
400 |
请求格式错误 |
500 |
Dapr 代码或底层组件出错 |
响应内容
无。
恢复工作流请求
恢复一个已暂停的工作流实例。
POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceId>/resume
URL 参数
参数 | 描述 |
---|---|
workflowComponentName |
对于 Dapr 工作流使用 dapr |
instanceId |
为特定工作流的每次运行创建的唯一值 |
HTTP 响应代码
代码 | 描述 |
---|---|
202 |
已接受 |
400 |
请求格式错误 |
500 |
Dapr 代码或底层组件出错 |
响应内容
无。
清除工作流请求
使用工作流的实例 ID 从您的状态存储中清除工作流状态。
POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceId>/purge
注意
只有状态为COMPLETED
、FAILED
或 TERMINATED
的工作流可以被清除。
URL 参数
参数 | 描述 |
---|---|
workflowComponentName |
对于 Dapr 工作流使用 dapr |
instanceId |
为特定工作流的每次运行创建的唯一值 |
HTTP 响应代码
代码 | 描述 |
---|---|
202 |
已接受 |
400 |
请求格式错误 |
500 |
Dapr 代码或底层组件出错 |
响应内容
无。
获取工作流请求
获取给定工作流实例的信息。
GET http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceId>
URL 参数
参数 | 描述 |
---|---|
workflowComponentName |
对于 Dapr 工作流使用 dapr |
instanceId |
为特定工作流的每次运行创建的唯一值 |
HTTP 响应代码
代码 | 描述 |
---|---|
200 |
正常 |
400 |
请求格式错误 |
500 |
请求格式正确,但 Dapr 代码或底层组件出错 |
响应内容
API 调用将返回如下的 JSON 响应:
{
"createdAt": "2023-01-12T21:31:13Z",
"instanceID": "12345678",
"lastUpdatedAt": "2023-01-12T21:31:13Z",
"properties": {
"property1": "value1",
"property2": "value2",
},
"runtimeStatus": "RUNNING",
}
参数 | 描述 |
---|---|
runtimeStatus |
工作流实例的状态。值包括:"RUNNING" 、"COMPLETED" 、"CONTINUED_AS_NEW" 、"FAILED" 、"CANCELED" 、"TERMINATED" 、"PENDING" 、"SUSPENDED" |
组件格式
一个 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>
设置 | 描述 |
---|---|
metadata.name |
工作流组件的名称。 |
spec/metadata |
由工作流组件指定的附加元数据参数 |
然而,Dapr 附带一个内置的基于 Dapr actor 的 dapr
工作流组件。使用内置的 Dapr 工作流组件不需要组件文件。
下一步
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>
设置 | 描述 |
---|---|
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格式由相应的数据存储定义。
元数据
元数据可以通过请求的URL中的查询参数发送。它必须以metadata.
为前缀,如下所示。
参数 | 描述 |
---|---|
metadata.ttlInSeconds |
消息过期的秒数,如此处所述 |
TTL: 只有某些状态存储支持TTL选项,根据支持的状态存储。
HTTP响应
响应代码
代码 | 描述 |
---|---|
204 |
状态已保存 |
400 |
状态存储缺失或配置错误或请求格式错误 |
500 |
保存状态失败 |
响应体
无。
示例
curl -X POST http://localhost:3500/v1.0/state/starwars?metadata.contentType=application/json \
-H "Content-Type: application/json" \
-d '[
{
"key": "weapon",
"value": "DeathStar",
"etag": "1234"
},
{
"key": "planet",
"value": {
"name": "Tatooine"
}
}
]'
获取状态
通过该端点可以获取特定键的状态。
HTTP请求
GET http://localhost:<daprPort>/v1.0/state/<storename>/<key>
URL参数
参数 | 描述 |
---|---|
daprPort |
Dapr端口 |
storename |
用户配置的statestore.yaml组件文件中的metadata.name 字段。请参阅上面提到的Dapr状态存储配置结构。 |
key |
所需状态的键 |
consistency |
(可选)读取一致性模式;请参阅状态操作选项 |
metadata |
(可选)作为查询参数传递给状态存储的元数据 |
可选的请求元数据通过URL查询参数传递。例如,
GET http://localhost:3500/v1.0/state/myStore/myKey?metadata.contentType=application/json
注意,所有URL参数区分大小写。
HTTP响应
响应代码
代码 | 描述 |
---|---|
200 |
获取状态成功 |
204 |
找不到键 |
400 |
状态存储缺失或配置错误 |
500 |
获取状态失败 |
响应头
头 | 描述 |
---|---|
ETag |
返回值的ETag |
响应体
JSON编码的值
示例
curl http://localhost:3500/v1.0/state/starwars/planet?metadata.contentType=application/json
上述命令返回状态:
{
"name": "Tatooine"
}
要将元数据作为查询参数传递:
GET http://localhost:3500/v1.0/state/starwars/planet?metadata.partitionKey=mypartitionKey&metadata.contentType=application/json
获取批量状态
通过该端点可以获取给定键列表的值列表。
HTTP请求
POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/bulk
URL参数
参数 | 描述 |
---|---|
daprPort |
Dapr端口 |
storename |
用户配置的statestore.yaml组件文件中的metadata.name 字段。请参阅上面提到的Dapr状态存储配置结构。 |
metadata |
(可选)作为查询参数传递给状态存储的元数据 |
可选的请求元数据通过URL查询参数传递。例如,
POST/PUT http://localhost:3500/v1.0/state/myStore/bulk?metadata.partitionKey=mypartitionKey
注意,所有URL参数区分大小写。
HTTP响应
响应代码
代码 | 描述 |
---|---|
200 |
获取状态成功 |
400 |
状态存储缺失或配置错误 |
500 |
获取批量状态失败 |
响应体
一个JSON编码的值数组
示例
curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
-H "Content-Type: application/json" \
-d '{
"keys": [ "key1", "key2" ],
"parallelism": 10
}'
上述命令返回一个键/值对象数组:
[
{
"key": "key1",
"value": "value1",
"etag": "1"
},
{
"key": "key2",
"value": "value2",
"etag": "1"
}
]
要将元数据作为查询参数传递:
POST http://localhost:3500/v1.0/state/myRedisStore/bulk?metadata.partitionKey=mypartitionKey
删除状态
通过该端点可以删除特定键的状态。
HTTP请求
DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>
URL参数
参数 | 描述 |
---|---|
daprPort |
Dapr端口 |
storename |
用户配置的statestore.yaml组件文件中的metadata.name 字段。请参阅上面提到的Dapr状态存储配置结构。 |
key |
所需状态的键 |
concurrency |
(可选)first-write或last-write;请参阅状态操作选项 |
consistency |
(可选)strong或eventual;请参阅状态操作选项 |
可选的请求元数据通过URL查询参数传递。例如,
DELETE http://localhost:3500/v1.0/state/myStore/myKey?metadata.contentType=application/json
注意,所有URL参数区分大小写。
请求头
头 | 描述 |
---|---|
If-Match | (可选)与要删除的键关联的ETag |
HTTP响应
响应代码
代码 | 描述 |
---|---|
204 |
删除状态成功 |
400 |
状态存储缺失或配置错误 |
500 |
删除状态失败 |
响应体
无。
示例
curl -X DELETE http://localhost:3500/v1.0/state/starwars/planet -H "If-Match: xxxxxxx"
查询状态
通过该端点可以查询键/值状态。
alpha
此API处于alpha阶段。HTTP请求
POST/PUT http://localhost:<daprPort>/v1.0-alpha1/state/<storename>/query
URL参数
参数 | 描述 |
---|---|
daprPort |
Dapr端口 |
storename |
用户配置的statestore.yaml组件文件中的metadata.name 字段。请参阅上面提到的Dapr状态存储配置结构。 |
metadata |
(可选)作为查询参数传递给状态存储的元数据 |
可选的请求元数据通过URL查询参数传递。例如,
POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.contentType=application/json
注意,所有URL参数区分大小写。
响应代码
代码 | 描述 |
---|---|
200 |
状态查询成功 |
400 |
状态存储缺失或配置错误 |
500 |
状态查询失败 |
响应体
一个JSON编码的值数组
示例
curl -X POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.contentType=application/json \
-H "Content-Type: application/json" \
-d '{
"filter": {
"OR": [
{
"EQ": { "person.org": "Dev Ops" }
},
{
"AND": [
{
"EQ": { "person.org": "Finance" }
},
{
"IN": { "state": [ "CA", "WA" ] }
}
]
}
]
},
"sort": [
{
"key": "state",
"order": "DESC"
},
{
"key": "person.id"
}
],
"page": {
"limit": 3
}
}'
上述命令返回一个对象数组以及一个令牌:
{
"results": [
{
"key": "1",
"data": {
"person": {
"org": "Dev Ops",
"id": 1036
},
"city": "Seattle",
"state": "WA"
},
"etag": "6f54ad94-dfb9-46f0-a371-e42d550adb7d"
},
{
"key": "4",
"data": {
"person": {
"org": "Dev Ops",
"id": 1042
},
"city": "Spokane",
"state": "WA"
},
"etag": "7415707b-82ce-44d0-bf15-6dc6305af3b1"
},
{
"key": "10",
"data": {
"person": {
"org": "Dev Ops",
"id": 1054
},
"city": "New York",
"state": "NY"
},
"etag": "26bbba88-9461-48d1-8a35-db07c374e5aa"
}
],
"token": "3"
}
要将元数据作为查询参数传递:
POST http://localhost:3500/v1.0-alpha1/state/myStore/query?metadata.partitionKey=mypartitionKey
状态事务
将更改持久化到状态存储作为事务操作。
此API依赖于支持事务的状态存储组件。
请参阅状态存储组件规范以获取支持事务的状态存储的完整、当前列表。
HTTP请求
POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/transaction
HTTP响应代码
代码 | 描述 |
---|---|
204 |
请求成功 |
400 |
状态存储缺失或配置错误或请求格式错误 |
500 |
请求失败 |
URL参数
参数 | 描述 |
---|---|
daprPort |
Dapr端口 |
storename |
用户配置的statestore.yaml组件文件中的metadata.name 字段。请参阅上面提到的Dapr状态存储配置结构。 |
可选的请求元数据通过URL查询参数传递。例如,
POST http://localhost:3500/v1.0/state/myStore/transaction?metadata.contentType=application/json
注意,所有URL参数区分大小写。
请求体
字段 | 描述 |
---|---|
operations |
状态operation 的JSON数组 |
metadata |
(可选)适用于所有操作的事务metadata |
所有事务性数据库实现以下必需操作:
操作 | 描述 |
---|---|
upsert |
添加或更新值 |
delete |
删除值 |
每个操作都有一个关联的request
,由以下字段组成:
请求 | 描述 |
---|---|
key |
状态键 |
value |
状态值,可以是任何字节数组 |
etag |
(可选)状态ETag |
metadata |
(可选)要传递给状态存储的附加键值对,适用于此操作 |
options |
(可选)状态操作选项;请参阅状态操作选项 |
示例
下面的示例显示了key1
的upsert
操作和key2
的delete
操作。这适用于状态存储中名为’planet’的分区。两个操作在事务中要么成功要么失败。
curl -X POST http://localhost:3500/v1.0/state/starwars/transaction \
-H "Content-Type: application/json" \
-d '{
"operations": [
{
"operation": "upsert",
"request": {
"key": "key1",
"value": "myData"
}
},
{
"operation": "delete",
"request": {
"key": "key2"
}
}
],
"metadata": {
"partitionKey": "planet"
}
}'
为actor配置状态存储
actor不支持多个状态存储,并且需要使用事务性状态存储与Dapr一起使用。查看当前实现事务性状态存储接口的服务。
在statestore.yaml
组件文件的元数据部分中为属性actorStateStore
指定一个true
值,以指定用于actor的状态存储。
例如,以下组件yaml将配置Redis用作actor的状态存储。
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <redis host>
- name: redisPassword
value: ""
- name: actorStateStore
value: "true"
可选行为
键方案
一个Dapr兼容的状态存储应使用以下键方案:
- <App ID>||<state key> 键格式用于一般状态
- <App ID>||<Actor type>||<Actor id>||<state key> 键格式用于actor状态。
并发
Dapr使用带有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
。
-
在状态存储中存储一个对象:
curl -X POST http://localhost:3500/v1.0/state/statestore \ -H "Content-Type: application/json" \ -d '[ { "key": "sampleData", "value": "1" } ]'
-
获取对象以查找由状态存储自动设置的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"}
-
通过简单地在请求体(更新)或
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
下一步
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
属性。
以下是一些 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 响应代码
代码 | 描述 |
---|---|
404 | 应用程序不想绑定到该绑定 |
2xx 或 405 | 应用程序想要绑定到该绑定 |
URL 参数
参数 | 描述 |
---|---|
appPort | 应用程序端口 |
name | 绑定的名称 |
注意,所有 URL 参数区分大小写。
绑定负载
为了传递绑定输入,会向用户代码发出一个以绑定名称为 URL 路径的 POST 调用。
HTTP 请求
POST http://localhost:<appPort>/<name>
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 应用程序成功处理了输入绑定 |
URL 参数
参数 | 描述 |
---|---|
appPort | 应用程序端口 |
name | 绑定的名称 |
注意,所有 URL 参数区分大小写。
HTTP 响应体(可选)
可选地,可以使用响应体直接将输入绑定与状态存储或输出绑定绑定。
示例:
Dapr 将 stateDataToStore
存储到名为 “stateStore” 的状态存储中。
Dapr 将 jsonObject
并行发送到名为 “storage” 和 “queue” 的输出绑定。
如果未设置 concurrency
,则按顺序发送(下面的示例显示这些操作是并行完成的)
{
"storeName": "stateStore",
"state": stateDataToStore,
"to": ['storage', 'queue'],
"concurrency": "parallel",
"data": jsonObject,
}
调用输出绑定
此端点允许您调用 Dapr 输出绑定。Dapr bindings 支持各种操作,例如 create
。
请参阅每个绑定的不同规范以查看支持的操作列表。
HTTP 请求
POST/PUT http://localhost:<daprPort>/v1.0/bindings/<name>
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
204 | 空响应 |
400 | 请求格式错误 |
500 | 请求失败 |
负载
bindings 端点接收以下 JSON 负载:
{
"data": "",
"metadata": {
"": ""
},
"operation": ""
}
注意,所有 URL 参数区分大小写。
data
字段接受任何 JSON 可序列化的值,并作为要发送到输出绑定的负载。metadata
字段是一个键/值对数组,允许您为每次调用设置绑定特定的元数据。operation
字段告诉 Dapr 绑定它应该执行哪个操作。
URL 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口 |
name | 要调用的输出绑定的名称 |
注意,所有 URL 参数区分大小写。
示例
curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
-H "Content-Type: application/json" \
-d '{
"data": {
"message": "Hi"
},
"metadata": {
"key": "redis-key-1"
},
"operation": "create"
}'
常见元数据值
有一些常见的元数据属性在多个绑定组件中支持。以下列表展示了它们:
属性 | 描述 | 绑定定义 | 可用于 |
---|---|---|---|
ttlInSeconds | 定义消息的生存时间(以秒为单位) | 如果在绑定定义中设置,将导致所有消息具有默认的生存时间。消息 ttl 覆盖绑定定义中的任何值。 | RabbitMQ, Azure Service Bus, Azure Storage Queue |
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 响应代码
代码 | 描述 |
---|---|
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"
}'
或
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 响应代码
代码 | 描述 |
---|---|
204 | 请求成功 |
400 | 未找到 actor |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
注意,所有 URL 参数区分大小写。
示例
注意,以下示例使用了
ttlInSeconds
字段,这需要启用ActorStateTTL
功能。
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
-H "Content-Type: application/json" \
-d '[
{
"operation": "upsert",
"request": {
"key": "key1",
"value": "myData",
"metadata": {
"ttlInSeconds": "3600"
}
}
},
{
"operation": "delete",
"request": {
"key": "key2"
}
}
]'
获取 actor 状态
使用指定的键获取 actor 的状态。
HTTP 请求
GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
204 | 未找到键,响应将为空 |
400 | 未找到 actor |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
key |
状态值的键。 |
注意,所有 URL 参数区分大小写。
示例
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
-H "Content-Type: application/json"
上述命令返回状态:
{
"location": "Alderaan"
}
创建 actor 提醒
为 actor 创建一个持久化的提醒。
HTTP 请求
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
提醒请求体
一个包含以下字段的 JSON 对象:
字段 | 描述 |
---|---|
dueTime |
指定提醒被调用的时间。其格式应为 time.ParseDuration |
period |
指定不同调用之间的周期。其格式应为 time.ParseDuration 或带有可选重复的 ISO 8601 持续时间格式。 |
ttl |
设置计时器或提醒将在何时或间隔后过期并被删除。其格式应为 time.ParseDuration 格式、RFC3339 日期格式或 ISO 8601 持续时间格式。 |
data |
一个字符串值,可以是任何相关内容。内容在提醒过期时返回。例如,这可能用于返回 URL 或与内容相关的任何内容。 |
period
字段支持 time.Duration
格式和 ISO 8601 格式,但有一些限制。对于 period
,仅支持 ISO 8601 持续时间格式 Rn/PnYnMnWnDTnHnMnS
。Rn/
指定提醒将被调用 n
次。
n
应为大于 0 的正整数。- 如果某些值为 0,则可以缩短
period
;例如,10 秒可以在 ISO 8601 持续时间中指定为PT10S
。
如果未指定 Rn/
,则提醒将无限次运行,直到被删除。
如果仅设置了 ttl
和 dueTime
,则提醒将被接受。然而,只有 dueTime
生效。例如,提醒在 dueTime
触发,ttl
被忽略。
如果设置了 ttl
、dueTime
和 period
,则提醒首先在 dueTime
触发,然后根据 period
和 ttl
重复触发并过期。
以下示例指定了 3 秒的 dueTime
和 7 秒的周期。
{
"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 响应代码
代码 | 描述 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
400 | 未找到 actor 或请求格式错误 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
name |
要创建的提醒名称。 |
注意,所有 URL 参数区分大小写。
示例
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-H "Content-Type: application/json" \
-d '{
"data": "someData",
"dueTime": "1m",
"period": "20s"
}'
获取 actor 提醒
获取 actor 的提醒。
HTTP 请求
GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
name |
要获取的提醒名称。 |
注意,所有 URL 参数区分大小写。
示例
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
"Content-Type: application/json"
上述命令返回提醒:
{
"dueTime": "1s",
"period": "5s",
"data": "0",
}
删除 actor 提醒
删除 actor 的提醒。
HTTP 请求
DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
HTTP 响应代码
代码 | 描述 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
name |
要删除的提醒名称。 |
注意,所有 URL 参数区分大小写。
示例
curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-H "Content-Type: application/json"
创建 actor 计时器
为 actor 创建一个计时器。
HTTP 请求
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>
计时器请求体:
计时器请求体的格式与actor 提醒相同。例如:
以下指定了 3 秒的 dueTime
和 7 秒的周期。
{
"dueTime":"0h0m3s0ms",
"period":"0h0m7s0ms"
}
dueTime
为 0 表示立即触发。以下请求体表示立即触发,然后每 9 秒触发一次。
{
"dueTime":"0h0m0s0ms",
"period":"0h0m9s0ms"
}
HTTP 响应代码
代码 | 描述 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
400 | 未找到 actor 或请求格式错误 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
name |
要创建的计时器名称。 |
注意,所有 URL 参数区分大小写。
示例
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
-H "Content-Type: application/json" \
-d '{
"data": "someData",
"dueTime": "1m",
"period": "20s",
"callback": "myEventHandler"
}'
删除 actor 计时器
删除 actor 的计时器。
HTTP 请求
DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>
HTTP 响应代码
代码 | 描述 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
name |
要删除的计时器名称。 |
注意,所有 URL 参数区分大小写。
curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
-H "Content-Type: application/json"
Dapr 调用用户服务代码
获取注册的 actor
获取此应用程序的注册 actor 类型和 Dapr actor 配置设置。
HTTP 请求
GET http://localhost:<appPort>/dapr/config
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
示例
获取注册 actor 的示例:
curl -X GET http://localhost:3000/dapr/config \
-H "Content-Type: application/json"
上述命令返回配置(所有字段都是可选的):
参数 | 描述 |
---|---|
entities |
此应用程序支持的 actor 类型。 |
actorIdleTimeout |
指定在停用空闲 actor 之前等待的时间。如果没有 actor 方法调用且没有提醒触发,则 actor 为空闲状态。 |
actorScanInterval |
指定扫描以停用空闲 actor 的频率。空闲时间超过 actorIdleTimeout 的 actor 将被停用。 |
drainOngoingCallTimeout |
在重新平衡 actor 的过程中使用的持续时间。指定等待当前活动的 actor 方法完成的时间。如果没有当前的 actor 方法调用,则忽略此项。 |
drainRebalancedActors |
一个布尔值。如果为 true,Dapr 将等待 drainOngoingCallTimeout 以允许当前 actor 调用完成,然后再尝试停用 actor。如果为 false,则不等待。 |
reentrancy |
一个配置对象,包含 actor 重入的选项。 |
enabled |
重入配置中启用重入所需的标志。 |
maxStackDepth |
重入配置中控制对同一 actor 进行的重入调用次数的值。 |
entitiesConfig |
允许每个 actor 类型设置的实体配置数组。此处定义的任何配置都必须有一个映射回根级别实体的实体。 |
注意
配置中的 actor 设置的超时和间隔使用 time.ParseDuration 格式。您可以使用字符串格式表示持续时间。例如:
1h30m
或1.5h
:1 小时 30 分钟的持续时间1d12h
:1 天 12 小时的持续时间500ms
:500 毫秒的持续时间-30m
:负 30 分钟的持续时间
{
"entities":["actorType1", "actorType2"],
"actorIdleTimeout": "1h",
"actorScanInterval": "30s",
"drainOngoingCallTimeout": "30s",
"drainRebalancedActors": true,
"reentrancy": {
"enabled": true,
"maxStackDepth": 32
},
"entitiesConfig": [
{
"entities": ["actorType1"],
"actorIdleTimeout": "1m",
"drainOngoingCallTimeout": "10s",
"reentrancy": {
"enabled": false
}
}
]
}
停用 actor
通过将 actor 的实例持久化到具有指定 actorId 的状态存储中来停用 actor。
HTTP 请求
DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
400 | 未找到 actor |
500 | 请求失败 |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
注意,所有 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 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 actor |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
methodName |
要调用的方法名称。 |
注意,所有 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 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 actor |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
reminderName |
要调用的提醒名称。 |
注意,所有 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 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 actor |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
actorType |
actor 类型。 |
actorId |
actor ID。 |
timerName |
要调用的计时器名称。 |
注意,所有 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 响应代码
代码 | 描述 |
---|---|
200 | 应用程序健康 |
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口。 |
示例
从应用程序获取健康检查响应的示例:
curl -X GET http://localhost:3000/healthz \
激活 actor
从概念上讲,激活 actor 意味着创建 actor 的对象并将 actor 添加到跟踪表中。查看 .NET SDK 的示例。
外部查询 actor 状态
为了使 actor 状态可见并允许复杂场景(如状态聚合),Dapr 将 actor 状态保存在外部状态存储中,例如数据库。因此,可以通过组合正确的键或查询来外部查询 actor 状态。
Dapr 为 actor 创建的状态命名空间由以下项目组成:
- 应用程序 ID:表示分配给 Dapr 应用程序的唯一 ID。
- actor 类型:表示 actor 的类型。
- actor ID:表示 actor 类型的 actor 实例的唯一 ID。
- 键:特定状态值的键。一个 actor ID 可以持有多个状态键。
以下示例显示了如何在 myapp
应用程序 ID 命名空间下构造 actor 实例状态的键:
myapp||cat||hobbit||food
在上述示例中,我们获取了 myapp
应用程序 ID 命名空间下,actor 类型为 cat
,actor ID 为 hobbit
的状态键 food
的值。
7 - Secrets API 参考
获取 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 负载,其中键名作为字段及其各自的值。
如果 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
) 作为键返回。
响应代码
代码 | 描述 |
---|---|
200 | OK |
204 | Secret 未找到 |
400 | Secret 存储缺失或配置错误 |
403 | 访问被拒绝 |
500 | 获取 secret 失败或未定义 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 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口 |
secret-store-name | 要从中获取 secret 的 secret 存储名称 |
请注意,所有 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"
}
}
响应代码
代码 | 描述 |
---|---|
200 | OK |
400 | Secret 存储缺失或配置错误 |
403 | 访问被拒绝 |
500 | 获取 secret 失败或未定义 secret 存储 |
示例
curl http://localhost:3500/v1.0/secrets/vault/bulk
{
"key1": {
"key1": "value1"
},
"key2": {
"key2": "value2"
}
}
8 - 配置 API 参考
获取配置
该端点用于从存储中获取配置。
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
查询参数。例如:
GET http://localhost:<daprPort>/v1.0/configuration/mystore/subscribe?key=config1&key=config2
要订阅所有更改:
GET http://localhost:<daprPort>/v1.0/configuration/mystore/subscribe
请求体
无
HTTP 响应
响应代码
代码 | 描述 |
---|---|
200 |
订阅操作成功 |
400 |
配置存储缺失或配置错误或请求格式错误 |
500 |
订阅配置更改失败 |
响应体
JSON 编码值
示例
curl -X GET 'http://localhost:3500/v1.0/configuration/mystore/subscribe?key=myConfigKey'
上述命令返回以下 JSON:
{
"id": "<unique-id>"
}
返回的 id
参数可用于取消订阅在订阅 API 调用中提供的特定键集。应用程序应保存此参数。
取消订阅配置
该端点用于取消订阅配置更改。
HTTP 请求
GET http://localhost:<daprPort>/v1.0/configuration/<storename>/<subscription-id>/unsubscribe
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口 |
storename |
metadata.name 字段组件文件。请参阅 组件规范 |
subscription-id |
从订阅端点响应中返回的 id 字段的值 |
查询参数
无
请求体
无
HTTP 响应
响应代码
代码 | 描述 |
---|---|
200 |
取消订阅操作成功 |
400 |
配置存储缺失或配置错误或请求格式错误 |
500 |
取消订阅配置更改失败 |
响应体
{
"ok" : true
}
示例
curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore/bf3aa454-312d-403c-af95-6dec65058fa2/unsubscribe'
上述命令返回以下 JSON:
在操作成功的情况下:
{
"ok": true
}
在操作不成功的情况下:
{
"ok": false,
"message": "<dapr 返回的错误信息>"
}
可选应用程序路由
提供一个路由以便 Dapr 发送配置更改
订阅配置更改时,Dapr 会在配置项更改时调用应用程序。您的应用程序可以有一个 /configuration
端点,用于接收所有已订阅键的更新。可以通过在路由中添加 /<store-name>
和 /<store-name>/<key>
来使端点更具体,以适应给定的配置存储。
HTTP 请求
POST http://localhost:<appPort>/configuration/<store-name>/<key>
URL 参数
参数 | 描述 |
---|---|
appPort |
应用程序端口 |
storename |
metadata.name 字段组件文件。请参阅 组件规范 |
key |
已订阅的键 |
请求体
给定订阅 id 的配置项列表。配置项可以有一个与之关联的版本,该版本在通知中返回。
{
"id": "<subscription-id>",
"items": [
{
"key": "<key-of-configuration-item>",
"value": "<new-value>",
"version": "<version-of-item>"
}
]
}
示例
{
"id": "bf3aa454-312d-403c-af95-6dec65058fa2",
"items": [
{
"key": "config-1",
"value": "abcdefgh",
"version": "1.1"
}
]
}
下一步
9 - 分布式锁 API 参考
锁
通过此端点,您可以通过提供锁所有者的名称和要锁定的资源 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 解锁现有锁。
HTTP 请求
POST http://localhost:<daprPort>/v1.0-alpha1/unlock/<storename>
URL 参数
参数 | 描述 |
---|---|
daprPort |
Dapr 端口 |
storename |
metadata.name 字段的组件文件。请参阅组件模式 |
查询参数
无
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 请求成功 |
204 | 空响应 |
400 | 请求格式错误 |
500 | 请求失败 |
HTTP 请求体
解锁端点需要接收以下 JSON 负载:
{
"resourceId": "",
"lockOwner": ""
}
HTTP 响应体
解锁端点会返回以下负载:
{
"status": 0
}
status
字段包含以下响应代码:
代码 | 描述 |
---|---|
0 | 成功 |
1 | 锁未找到 |
2 | 锁属于其他所有者 |
3 | 内部错误 |
示例
curl -X POST http://localhost:3500/v1.0-alpha/unlock/redisStore \
-H "Content-Type: application/json" \
-d '{
"resourceId": "lock1",
"lockOwner": "vader"
}'
{
"status": 0
}
10 - 健康 API 参考
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 是否已正确初始化,以便进行后续调用。
例如,Java SDK 和 .NET SDK 使用此端点进行初始化。
目前,v1.0/healthz/outbound
端点在以下 SDK 中支持:
HTTP 请求
GET http://localhost:<daprPort>/v1.0/healthz/outbound
HTTP 响应代码
代码 | 描述 |
---|---|
204 | Dapr 是健康的 |
500 | Dapr 是不健康的 |
URL 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口 |
示例
curl -i http://localhost:3500/v1.0/healthz/outbound
相关文章
11 - 元数据 API 参考
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 运行时注册的 pub/sub 订阅列表。这包括 pub/sub 名称、主题、路由、死信主题、订阅类型和与订阅相关的元数据。
启用的功能
通过配置规范启用的功能列表(包括构建时的覆盖)。
应用程序连接详细信息
元数据 API 返回与 Dapr 连接到应用程序相关的信息。这包括应用程序端口、协议、主机、最大并发性以及健康检查的详细信息。
属性
元数据 API 允许您以键值对的格式存储附加的属性信息。这些信息是临时的内存信息,如果 sidecar 重新加载则不会持久化。此信息应在 sidecar 创建时添加(例如,在应用程序启动后)。
获取 Dapr sidecar 信息
从元数据端点获取 Dapr sidecar 信息。
用例:
获取元数据 API 可用于发现已加载组件支持的不同能力。它可以帮助操作员确定要为所需能力提供哪些组件。
HTTP 请求
GET http://localhost:<daprPort>/v1.0/metadata
URL 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口。 |
HTTP 响应代码
代码 | 描述 |
---|---|
200 | 返回元数据信息 |
500 | Dapr 无法返回元数据信息 |
HTTP 响应体
元数据 API 响应对象
名称 | 类型 | 描述 |
---|---|---|
id | string | 应用程序 ID |
runtimeVersion | string | Dapr 运行时版本 |
enabledFeatures | string[] | 由 Dapr 配置启用的功能列表,参见 https://docs.dapr.io/operations/configuration/preview-features/ |
actors | 元数据 API 响应注册的 actor[] | 注册的 actor 元数据的 JSON 编码数组。 |
extended.attributeName | string | 自定义属性的键值对列表,其中键是属性名称。 |
components | 元数据 API 响应组件[] | 已加载组件元数据的 JSON 编码数组。 |
httpEndpoints | 元数据 API 响应 HttpEndpoint[] | 已加载 HttpEndpoints 元数据的 JSON 编码数组。 |
subscriptions | 元数据 API 响应订阅[] | pub/sub 订阅元数据的 JSON 编码数组。 |
appConnectionProperties | 元数据 API 响应应用程序连接属性 | 应用程序连接属性的 JSON 编码对象。 |
名称 | 类型 | 描述 |
---|---|---|
type | string | 注册的 actor 类型。 |
count | integer | 运行的 actor 数量。 |
名称 | 类型 | 描述 |
---|---|---|
name | string | 组件名称。 |
type | string | 组件类型。 |
version | string | 组件版本。 |
capabilities | array | 此组件类型和版本支持的能力。 |
名称 | 类型 | 描述 |
---|---|---|
name | string | HttpEndpoint 的名称。 |
名称 | 类型 | 描述 |
---|---|---|
pubsubname | string | pub/sub 的名称。 |
topic | string | 主题名称。 |
metadata | object | 与订阅相关的元数据。 |
rules | 元数据 API 响应订阅规则[] | 与订阅相关的规则列表。 |
deadLetterTopic | string | 死信主题名称。 |
type | string | 订阅类型,可以是 DECLARATIVE 、STREAMING 或 PROGRAMMATIC 。 |
名称 | 类型 | 描述 |
---|---|---|
match | string | 用于匹配消息的 CEL 表达式,参见 https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-route-messages/#common-expression-language-cel |
path | string | 如果匹配表达式为真,则路由消息的路径。 |
名称 | 类型 | 描述 |
---|---|---|
port | integer | 应用程序监听的端口。 |
protocol | string | 应用程序使用的协议。 |
channelAddress | string | 应用程序监听的主机地址。 |
maxConcurrency | integer | 应用程序可以处理的最大并发请求数。 |
health | 元数据 API 响应应用程序连接属性健康 | 应用程序的健康检查详细信息。 |
名称 | 类型 | 描述 |
---|---|---|
healthCheckPath | string | 健康检查路径,适用于 HTTP 协议。 |
healthProbeInterval | string | 每次健康探测之间的时间,以 go duration 格式表示。 |
healthProbeTimeout | string | 每次健康探测的超时时间,以 go duration 格式表示。 |
healthThreshold | integer | 在应用程序被认为不健康之前失败的健康探测的最大次数。 |
示例
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 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口。 |
attributeName | 自定义属性名称。这是键值对中的键名称。 |
HTTP 请求体
在请求中需要以 RAW 数据传递自定义属性值:
{
"Content-Type": "text/plain"
}
在请求体中放置您想要存储的自定义属性值:
attributeValue
HTTP 响应代码
代码 | 描述 |
---|---|
204 | 自定义属性已添加到元数据信息中 |
示例
向元数据端点添加自定义属性:
curl -X PUT -H "Content-Type: text/plain" --data "myDemoAttributeValue" http://localhost:3500/v1.0/metadata/myDemoAttribute
获取元数据信息以确认您的自定义属性已添加:
{
"id": "myApp",
"runtimeVersion": "1.12.0",
"enabledFeatures": [
"ServiceInvocationStreaming"
],
"actors": [
{
"type": "DemoActor"
}
],
"components": [
{
"name": "pubsub",
"type": "pubsub.redis",
"version": "v1"
},
{
"name": "statestore",
"type": "state.redis",
"version": "v1",
"capabilities": [
"ETAG",
"TRANSACTIONAL",
"ACTOR"
]
}
],
"httpEndpoints": [
{
"name": "my-backend-api"
}
],
"subscriptions": [
{
"type": "PROGRAMMATIC",
"pubsubname": "pubsub",
"topic": "orders",
"deadLetterTopic": "",
"metadata": {
"ttlInSeconds": "30"
},
"rules": [
{
"match": "%!s(<nil>)",
"path": "orders"
}
]
}
],
"extended": {
"myDemoAttribute": "myDemoAttributeValue",
"appCommand": "uvicorn --port 3000 demo_actor_service:app",
"appPID": "98121",
"cliPID": "98114",
"daprRuntimeVersion": "1.12.0"
},
"appConnectionProperties": {
"port": 3000,
"protocol": "http",
"channelAddress": "127.0.0.1",
"health": {
"healthProbeInterval": "5s",
"healthProbeTimeout": "500ms",
"healthThreshold": 3
}
}
}
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 响应代码
代码 | 描述 |
---|---|
200 | 成功返回 placement 表信息 |
500 | 无法返回 placement 表信息 |
HTTP 响应体
Placement 表 API 响应对象
名称 | 类型 | 描述 |
---|---|---|
tableVersion | int | placement 表版本 |
hostList | Actor 主机信息[] | 注册的 actor 主机信息的 JSON 数组。 |
名称 | 类型 | 描述 |
---|---|---|
name | string | actor 的主机:端口地址。 |
appId | string | 应用 ID。 |
actorTypes | json string array | 它所托管的 actor 类型列表。 |
updatedAt | timestamp | 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
}
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 参数
参数 | 描述 |
---|---|
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
,因为它返回一个包含加密数据的字节数组。
响应代码
代码 | 描述 |
---|---|
200 | OK |
400 | 找不到加密提供者 |
500 | 请求格式正确,但 Dapr 代码或底层组件出错 |
示例
curl http://localhost:3500/v1.0-alpha1/crypto/myAzureKeyVault/encrypt \
-X PUT \
-H "dapr-key-name: myCryptoKey" \
-H "dapr-key-wrap-algorithm: aes-gcm" \
-H "Content-Type: application/octet-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 参数
参数 | 描述 |
---|---|
daprPort | Dapr 端口 |
crypto-store-name | 用于获取解密密钥的加密存储名称 |
注意,所有参数区分大小写。
请求头
通过设置请求头来配置其他解密参数。下表详细说明了每个解密请求需要设置的必需和可选请求头。
请求头键 | 描述 | 必需性 |
---|---|---|
dapr-key-name | 用于解密操作的密钥名称。 | 是 |
HTTP 响应
响应体
解密请求的响应将其内容类型请求头设置为 application/octet-stream
,因为它返回一个表示解密数据的字节数组。
响应代码
代码 | 描述 |
---|---|
200 | OK |
400 | 找不到加密提供者 |
500 | 请求格式正确,但 Dapr 代码或底层组件出错 |
示例
curl http://localhost:3500/v1.0-alpha1/crypto/myAzureKeyVault/decrypt \
-X PUT \
-H "dapr-key-name: myCryptoKey" \
-H "Content-Type: application/octet-stream" \
--data-binary "gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A=="
上述命令发送一个加密消息负载的 base-64 编码字符串,并将返回一个响应,内容类型请求头设置为
application/octet-stream
,返回响应体hello world
。
hello world
14 - 作业API参考
注意
作业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 |
每隔 |
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
。
$ 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:3500/v1.0-alpha1/jobs/<name>
URL参数
参数 | 描述 |
---|---|
name |
您正在检索的已调度作业的名称 |
HTTP响应代码
代码 | 描述 |
---|---|
200 |
已接受 |
400 |
请求格式错误 |
500 |
请求格式正确,但作业不存在或dapr代码或调度器控制平面服务中出错 |
响应内容
运行以下示例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:3500/v1.0-alpha1/jobs/<name>
URL参数
参数 | 描述 |
---|---|
name |
您正在删除的作业的名称 |
HTTP响应代码
代码 | 描述 |
---|---|
204 |
已接受 |
400 |
请求格式错误 |
500 |
请求格式正确,但dapr代码或调度器控制平面服务中出错 |
响应内容
在以下示例curl命令中,名为test1
且app-id为sub
的作业将被删除
$ curl -X DELETE http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json"
下一步
15 - 会话API参考
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": {},
}
],
}