1 - 服务调用API参考

关于服务调用API的详细文档

Dapr为用户提供了使用唯一命名标识符(appId)来调用其他使用Dapr的应用程序的功能,或者调用不使用Dapr的HTTP端点。 这使得应用程序可以通过命名标识符相互交互,并将服务发现的责任交给Dapr运行时。

调用远程Dapr应用上的方法

这个端点允许您在另一个启用了Dapr的应用中调用方法。

HTTP请求

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

调用非Dapr端点上的方法

这个端点允许您使用HTTPEndpoint资源名称或完全限定域名(FQDN)URL在非Dapr端点上调用方法。

HTTP请求

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

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

HTTP响应代码

当一个服务通过Dapr调用另一个服务时,被调用服务的状态码将返回给调用者。 如果存在网络错误或其他瞬态错误,Dapr将返回一个500错误,并附带详细的错误信息。

如果用户通过HTTP调用Dapr与启用gRPC的服务通信,来自被调用gRPC服务的错误将返回为500,而成功的响应将返回为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中,testingmathService运行的命名空间。

非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 参考

关于发布/订阅 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/jsonContent-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 上的路由 ordersPOST 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 参考

关于工作流 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>

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

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

关于状态管理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-writelast-write;请参阅状态操作选项
consistency (可选)strongeventual;请参阅状态操作选项

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

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

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

请求头

描述
If-Match (可选)与要删除的键关联的ETag

HTTP响应

响应代码

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

响应体

无。

示例

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

查询状态

通过该端点可以查询键/值状态。

HTTP请求

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

URL参数

参数 描述
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 (可选)状态操作选项;请参阅状态操作选项

示例

下面的示例显示了key1upsert操作和key2delete操作。这适用于状态存储中名为’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
    

下一步

5 - Bindings API 参考

关于 bindings API 的详细文档

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

bindings 的示例包括 KafkaRabbit MQAzure Event HubsAWS SQSGCP 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 响应代码

代码 描述
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 参考

关于 actor 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/PnYnMnWnDTnHnMnSRn/ 指定提醒将被调用 n 次。

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

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

如果仅设置了 ttldueTime,则提醒将被接受。然而,只有 dueTime 生效。例如,提醒在 dueTime 触发,ttl 被忽略。

如果设置了 ttldueTimeperiod,则提醒首先在 dueTime 触发,然后根据 periodttl 重复触发并过期。

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

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

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

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

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

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

当您在 periodttl 中同时指定重复次数时,当任一条件满足时,计时器/提醒将停止。以下示例中,计时器的 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 类型设置的实体配置数组。此处定义的任何配置都必须有一个映射回根级别实体的实体。
{
  "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 参考

关于 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 参考

关于配置 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 参考

关于分布式锁 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 参考

关于健康 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 参考

关于元数据 API 的详细文档

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

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

元数据 API

组件

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

组件类型 能力
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 编码对象。

元数据 API 响应注册的 actor

名称 类型 描述
type string 注册的 actor 类型。
count integer 运行的 actor 数量。

元数据 API 响应组件

名称 类型 描述
name string 组件名称。
type string 组件类型。
version string 组件版本。
capabilities array 此组件类型和版本支持的能力。

元数据 API 响应 HttpEndpoint

名称 类型 描述
name string HttpEndpoint 的名称。

元数据 API 响应订阅

名称 类型 描述
pubsubname string pub/sub 的名称。
topic string 主题名称。
metadata object 与订阅相关的元数据。
rules 元数据 API 响应订阅规则[] 与订阅相关的规则列表。
deadLetterTopic string 死信主题名称。
type string 订阅类型,可以是 DECLARATIVESTREAMINGPROGRAMMATIC

元数据 API 响应订阅规则

名称 类型 描述
match string 用于匹配消息的 CEL 表达式,参见 https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-route-messages/#common-expression-language-cel
path string 如果匹配表达式为真,则路由消息的路径。

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

名称 类型 描述
port integer 应用程序监听的端口。
protocol string 应用程序使用的协议。
channelAddress string 应用程序监听的主机地址。
maxConcurrency integer 应用程序可以处理的最大并发请求数。
health 元数据 API 响应应用程序连接属性健康 应用程序的健康检查详细信息。

元数据 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 参考

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 数组。

Actor 主机信息

名称 类型 描述
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 参考

关于加密 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-gcmchacha20-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参数

参数 描述
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的作业,并指定schedulerepeatsdata

$ 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命令后,返回的响应是包含作业namedueTimedata的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"

下一步

作业API概述

15 - 会话API参考

关于会话API的详细文档

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概述