Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

每个绑定组件都有自己的一组属性。点击名称链接以查看每个绑定的组件规格。

Generic

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
Apache Dubbo		✅	Alpha	v1	1.7
Apple Push Notifications (APN)		✅	Alpha	v1	1.0
commercetools GraphQL		✅	Alpha	v1	1.8
Cron (Scheduler)	✅		Stable	v1	1.10
GraphQL		✅	Alpha	v1	1.0
HTTP		✅	Stable	v1	1.0
Huawei OBS		✅	Alpha	v1	1.8
InfluxDB		✅	Beta	v1	1.7
Kafka	✅	✅	Stable	v1	1.8
Kitex		✅	Alpha	v1	1.11
KubeMQ	✅	✅	Beta	v1	1.10
Kubernetes Events	✅		Alpha	v1	1.0
Local Storage		✅	Stable	v1	1.9
MQTT3	✅	✅	Beta	v1	1.7
MySQL & MariaDB		✅	Alpha	v1	1.0
PostgreSQL		✅	Stable	v1	1.9
Postmark		✅	Alpha	v1	1.0
RabbitMQ	✅	✅	Stable	v1	1.9
Redis		✅	Stable	v1	1.9
RethinkDB	✅		Beta	v1	1.9
RocketMQ	✅	✅	Alpha	v1	1.2
SFTP		✅	Alpha	v1	1.15
SMTP		✅	Alpha	v1	1.0
Twilio SMS		✅	Alpha	v1	1.0
Twillio SendGrid		✅	Alpha	v1	1.0
Wasm		✅	Alpha	v1	1.11

Alibaba Cloud

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
Alibaba Cloud DingTalk	✅	✅	Alpha	v1	1.2
Alibaba Cloud OSS		✅	Alpha	v1	1.0
Alibaba Cloud SLS		✅	Alpha	v1	1.9
Alibaba Cloud Tablestore		✅	Alpha	v1	1.5

Amazon Web Services (AWS)

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
AWS DynamoDB		✅	Alpha	v1	1.0
AWS Kinesis	✅	✅	Alpha	v1	1.0
AWS S3		✅	Stable	v1	1.11
AWS SES		✅	Alpha	v1	1.4
AWS SNS		✅	Alpha	v1	1.0
AWS SQS	✅	✅	Alpha	v1	1.0

Cloudflare

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
Cloudflare Queues		✅	Alpha	v1	1.10

Google Cloud Platform (GCP)

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
GCP Cloud Pub/Sub	✅	✅	Alpha	v1	1.0
GCP Storage Bucket		✅	Alpha	v1	1.0

Microsoft Azure

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
Azure Blob Storage		✅	Stable	v1	1.0
Azure Cosmos DB (Gremlin API)		✅	Alpha	v1	1.5
Azure CosmosDB		✅	Stable	v1	1.7
Azure Event Grid	✅	✅	Beta	v1	1.7
Azure Event Hubs	✅	✅	Stable	v1	1.8
Azure OpenAI	✅	✅	Alpha	v1	1.11
Azure Service Bus Queues	✅	✅	Stable	v1	1.7
Azure SignalR		✅	Alpha	v1	1.0
Azure Storage Queues	✅	✅	Stable	v1	1.0

Zeebe (Camunda Cloud)

Component	Input Binding	Output Binding	Status	Component version	Since runtime version
Zeebe Command		✅	Stable	v1	1.2
Zeebe Job Worker	✅		Stable	v1	1.2

1.1 - Alibaba Cloud DingTalk binding 规范

Alibaba Cloud DingTalk binding 组件的详细文档

设置 Dapr 组件

要设置 Alibaba Cloud DingTalk binding，请创建一个类型为 bindings.dingtalk.webhook 的组件。有关如何创建和应用 secretstore 配置，请参阅此指南。有关如何检索和使用密钥以及 Dapr 组件，请参阅此引用密钥指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.dingtalk.webhook
  version: v1
  metadata:
  - name: id
    value: "test_webhook_id"
  - name: url
    value: "https://oapi.dingtalk.com/robot/send?access_token=******"
  - name: secret
    value: "****************"
  - name: direction
    value: "input, output"

Warning

上面的示例将密钥作为纯字符串使用。建议使用密钥存储来存储密钥，如此处所述。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`id`	Y	Input/Output	唯一 id	`"test_webhook_id"`
`url`	Y	Input/Output	DingTalk 的 Webhook url	`"https://oapi.dingtalk.com/robot/send?access_token=******"`
`secret`	N	Input/Output	DingTalk Webhook 的密钥	`"****************"`
`direction`	N	Input/Output	binding 的方向	`"input"`, `"output"`, `"input, output"`

Binding 支持

此组件支持输入和输出 binding 接口。

此组件支持输出 binding，具有以下操作：

create
get

指定负载

示例：按照此处的说明设置负载数据

curl -X POST http://localhost:3500/v1.0/bindings/myDingTalk \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "msgtype": "text",
          "text": {
            "content": "Hi"
          }
        },
        "operation": "create"
      }'

curl -X POST http://localhost:3500/v1.0/bindings/myDingTalk \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "msgtype": "text",
          "text": {
            "content": "Hi"
          }
        },
        "operation": "get"
      }'

1.2 - Alibaba Cloud Tablestore binding 规范

Alibaba Tablestore binding 组件的详细文档

组件格式

要设置 Alibaba Cloud Tablestore binding，请创建类型为 bindings.alicloud.tablestore 的组件。有关如何创建和应用 secretstore 配置，请参阅本指南。有关如何使用 Dapr 组件检索和使用密钥，请参阅引用密钥指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mytablestore
spec:
  type: bindings.alicloud.tablestore
  version: v1
  metadata:
  - name: endpoint
    value: "[endpoint]"
  - name: accessKeyID
    value: "[key-id]"
  - name: accessKey
    value: "[access-key]"
  - name: instanceName
    value: "[instance]"
  - name: tableName
    value: "[table]"
  - name: endpoint
    value: "[endpoint]"

Warning

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体如此处所述。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`endpoint`	Y	Output	Alicloud Tablestore 端点。	https://tablestore-cn-hangzhou.aliyuncs.com
`accessKeyID`	Y	Output	Access key ID 凭证。
`accessKey`	Y	Output	Access key 凭证。
`instanceName`	Y	Output	实例名称。
`tableName`	Y	Output	表名称。

Binding 支持

此组件支持输出 binding，具有以下操作：

create：创建对象

创建对象

要执行创建对象操作，请使用 POST 方法调用 binding，并传入以下 JSON 正文：

{
  "operation": "create",
  "data": "YOUR_CONTENT",
  "metadata": {
    "primaryKeys": "pk1"
  }
}

Note

注意 metadata.primaryKeys 字段是必填项。

删除对象

要执行删除对象操作，请使用 POST 方法调用 binding，并传入以下 JSON 正文：

{
  "operation": "delete",
  "metadata": {
   "primaryKeys": "pk1",
   "columnToGet": "name,age,date"
  },
  "data": {
    "pk1": "data1"
  }
}

Note

注意 metadata.primaryKeys 字段是必填项。

列出对象

要执行列出对象操作，请使用 POST 方法调用 binding，并传入以下 JSON 正文：

{
  "operation": "delete",
  "metadata": {
    "primaryKeys": "pk1",
    "columnToGet": "name,age,date"
  },
  "data": {
    "pk1": "data1",
    "pk2": "data2"
  }
}

Note

注意 metadata.primaryKeys 字段是必填项。

获取对象

要执行获取对象操作，请使用 POST 方法调用 binding，并传入以下 JSON 正文：

{
  "operation": "delete",
  "metadata": {
    "primaryKeys": "pk1"
  },
  "data": {
    "pk1": "data1"
  }
}

Note

注意 metadata.primaryKeys 字段是必填项。

1.3 - Apple Push Notification Service 绑定规范

Apple Push Notification Service 绑定组件的详细文档

组件格式

要设置 Apple Push Notifications 绑定，请创建类型为 bindings.apns 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.apns
  version: v1
  metadata:
    - name: development
      value: "<bool>"
    - name: key-id
      value: "<APPLE_KEY_ID>"
    - name: team-id
      value: "<APPLE_TEAM_ID>"
    - name: private-key
      secretKeyRef:
        name: <SECRET>
        key: "<SECRET-KEY-NAME>"

规格元数据字段

字段	必填	绑定支持	详情	示例
`development`	Y	Output	告诉绑定使用哪个 APNs 服务。设置为 `"true"` 以使用开发服务，或设置为 `"false"` 以使用生产服务。默认值：`"true"`	`"true"`
`key-id`	Y	Output	来自 Apple Developer Portal 的私钥标识符	`"private-key-id`"
`team-id`	Y	Output	来自 Apple Developer Portal 的组织或作者标识符	`"team-id"`
`private-key`	Y	Output	是一个 PKCS #8 格式的私钥。私钥应存储在 secret store 中，而不是直接暴露在配置中。有关更多详细信息，请参阅此处	`"pem file"`

私钥

APNS 绑定需要一个加密私钥来为 APNS 服务生成认证令牌。私钥可以从 Apple Developer Portal 生成，以 PKCS #8 文件的形式提供，私钥以 PEM 格式存储。私钥应存储在 Dapr secret store 中，而不是直接存储在绑定配置文件中。

下面显示了 APNS 绑定的示例配置文件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: apns
spec:
  type: bindings.apns
  metadata:
  - name: development
    value: false
  - name: key-id
    value: PUT-KEY-ID-HERE
  - name: team-id
    value: PUT-APPLE-TEAM-ID-HERE
  - name: private-key
    secretKeyRef:
      name: apns-secrets
      key: private-key

如果使用 Kubernetes，示例 secret 配置可能如下所示：

apiVersion: v1
kind: Secret
metadata:
    name: apns-secrets
stringData:
    private-key: |
        -----BEGIN PRIVATE KEY-----
        KEY-DATA-GOES-HERE
        -----END PRIVATE KEY-----

绑定支持

此组件支持 输出绑定，具有以下操作：

create

推送通知格式

APNS 绑定是对 Apple Push Notification Service 的透传包装器。APNS 绑定将直接向 APNS 服务发送请求，而不进行任何转换。因此，了解 APNS 服务期望的推送通知负载格式非常重要。负载格式记录在此处。

请求格式

{
    "data": {
        "aps": {
            "alert": {
                "title": "New Updates!",
                "body": "There are new updates for your review"
            }
        }
    },
    "metadata": {
        "device-token": "PUT-DEVICE-TOKEN-HERE",
        "apns-push-type": "alert",
        "apns-priority": "10",
        "apns-topic": "com.example.helloworld"
    },
    "operation": "create"
}

data 对象包含完整的推送通知规范，如 Apple 文档中所述。data 对象将直接发送到 APNs 服务。

除了 device-token 值之外，Apple 文档中指定的 HTTP 标头可以作为元数据字段发送，并将包含在对 APNs 服务的 HTTP 请求中。

响应格式

{
    "messageID": "UNIQUE-ID-FOR-NOTIFICATION"
}

1.4 - AWS DynamoDB 绑定规范

AWS DynamoDB 绑定组件的详细文档

组件格式

要设置 AWS DynamoDB 绑定，请创建类型为 bindings.aws.dynamodb 的组件。有关如何创建和应用绑定配置，请参阅此指南。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "items"
  - name: region
    value: "us-west-2"
  - name: accessKey
    value: "*****************"
  - name: secretKey
    value: "*****************"
  - name: sessionToken
    value: "*****************"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`table`	Y	Output	DynamoDB 表名	`"items"`
`region`	Y	Output	AWS DynamoDB 实例部署所在的特定 AWS 区域	`"us-east-1"`
`accessKey`	Y	Output	用于访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	Output	用于访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	Output	要使用的 AWS 会话令牌	`"sessionToken"`

Important

当在 EKS (AWS Kubernetes) 上与您的应用程序一起运行 Dapr 边车 (daprd) 时，如果您使用的节点/pod 已经附加了定义对 AWS 资源访问权限的 IAM 策略，则不得在您使用的组件规范定义中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持输出绑定，具有以下操作：

create

1.5 - AWS Kinesis 绑定规范

AWS Kinesis 绑定组件的详细文档

组件格式

要设置 AWS Kinesis 绑定，请创建一个类型为 bindings.aws.kinesis 的组件。有关如何创建和应用绑定配置，请参阅本指南。

有关如何设置 AWS Kinesis 数据流的说明，请参阅此有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.kinesis
  version: v1
  metadata:
  - name: streamName
    value: "KINESIS_STREAM_NAME" # Kinesis 流名称
  - name: consumerName
    value: "KINESIS_CONSUMER_NAME" # Kinesis 消费者名称
  - name: mode
    value: "shared" # shared - 共享吞吐量 或 extended - 扩展/增强扇出
  - name: region
    value: "AWS_REGION" # 替换
  - name: accessKey
    value: "AWS_ACCESS_KEY" # 替换
  - name: secretKey
    value: "AWS_SECRET_KEY" # 替换
  - name: sessionToken
    value: "*****************"
  - name: direction
    value: "input, output"
  - name: endpoint
    value: "http://localhost:4566" # 可选：自定义端点（例如用于 LocalStack）

警告

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，如此处所述。

规范元数据字段

字段	必填	绑定支持	详情	示例
`mode`	N	输入	Kinesis 流模式。`shared`- 共享吞吐量，`extended` - 扩展/增强扇出方法。更多细节请见这里。默认为 `"shared"`	`"shared"`, `"extended"`
`streamName`	Y	输入/输出	AWS Kinesis 流名称	`"stream"`
`consumerName`	Y	输入	AWS Kinesis 消费者名称	`"myconsumer"`
`region`	Y	输出	AWS Kinesis 实例部署的特定 AWS 区域	`"us-east-1"`
`accessKey`	Y	输出	用于访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	输出	用于访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	输出	要使用的 AWS 会话令牌	`"sessionToken"`
`direction`	N	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`
`endpoint`	N	输入	Kinesis 和 DynamoDB 的自定义端点（例如启用 AWS LocalStack 支持）	`"http://localhost:4566"`

重要

在 EKS (AWS Kubernetes) 上与应用程序一起运行 Dapr 边车 (daprd) 时，如果您使用的节点/Pod 已附加到定义访问 AWS 资源的 IAM 策略，则不得在您使用的组件规范定义中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持输入和输出绑定接口。

此组件支持以下操作的输出绑定：

create

1.6 - AWS S3 绑定规范

AWS S3 绑定组件的详细文档

组件格式

要设置 AWS S3 绑定，请创建一个类型为 bindings.aws.s3 的组件。该绑定适用于其他兼容 S3 的服务，例如 Minio。有关如何创建和应用绑定配置，请参阅此指南。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.s3
  version: v1
  metadata:
  - name: bucket
    value: "mybucket"
  - name: region
    value: "us-west-2"
  - name: endpoint
    value: "s3.us-west-2.amazonaws.com"
  - name: accessKey
    value: "*****************"
  - name: secretKey
    value: "*****************"
  - name: sessionToken
    value: "mysession"
  - name: decodeBase64
    value: "<bool>"
  - name: encodeBase64
    value: "<bool>"
  - name: forcePathStyle
    value: "<bool>"
  - name: disableSSL
    value: "<bool>"
  - name: insecureSSL
    value: "<bool>"
  - name: storageClass
    value: "<string>"

警告

上述示例将密钥以纯字符串形式使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`bucket`	Y	Output	要写入的 S3 存储桶名称	`"bucket"`
`region`	Y	Output	特定的 AWS 区域	`"us-east-1"`
`endpoint`	N	Output	特定的 AWS 端点	`"s3.us-east-1.amazonaws.com"`
`accessKey`	Y	Output	用于访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	Output	用于访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	Output	要使用的 AWS 会话令牌	`"sessionToken"`
`forcePathStyle`	N	Output	目前 Amazon S3 SDK 支持虚拟托管式和路径式访问。`"true"` 为路径式格式，如 `"https://<endpoint>/<your bucket>/<key>"`。`"false"` 为托管式格式，如 `"https://<your bucket>.<endpoint>/<key>"`。默认为 `"false"`	`"true"`, `"false"`
`decodeBase64`	N	Output	在保存到存储桶之前解码 base64 文件内容的配置。（用于保存包含二进制内容的文件）。`"true"` 是唯一允许的肯定值。其他肯定变体如 `"True"`, `"1"` 不可接受。默认为 `false`	`"true"`, `"false"`
`encodeBase64`	N	Output	在返回内容之前编码 base64 文件内容的配置。（用于打开包含二进制内容的文件）。`"true"` 是唯一允许的肯定值。其他肯定变体如 `"True"`, `"1"` 不可接受。默认为 `"false"`	`"true"`, `"false"`
`disableSSL`	N	Output	允许连接到非 `https://` 端点。默认为 `"false"`	`"true"`, `"false"`
`insecureSSL`	N	Output	当连接到 `https://` 端点时，接受无效或自签名证书。默认为 `"false"`	`"true"`, `"false"`
`storageClass`	N	Output	创建操作期间对象的所需存储类。有效的 AWS 存储类类型可在此处找到	`STANDARD_IA`

重要

在 EKS (AWS Kubernetes) 上将 Dapr 边车 (daprd) 与您的应用程序一起运行时，如果您使用的节点/Pod 已附加到定义 AWS 资源访问权限的 IAM 策略，则不得在正在使用的组件规范定义中提供 AWS 访问密钥、秘密密钥和令牌。

S3 存储桶创建

与 Minio 一起使用

Minio 是一项将本地存储暴露为兼容 S3 的块存储的服务，它是 S3 的流行替代方案，尤其是在开发环境中。您也可以将 S3 绑定与 Minio 一起使用，只需进行一些配置调整：

将 endpoint 设置为 Minio 服务器的地址，包括协议（http:// 或 https://）和末尾的可选端口。例如，http://minio.local:9000（具体值取决于您的环境）。
forcePathStyle 必须设置为 true
region 的值不重要；您可以将其设置为 us-east-1。
根据您的环境，如果您使用非安全连接（使用 http:// 协议）连接到 Minio，可能需要将 disableSSL 设置为 true。如果您使用安全连接（https:// 协议）但使用自签名证书，则可能需要将 insecureSSL 设置为 true。

对于本地开发，使用 LocalStack 项目来集成 AWS S3。按照这些说明运行 LocalStack。

要使用 Docker 从命令行在本地运行 LocalStack，请使用类似于以下的 docker-compose.yaml：

version: "3.8"

services:
  localstack:
    container_name: "cont-aws-s3"
    image: localstack/localstack:1.4.0
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      - DEBUG=1
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "<PATH>/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh"  # init hook
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

要使用 S3 组件，您需要使用现有的存储桶。上述示例使用 LocalStack 初始化钩子来设置存储桶。

要将 LocalStack 与 S3 绑定一起使用，您需要在组件元数据中提供 endpoint 配置。当针对生产 AWS 运行时，不需要 endpoint。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
    name: aws-s3
    namespace: default
spec:
  type: bindings.aws.s3
  version: v1
  metadata:
    - name: bucket
      value: conformance-test-docker
    - name: endpoint
      value: "http://localhost:4566"
    - name: accessKey
      value: "my-access"
    - name: secretKey
      value: "my-secret"
    - name: region
      value: "us-east-1"

要使用 S3 组件，您需要使用现有的存储桶。按照 AWS 文档创建存储桶。

绑定支持

该组件支持具有以下操作的输出绑定：

create : 创建对象
get : 获取对象
delete : 删除对象
list: 列出对象

创建对象

要执行创建操作，请使用 POST 方法调用 AWS S3 绑定，并提供以下 JSON 请求体：

注意：默认情况下，会生成一个随机 UUID。有关设置名称的元数据支持，请参阅下文

{
  "operation": "create",
  "data": "YOUR_CONTENT",
  "metadata": { 
    "storageClass": "STANDARD_IA",
    "tags": "project=sashimi,year=2024",
  }
}

例如，您可以在使用 Linux curl 命令执行 create 操作时提供存储类或标签

curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "storageClass": "STANDARD_IA", "project=sashimi,year=2024" } }' /
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

使用预签名 URL 共享对象

要为对象指定生存时间进行预签名，请在 create 请求上使用 presignTTL 元数据键。 presignTTL 的有效值为 Go duration 字符串。

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"presignTTL\": \"15m\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "presignTTL": "15m" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下示例 JSON：

{
    "location":"https://<your bucket>.s3.<your region>.amazonaws.com/<key>",
    "versionID":"<version ID if Bucket Versioning is enabled>",
    "presignURL": "https://<your bucket>.s3.<your region>.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host"
}

示例

将文本保存到随机生成的 UUID 文件

在 Windows 上，使用 cmd 提示符（PowerShell 具有不同的转义机制）

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文本保存到特定文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"key\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "key": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文件保存为对象

要上传文件，请将其编码为 Base64 并让绑定知道对其进行反序列化：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.s3
  version: v1
  metadata:
  - name: bucket
    value: mybucket
  - name: region
    value: us-west-2
  - name: endpoint
    value: s3.us-west-2.amazonaws.com
  - name: accessKey
    value: *****************
  - name: secretKey
    value: *****************
  - name: sessionToken
    value: mysession
  - name: decodeBase64
    value: <bool>
  - name: forcePathStyle
    value: <bool>

然后您可以像往常一样上传它：

curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"key\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "key": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

从文件路径上传

要从提供的路径（相对或绝对）上传文件，请在包含空 data 字段的 create 请求上使用 filepath 元数据键。

curl -d '{ \"operation\": \"create\", \"metadata\": { \"filePath\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "metadata": { "filePath": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体将包含以下 JSON：

{
    "location":"https://<your bucket>.s3.<your region>.amazonaws.com/<key>",
    "versionID":"<version ID if Bucket Versioning is enabled"
}

预签名现有对象

要为现有的 S3 对象指定生存时间进行预签名，请在 presign 请求上使用 presignTTL 和 key 元数据键。 presignTTL 的有效值为 Go duration 字符串。

curl -d "{ \"operation\": \"presign\", \"metadata\": { \"presignTTL\": \"15m\", \"key\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "presign", "metadata": { "presignTTL": "15m", "key": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下示例 JSON：

{
    "presignURL": "https://<your bucket>.s3.<your region>.amazonaws.com/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host"
}

获取对象

要执行获取文件操作，请使用 POST 方法调用 AWS S3 绑定，并提供以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数为：

key - 对象的名称

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含存储在对象中的值。

删除对象

要执行删除对象操作，请使用 POST 方法调用 AWS S3 绑定，并提供以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数为：

key - 对象的名称

示例

删除对象

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

如果成功，将返回 HTTP 204（无内容）和空响应体。

列出对象

要执行列出对象操作，请使用 POST 方法调用 S3 绑定，并提供以下 JSON 请求体：

{
  "operation": "list",
  "data": {
    "maxResults": 10,
    "prefix": "file",
    "marker": "hvlcCQFSOD5TD",
    "delimiter": "i0FvxAn2EOEL6"
  }
}

数据参数为：

maxResults - （可选）设置响应中返回的键的最大数量。默认情况下，该操作最多返回 1,000 个键名称。响应可能包含较少的键，但绝不会包含更多。
prefix - （可选）将响应限制为以指定前缀开头的键。
marker - （可选）marker 是您希望 Amazon S3 开始列出的位置。Amazon S3 在此指定的键之后开始列出。Marker 可以是存储桶中的任何键。然后可以在后续调用中使用 marker 值来请求下一组列表项。
delimiter - （可选）分隔符是用于对键进行分组的字符。

响应

响应体包含找到的对象列表。

对象列表将以 JSON 数组形式返回，格式如下：

{
	"CommonPrefixes": null,
	"Contents": [
		{
			"ETag": "\"7e94cc9b0f5226557b05a7c2565dd09f\"",
			"Key": "hpNdFUxruNuwm",
			"LastModified": "2021-08-16T06:44:14Z",
			"Owner": {
				"DisplayName": "owner name",
				"ID": "owner id"
			},
			"Size": 6916,
			"StorageClass": "STANDARD"
		}
	],
	"Delimiter": "",
	"EncodingType": null,
	"IsTruncated": true,
	"Marker": "hvlcCQFSOD5TD",
	"MaxKeys": 1,
	"Name": "mybucketdapr",
	"NextMarker": "hzaUPWjmvyi9W",
	"Prefix": ""
}

1.7 - AWS SES 绑定规范

AWS SES 绑定组件的详细文档

组件格式

要设置 AWS 绑定，请创建类型为 bindings.aws.ses 的组件。请参阅本指南了解如何创建和应用绑定配置。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: ses
spec:
  type: bindings.aws.ses
  version: v1
  metadata:
  - name: accessKey
    value: *****************
  - name: secretKey
    value: *****************
  - name: region
    value: "eu-west-1"
  - name: sessionToken
    value: mysession
  - name: emailFrom
    value: "sender@example.com"
  - name: emailTo
    value: "receiver@example.com"
  - name: emailCc
    value: "cc@example.com"
  - name: emailBcc
    value: "bcc@example.com"
  - name: subject
    value: "subject"

Warning

上述示例将密钥作为纯文本字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

Field	Required	Binding support	Details	Example
`region`	N	Output	特定的 AWS 区域	`"eu-west-1"`
`accessKey`	N	Output	用于访问此资源的 AWS Access Key	`"key"`
`secretKey`	N	Output	用于访问此资源的 AWS Secret Access Key	`"secretAccessKey"`
`sessionToken`	N	Output	要使用的 AWS 会话令牌	`"sessionToken"`
`emailFrom`	N	Output	如果设置，指定发件人的电子邮件地址。另请参见示例	`"me@example.com"`
`emailTo`	N	Output	如果设置，指定收件人的电子邮件地址。另请参见示例	`"me@example.com"`
`emailCc`	N	Output	如果设置，指定要抄送的电子邮件地址。另请参见示例	`"me@example.com"`
`emailBcc`	N	Output	如果设置，指定要密送的电子邮件地址。另请参见示例	`"me@example.com"`
`subject`	N	Output	如果设置，指定电子邮件的主题。另请参见示例	`"subject of mail"`

Important

当在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr 边车（daprd）时，如果您使用的节点/Pod 已附加到定义了 AWS 资源访问权限的 IAM 策略，则绝不能在正在使用的组件规范定义中提供 AWS access-key、secret-key 和令牌。

绑定支持

此组件支持输出绑定，具有以下操作：

create

示例请求

您可以在每个请求中指定以下任意可选元数据属性：

emailFrom
emailTo
emailCc
emailBcc
subject

发送电子邮件时，配置和请求中的元数据会合并。合并后的元数据集必须至少包含 emailFrom、emailTo、emailCc、emailBcc 和 subject 字段。

emailTo、emailCc 和 emailBcc 字段可以包含多个用分号分隔的电子邮件地址。

示例：

{
  "operation": "create",
  "metadata": {
    "emailTo": "dapr-smtp-binding@example.net",
    "emailCc": "cc1@example.net",
    "subject": "Email subject"
  },
  "data": "Testing Dapr SMTP Binding"
}

emailTo、emailCc 和 emailBcc 字段可以包含多个用分号分隔的电子邮件地址。

1.8 - AWS SNS 绑定规范

AWS SNS 绑定组件的详细文档

组件格式

要设置 AWS SNS 绑定，需创建一个类型为 bindings.aws.sns 的组件。有关如何创建和应用绑定配置，请参阅此指南。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.sns
  version: v1
  metadata:
  - name: topicArn
    value: "mytopic"
  - name: region
    value: "us-west-2"
  - name: endpoint
    value: "sns.us-west-2.amazonaws.com"
  - name: accessKey
    value: "*****************"
  - name: secretKey
    value: "*****************"
  - name: sessionToken
    value: "*****************"

警告

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详细说明	示例
`topicArn`	Y	输出	SNS 主题名称	`"arn:::topicarn"`
`region`	Y	输出	特定的 AWS 区域	`"us-east-1"`
`endpoint`	N	输出	特定的 AWS 端点	`"sns.us-east-1.amazonaws.com"`
`accessKey`	Y	输出	用于访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	输出	用于访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	输出	要使用的 AWS 会话令牌	`"sessionToken"`

重要

在 EKS（AWS Kubernetes）上与你的应用程序一起运行 Dapr 边车（daprd）时，如果你使用的节点/Pod 已附加到定义了 AWS 资源访问权限的 IAM 策略，则不得在你使用的组件规范定义中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持输出绑定，支持以下操作：

create

1.9 - AWS SQS 绑定规范

AWS SQS 绑定组件的详细文档

组件格式

要设置 AWS SQS 绑定，请创建一个类型为 bindings.aws.sqs 的组件。请参阅此指南了解如何创建和应用绑定配置。

请参阅向 AWS 进行身份验证了解与身份验证相关的属性信息

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.aws.sqs
  version: v1
  metadata:
  - name: queueName
    value: "items"
  - name: region
    value: "us-west-2"
  - name: endpoint
    value: "sqs.us-west-2.amazonaws.com"    
  - name: accessKey
    value: "*****************"
  - name: secretKey
    value: "*****************"
  - name: sessionToken
    value: "*****************"
  - name: direction 
    value: "input, output"

Warning

上述示例将密钥以纯文本字符串形式展示。建议按照此处说明使用密钥存储来管理敏感信息。

规范元数据字段

字段	必填	绑定支持	详情	示例
`queueName`	是	输入/输出	SQS 队列名称	`"myqueue"`
`region`	是	输入/输出	特定的 AWS 区域	`"us-east-1"`
`endpoint`	否	输出	特定的 AWS 端点	`"sqs.us-east-1.amazonaws.com"`
`accessKey`	是	输入/输出	用于访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	是	输入/输出	用于访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输入/输出	要使用的 AWS 会话令牌	`"sessionToken"`
`direction`	否	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

Important

当在 EKS（AWS Kubernetes）上使用 Dapr 边车（daprd）与应用程序一起运行时，如果您使用的节点/Pod 已附加定义了访问 AWS 资源的 IAM 策略，则不得在所使用的组件规范定义中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

该组件同时支持输入和输出绑定接口。

该组件支持以下操作的输出绑定：

create

1.10 - Azure Blob Storage 绑定规范

Azure Blob Storage 绑定组件的详细文档

组件格式

若要设置 Azure Blob Storage 绑定，请创建类型为 bindings.azure.blobstorage 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.blobstorage
  version: v1
  metadata:
  - name: accountName
    value: myStorageAccountName
  - name: accountKey
    value: ***********
  - name: containerName
    value: container1
# - name: decodeBase64
#   value: <bool>
# - name: getBlobRetryCount
#   value: <integer>
# - name: publicAccessLevel
#   value: <publicAccessLevel>
# - name: disableEntityManagement
#   value: <bool>

Warning

上述示例将密钥以纯文本字符串形式使用。建议使用 secret store 来管理密钥，具体请参阅此处。

规范元数据字段

字段	必填	绑定支持	详情	示例
`accountName`	Y	Input/Output	Azure Storage 账户名称	`"myexmapleaccount"`
`accountKey`	Y*	Input/Output	Azure Storage 账户访问密钥。仅在不使用 Microsoft Entra ID 身份验证时需要。	`"access-key"`
`containerName`	Y	Output	要写入的 Blob Storage 容器名称	`myexamplecontainer`
`endpoint`	N	Input/Output	可选的自定义 endpoint URL。在使用 Azurite emulator 或为 Azure Storage 使用自定义域时（尽管这不属于官方支持场景）这很有用。endpoint 必须是完整的基础 URL，包含协议（`http://` 或 `https://`）、IP 或 FQDN 以及可选端口。	`"http://127.0.0.1:10000"`
`decodeBase64`	N	Output	在保存到 Blob Storage 之前对 base64 文件内容进行解码的配置（用于保存包含二进制内容的文件）。默认为 `false`	`true`、`false`
`getBlobRetryCount`	N	Output	指定在从 RetryReader 读取时最多发起的 HTTP GET 请求次数。默认为 `10`	`1`、`2`
`publicAccessLevel`	N	Output	指定容器中的数据是否可以公开访问以及访问级别（仅在容器由 Dapr 创建时使用）。默认为 `none`	`blob`、`container`、`none`
`disableEntityManagement`	N	Output	用于禁用实体管理的配置。设置为 `true` 时，绑定将跳过创建指定存储容器的尝试。在使用最小的 Azure AD 权限时这很有用。默认为 `false`	`true`、`false`

Microsoft Entra ID 身份验证

Azure Blob Storage 绑定组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息和根据所选的 Microsoft Entra ID 身份验证机制需要提供的组件元数据字段，请参阅对 Azure 进行身份验证的文档。

绑定支持

此组件支持输出绑定，包含以下操作：

create：创建 blob
get：获取 blob
delete：删除 blob
list：列出 blob

Blob storage 组件的输入绑定通过 Azure Event Grid 触发并推送事件。

有关更多设置和信息，请参阅响应 Blob storage 事件指南。

创建 blob

要执行创建 blob 操作，请使用 POST 方法调用 Azure Blob Storage 绑定，并使用以下 JSON 请求体：

注意：默认情况下会生成一个随机 UUID。有关设置名称的元数据支持，请参阅下文

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

示例

将文本保存到随机生成的 UUID blob

在 Windows 上，使用 cmd 提示符（PowerShell 具有不同的转义机制）

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文本保存到指定 blob

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"blobName\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "blobName": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文件保存到 blob

要上传文件，将其编码为 Base64 并让 Binding 知道需要反序列化：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.blobstorage
  version: v1
  metadata:
  - name: accountName
    value: myStorageAccountName
  - name: accountKey
    value: ***********
  - name: containerName
    value: container1
  - name: decodeBase64
    value: true

然后您可以像平常一样上传：

curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"blobName\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "blobName": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体将包含以下 JSON：

{
   "blobURL": "https://<your account name>. blob.core.windows.net/<your container name>/<filename>"
}

获取 blob

要执行获取 blob 操作，请使用 POST 方法调用 Azure Blob Storage 绑定，并使用以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "blobName": "myblob",
    "includeMetadata": "true"
  }
}

元数据参数为：

blobName - blob 的名称
includeMetadata -（可选）定义是否应返回用户定义的元数据，默认为：false

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"blobName\": \"myblob\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "blobName": "myblob" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含存储在 blob 对象中的值。如果已启用，用户定义的元数据将以以下形式的 HTTP 头返回：

Metadata.key1: value1 Metadata.key2: value2

删除 blob

要执行删除 blob 操作，请使用 POST 方法调用 Azure Blob Storage 绑定，并使用以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "blobName": "myblob"
  }
}

元数据参数为：

blobName - blob 的名称
deleteSnapshots -（可选）当 blob 有关联快照时需要。指定以下两个选项之一：
- include：删除基础 blob 及其所有快照
- only：仅删除 blob 的快照而不删除 blob 本身

示例

删除 blob

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"blobName\": \"myblob\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "blobName": "myblob" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

仅删除 blob 快照

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"blobName\": \"myblob\", \"deleteSnapshots\": \"only\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "blobName": "myblob", "deleteSnapshots": "only" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

删除 blob 及其快照

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"blobName\": \"myblob\", \"deleteSnapshots\": \"include\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "blobName": "myblob", "deleteSnapshots": "include" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

如果成功，将返回 HTTP 204（No Content）和空响应体。

列出 blob

要执行列出 blob 操作，请使用 POST 方法调用 Azure Blob Storage 绑定，并使用以下 JSON 请求体：

{
  "operation": "list",
  "data": {
    "maxResults": 10,
    "prefix": "file",
    "marker": "2!108!MDAwMDM1IWZpbGUtMDgtMDctMjAyMS0wOS0zOC01NS03NzgtMjEudHh0ITAwMDAyOCE5OTk5LTEyLTMxVDIzOjU5OjU5Ljk5OTk5OTlaIQ--",
    "include": {
      "snapshots": false,
      "metadata": true,
      "uncommittedBlobs": false,
      "copy": false,
      "deleted": false
    }
  }
}

data 参数为：

maxResults -（可选）指定最多返回的 blob 数量，包括所有 BlobPrefix 元素。如果请求未指定 maxresults，服务器将最多返回 5,000 个项目。
prefix -（可选）过滤结果，仅返回名称以指定前缀开头的 blob。
marker -（可选）一个字符串值，用于标识在下一次列表操作中要返回的列表部分。如果返回的列表不完整，操作会在响应体中返回一个 marker 值。然后可以在后续调用中使用该 marker 值来请求下一组列表项。
include -（可选）指定要在响应中包含的一个或多个数据集：
- snapshots：指定应在枚举中包含快照。快照在响应中按从最旧到最新的顺序列出。默认为：false
- metadata：指定应在响应中返回 blob 元数据。默认为：false
- uncommittedBlobs：指定响应中应包含已上传块但尚未使用 Put Block List 提交的 blob。默认为：false
- copy：版本 2012-02-12 及更新版本。指定响应中应包含与任何当前或先前 Copy Blob 操作相关的元数据。默认为：false
- deleted：版本 2017-07-29 及更新版本。指定响应中应包含已软删除的 blob。默认为：false

响应

响应体包含找到的块列表以及以下 HTTP 头：

Metadata.marker: 2!108!MDAwMDM1IWZpbGUtMDgtMDctMjAyMS0wOS0zOC0zNC04NjctMTEudHh0ITAwMDAyOCE5OTk5LTEyLTMxVDIzOjU5OjU5Ljk5OTk5OTlaIQ-- Metadata.number: 10

marker - 可在后续调用中用于请求下一组列表项的下一个 marker。请参阅绑定输入的 data 属性上的 marker 说明。
number - 找到的 blob 数量

blob 列表将以以下形式的 JSON 数组返回：

[
  {
    "XMLName": {
      "Space": "",
      "Local": "Blob"
    },
    "Name": "file-08-07-2021-09-38-13-776-1.txt",
    "Deleted": false,
    "Snapshot": "",
    "Properties": {
      "XMLName": {
        "Space": "",
        "Local": "Properties"
      },
      "CreationTime": "2021-07-08T07:38:16Z",
      "LastModified": "2021-07-08T07:38:16Z",
      "Etag": "0x8D941E3593C6573",
      "ContentLength": 1,
      "ContentType": "application/octet-stream",
      "ContentEncoding": "",
      "ContentLanguage": "",
      "ContentMD5": "xMpCOKC5I4INzFCab3WEmw==",
      "ContentDisposition": "",
      "CacheControl": "",
      "BlobSequenceNumber": null,
      "BlobType": "BlockBlob",
      "LeaseStatus": "unlocked",
      "LeaseState": "available",
      "LeaseDuration": "",
      "CopyID": null,
      "CopyStatus": "",
      "CopySource": null,
      "CopyProgress": null,
      "CopyCompletionTime": null,
      "CopyStatusDescription": null,
      "ServerEncrypted": true,
      "IncrementalCopy": null,
      "DestinationSnapshot": null,
      "DeletedTime": null,
      "RemainingRetentionDays": null,
      "AccessTier": "Hot",
      "AccessTierInferred": true,
      "ArchiveStatus": "",
      "CustomerProvidedKeySha256": null,
      "AccessTierChangeTime": null
    },
    "Metadata": null
  }
]

元数据信息

默认情况下，Azure Blob Storage 输出绑定会自动生成 UUID 作为 blob 文件名，并且不会为其分配任何系统或自定义元数据。可以在消息的元数据属性中配置（均为可选）。

向 Azure Blob Storage 输出绑定发布的应用程序应发送以下格式的消息：

{
    "data": "file content",
    "metadata": {
        "blobName"           : "filename.txt",
        "contentType"        : "text/plain",
        "contentMD5"         : "vZGKbMRDAnMs4BIwlXaRvQ==",
        "contentEncoding"    : "UTF-8",
        "contentLanguage"    : "en-us",
        "contentDisposition" : "attachment",
        "cacheControl"       : "no-cache",
        "custom"             : "hello-world"
    },
    "operation": "create"
}

1.11 - Azure Cosmos DB (Gremlin API) 绑定规范

Azure Cosmos DB (Gremlin API) 绑定组件的详细文档

组件格式

若要设置 Azure Cosmos DB (Gremlin API) 绑定，请创建类型为 bindings.azure.cosmosdb.gremlinapi 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.cosmosdb.gremlinapi
  version: v1
  metadata:
  - name: url
    value: "wss://******.gremlin.cosmos.azure.com:443/"
  - name: masterKey
    value: "*****"
  - name: username
    value: "*****"

警告

上述示例将密钥以纯文本字符串形式使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`url`	Y	输出	Gremlin API 的 Cosmos DB URL	`"wss://******.gremlin.cosmos.azure.com:443/"`
`masterKey`	Y	输出	Cosmos DB 账户主密钥	`"masterKey"`
`username`	Y	输出	Cosmos DB 数据库的用户名	`"/dbs/<database_name>/colls/<graph_name>"`

有关更多信息，请参阅快速入门：使用 Gremlin 的 Azure Cosmos Graph DB。

绑定支持

此组件支持输出绑定，包含以下操作：

query

请求负载示例

{
  "data": {
    "gremlin": "g.V().count()"
    },
  "operation": "query"
}

1.12 - Azure Cosmos DB (SQL API) 绑定规范

Azure Cosmos DB (SQL API) 绑定组件的详细文档

组件格式

若要设置 Azure Cosmos DB 绑定，需创建一个类型为 bindings.azure.cosmosdb 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.cosmosdb
  version: v1
  metadata:
  - name: url
    value: "https://******.documents.azure.com:443/"
  - name: masterKey
    value: "*****"
  - name: database
    value: "OrderDb"
  - name: collection
    value: "Orders"
  - name: partitionKey
    value: "<message>"

Warning

以上示例将密钥作为明文字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`url`	Y	输出	Cosmos DB URL	`"https://******.documents.azure.com:443/"`
`masterKey`	Y	输出	Cosmos DB 账户主密钥	`"master-key"`
`database`	Y	输出	Cosmos DB 数据库名称	`"OrderDb"`
`collection`	Y	输出	数据库中容器的名称。	`"Orders"`
`partitionKey`	Y	输出	从载荷中提取的、用作分区键的键的名称（待创建的文档）。该名称必须与创建 Cosmos DB 容器时指定的分区键一致。	`"OrderId"`、`"message"`

更多信息请参见 Azure Cosmos DB 资源模型。

Microsoft Entra ID 身份验证

Azure Cosmos DB 绑定组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据所选 Microsoft Entra ID 身份验证机制需提供的相应组件元数据字段，请参阅对 Azure 进行身份验证的文档。

你可以在以下部分中阅读有关使用 Azure AD 身份验证设置 Cosmos DB 的更多信息。

绑定支持

该组件支持输出绑定，包含以下操作：

create

生产环境最佳实践

Azure Cosmos DB 在单个 Azure Cosmos DB 账户的所有数据库之间共享严格的元数据请求速率限制。与 Azure Cosmos DB 的新连接会占用允许的请求速率限制的很大一部分。（参见 Cosmos DB 文档）

因此必须采取若干策略来避免与 Azure Cosmos DB 同时建立新连接：

确保应用程序的边车仅在需要时才加载 Azure Cosmos DB 组件，以避免不必要的数据库连接。这可以通过将组件限定于特定应用程序来实现。
选择顺序部署或启动应用程序的部署策略，以最大限度地减少到 Azure Cosmos DB 账户的新连接突增。
避免为不相关的数据库或系统复用同一个 Azure Cosmos DB 账户（即使在 Dapr 之外）。不同的 Azure Cosmos DB 账户具有不同的速率限制。
增加 initTimeout 值，允许组件在边车初始化期间重试连接到 Azure Cosmos DB，最长可达 5 分钟。默认值为 5s，应该增加。使用 Kubernetes 时，增加此值可能还需要更新就绪和存活探针。

spec:
  type: bindings.azure.cosmosdb
  version: v1
  initTimeout: 5m
  metadata:

数据格式

输出绑定的 create 操作要求每个待创建文档的载荷中存在以下键：

id：待创建文档的唯一 ID
<partitionKey>：通过组件定义中的 spec.partitionKey 指定的分区键名称。这也必须与创建 Cosmos DB 容器时指定的分区键一致。

为使用 Azure AD 身份验证设置 Cosmos DB

使用 Dapr Cosmos DB 绑定并通过 Azure AD 进行身份验证时，你需要执行一些额外步骤来设置环境。

先决条件：

你需要根据对 Azure 进行身份验证页面中的说明创建一个服务主体。下面的命令需要该服务主体的 ID（请注意，这与应用程序的客户端 ID 或你在元数据中用于 azureClientId 的值不同）。
Azure CLI
jq
以下脚本针对 bash 或 zsh shell 进行了优化

使用 Cosmos DB 绑定时，你不需要像使用 Cosmos DB 状态存储那样创建存储过程。

授予你的 Azure AD 应用程序访问 Cosmos DB 的权限

你可以在官方文档中找到更多信息，包括分配更精细权限的说明。

为了授予你的应用程序访问存储在 Cosmos DB 中的数据的权限，你需要为 Cosmos DB 数据平面分配一个自定义角色。在本例中，你将使用内置角色 “Cosmos DB Built-in Data Contributor”，该角色授予你的应用程序对数据的完全读写访问权限；你也可以按照官方文档中的说明创建自定义的、精细调整的角色。

# 包含你的 Cosmos DB 的资源组名称
RESOURCE_GROUP="..."
# 你的 Cosmos DB 账户名称
ACCOUNT_NAME="..."
# 你的服务主体对象 ID
PRINCIPAL_ID="..."
# "Cosmos DB Built-in Data Contributor" 角色的 ID
# 你也可以使用自定义角色的 ID
ROLE_ID="00000000-0000-0000-0000-000000000002"

az cosmosdb sql role assignment create \
  --account-name "$ACCOUNT_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --scope "/" \
  --principal-id "$PRINCIPAL_ID" \
  --role-definition-id "$ROLE_ID"

1.13 - Azure Event Grid 绑定规范

Azure Event Grid 绑定组件的详细文档

组件格式

若要设置 Azure Event Grid 绑定，请创建类型为 bindings.azure.eventgrid 的组件。请参阅此指南了解如何创建和应用绑定配置。

请参阅此处了解 Azure Event Grid 的文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <name>
spec:
  type: bindings.azure.eventgrid
  version: v1
  metadata:
  # 必需的输出绑定元数据
  - name: accessKey
    value: "[AccessKey]"
  - name: topicEndpoint
    value: "[TopicEndpoint]"
  # 必需的输入绑定元数据
  - name: azureTenantId
    value: "[AzureTenantId]"
  - name: azureSubscriptionId
    value: "[AzureSubscriptionId]"
  - name: azureClientId
    value: "[ClientId]"
  - name: azureClientSecret
    value: "[ClientSecret]"
  - name: subscriberEndpoint
    value: "[SubscriberEndpoint]"
  - name: handshakePort
    # 确保将此值作为字符串传递，并在值周围加上引号
    value: "[HandshakePort]"
  - name: scope
    value: "[Scope]"
  # 可选的输入绑定元数据
  - name: eventSubscriptionName
    value: "[EventSubscriptionName]"
  # 可选元数据
  - name: direction
    value: "input, output"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的说明，使用密钥存储来管理密钥。

规范元数据字段

字段	必需	绑定支持	详情	示例
`accessKey`	Y	Output	用于将 Event Grid 事件发布到自定义主题的访问密钥	`"accessKey"`
`topicEndpoint`	Y	Output	此输出绑定应向其发布事件的主题端点	`"topic-endpoint"`
`azureTenantId`	Y	Input	Event Grid 资源的 Azure 租户 ID	`"tenentID"`
`azureSubscriptionId`	Y	Input	Event Grid 资源的 Azure 订阅 ID	`"subscriptionId"`
`azureClientId`	Y	Input	绑定应使用此客户端 ID 来创建或更新 Event Grid 事件订阅并对传入消息进行身份验证	`"clientId"`
`azureClientSecret`	Y	Input	绑定应使用此客户端 ID 来创建或更新 Event Grid 事件订阅并对传入消息进行身份验证	`"clientSecret"`
`subscriberEndpoint`	Y	Input	Event Grid 将事件（格式化为 Cloud Events）发送到的 webhook 的 HTTPS 端点。如果你不在入站时重写 URL，它的格式应为：`"https://[YOUR HOSTNAME]/<path>"` 如果在本地计算机上测试，可以使用 ngrok 之类的工具来创建公共端点。	`"https://[YOUR HOSTNAME]/<path>"`
`handshakePort`	Y	Input	输入绑定在 webhook 上接收事件时监听的容器端口	`"9000"`
`scope`	Y	Input	需要创建或更新事件订阅的资源的标识符。有关更多详细信息，请参阅作用域部分	`"/subscriptions/{subscriptionId}/"`
`eventSubscriptionName`	N	Input	事件订阅的名称。事件订阅名称的长度必须介于 3 到 64 个字符之间，并且应仅使用字母数字字符	`"name"`
`direction`	N	Input/Output	绑定的方向	`"input"`、`"output"`、`"input, output"`

作用域

作用域是需要创建或更新事件订阅的资源的标识符。作用域可以是订阅、资源组、属于资源提供程序命名空间的顶级资源，或 Event Grid 主题。例如：

/subscriptions/{subscriptionId}/ 表示订阅
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName} 表示资源组
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName} 表示资源
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName} 表示 Event Grid 主题

花括号 {} 中的值应替换为实际值。

绑定支持

此组件支持输入和输出绑定接口。

此组件支持输出绑定，具有以下操作：

create：在 Event Grid 主题上发布消息

接收事件

你可以使用 Event Grid 绑定从各种来源和操作接收事件。了解有关与 Event Grid 兼容的所有可用事件源和处理程序的更多信息。

在下表中，你可以找到可以引发事件的 Dapr 组件列表。

事件源	Dapr 组件
Azure Blob Storage	Azure Blob Storage 绑定 Azure Blob Storage 状态存储
Azure Cache for Redis	Redis 绑定 Redis 发布订阅
Azure Event Hubs	Azure Event Hubs 发布订阅 Azure Event Hubs 绑定
Azure IoT Hub	Azure Event Hubs 发布订阅 Azure Event Hubs 绑定
Azure Service Bus	Azure Service Bus 绑定 Azure Service Bus 发布订阅主题和队列
Azure SignalR Service	SignalR 绑定

Microsoft Entra ID 凭据

Azure Event Grid 绑定需要 Microsoft Entra ID 应用程序和服务主体，原因有两个：

在 Dapr 启动时创建事件订阅（并在 Dapr 配置更改时更新它）
对 Event Hubs 传送到你的应用程序的消息进行身份验证。

要求：

已安装 Azure CLI。
已安装 PowerShell 7。
已安装用于 PowerShell 的 Az 模块：
Install-Module Az -Scope CurrentUser -Repository PSGallery -Force
已安装用于 PowerShell 的 Microsoft.Graph 模块：
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force

对于第一个目的，你需要创建 Azure 服务主体。创建后，记下 Microsoft Entra ID 应用程序的 clientID（一个 UUID），并使用 Azure CLI 运行以下脚本：

# 设置你创建的应用的客户端 ID
CLIENT_ID="..."
# 资源的范围，通常格式为：
# `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}`
SCOPE="..."

# 首先确保已为 Event Grid 注册 Azure Resource Manager 提供程序
az provider register --namespace "Microsoft.EventGrid"
az provider show --namespace "Microsoft.EventGrid" --query "registrationState"
# 授予 SP 所需的权限，以便它可以创建 Event Grid 的事件订阅
az role assignment create --assignee "$CLIENT_ID" --role "EventGrid EventSubscription Contributor" --scopes "$SCOPE"

对于第二个目的，首先下载一个脚本：

curl -LO "https://raw.githubusercontent.com/dapr/components-contrib/master/.github/infrastructure/conformance/azure/setup-eventgrid-sp.ps1"

然后，使用 PowerShell（pwsh），运行：

# 设置你创建的应用的客户端 ID
$clientId = "..."

# 使用 Microsoft Graph 进行身份验证
# 如果需要，你可能需要在下一个命令中添加 -TenantId 标志
Connect-MgGraph -Scopes "Application.Read.All","Application.ReadWrite.All"
./setup-eventgrid-sp.ps1 $clientId

注意：如果你的目录没有为应用程序"Microsoft.EventGrid"设置服务主体，你可能需要运行命令 Connect-MgGraph 并以 Microsoft Entra ID 租户的管理员身份登录（这与 Microsoft Entra ID 目录上的权限有关，而不是 Azure 订阅）。否则，请让你的租户管理员登录并运行此 PowerShell 命令：New-MgServicePrincipal -AppId "4962773b-9cdb-44cf-a8bf-237846a00ab7"（该 UUID 是一个常量）

本地测试

安装 ngrok
使用自定义端口（例如 9000）在本地运行，用于握手

# 以端口 9000 为例
ngrok http --host-header=localhost 9000

将 ngrok 的 HTTPS 端点和自定义端口配置为输入绑定元数据
运行 Dapr

# 以 .NET core web api 和 Dapr 的默认端口为例
dapr run --app-id dotnetwebapi --app-port 5000 --dapr-http-port 3500 dotnet run

在 Kubernetes 上测试

Azure Event Grid 需要有效的 HTTPS 端点用于自定义 webhook；不接受自签名证书。为了启用从公共互联网到应用程序的 Dapr 边车的流量，你需要一个启用了 Dapr 的入口控制器。有一篇关于此主题的好文章：Kubernetes NGINX ingress controller with Dapr。

若要开始，首先为 Dapr 注释创建一个 dapr-annotations.yaml 文件：

controller:
  podAnnotations:
    dapr.io/enabled: "true"
    dapr.io/app-id: "nginx-ingress"
    dapr.io/app-port: "80"

然后使用这些注释，使用 Helm 3 将 NGINX 入口控制器安装到 Kubernetes 集群：

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install nginx-ingress ingress-nginx/ingress-nginx -f ./dapr-annotations.yaml -n default
# 获取入口控制器的公共 IP
kubectl get svc -l component=controller -o jsonpath='Public IP is: {.items[0].status.loadBalancer.ingress[0].ip}{"\n"}'

如果部署到 Azure Kubernetes Service，你可以按照Microsoft 官方文档完成剩余步骤：

向你的 DNS 区域添加 A 记录
安装 cert-manager
创建 CA 集群颁发者

启用 Event Grid 和 Dapr 之间通信的最后一步是为应用程序的服务定义 http 和自定义端口，并在 Kubernetes 中定义 ingress。此示例使用 .NET Core web api 和 Dapr 默认端口，以及自定义端口 9000 用于握手。

# dotnetwebapi.yaml
kind: Service
apiVersion: v1
metadata:
  name: dotnetwebapi
  labels:
    app: dotnetwebapi
spec:
  selector:
    app: dotnetwebapi
  ports:
    - name: webapi
      protocol: TCP
      port: 80
      targetPort: 80
    - name: dapr-eventgrid
      protocol: TCP
      port: 9000
      targetPort: 9000
  type: ClusterIP

---
  apiVersion: extensions/v1beta1
  kind: Ingress
  metadata:
    name: eventgrid-input-rule
    annotations:
      kubernetes.io/ingress.class: nginx
      cert-manager.io/cluster-issuer: letsencrypt
  spec:
    tls:
      - hosts:
        - dapr.<your custom domain>
        secretName: dapr-tls
    rules:
      - host: dapr.<your custom domain>
        http:
          paths:
            - path: /api/events
              backend:
                serviceName: dotnetwebapi
                servicePort: 9000

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dotnetwebapi
  labels:
    app: dotnetwebapi
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dotnetwebapi
  template:
    metadata:
      labels:
        app: dotnetwebapi
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "dotnetwebapi"
        dapr.io/app-port: "5000"
    spec:
      containers:
      - name: webapi
        image: <your container image>
        ports:
        - containerPort: 5000
        imagePullPolicy: Always

将绑定和应用程序（包括入口）部署到 Kubernetes

# 部署 Dapr 组件
kubectl apply -f eventgrid.yaml
# 部署你的应用程序和 Nginx 入口
kubectl apply -f dotnetwebapi.yaml

注意： 此清单将所有内容部署到 Kubernetes 的默认命名空间。

对 Nginx 控制器的可能问题进行故障排除

初始部署后，“Daprized” Nginx 控制器可能会发生故障。要检查日志并修复问题（如果存在），请按照以下步骤操作。

$ kubectl get pods -l app=nginx-ingress

NAME                                                   READY   STATUS    RESTARTS   AGE
nginx-nginx-ingress-controller-649df94867-fp6mg        2/2     Running   0          51m
nginx-nginx-ingress-default-backend-6d96c457f6-4nbj5   1/1     Running   0          55m

$ kubectl logs nginx-nginx-ingress-controller-649df94867-fp6mg nginx-ingress-controller

# 如果你在日志中看到从对 webhook 端点 '/api/events' 的调用返回 503，则重启 Pod
# .."OPTIONS /api/events HTTP/1.1" 503..

$ kubectl delete pod nginx-nginx-ingress-controller-649df94867-fp6mg

# 再次检查日志 - 它应该开始返回 200
# .."OPTIONS /api/events HTTP/1.1" 200..

1.14 - Azure Event Hubs 绑定规约

Azure Event Hubs 绑定组件的详细文档

组件格式

要设置 Azure Event Hubs 绑定，请创建一个类型为 bindings.azure.eventhubs 的组件。请参阅此指南了解如何创建和应用绑定配置。

请参阅此文档了解如何设置 Event Hub。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.eventhubs
  version: v1
  metadata:
    # Hub 名称（"topic"）
    - name: eventHub
      value: "mytopic"
    - name: consumerGroup
      value: "myapp"
    # connectionString 或 eventHubNamespace 其中之一是必需的
    # 当*不*使用 Microsoft Entra ID 时使用 connectionString
    - name: connectionString
      value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"
    # 使用 Microsoft Entra ID 时使用 eventHubNamespace
    - name: eventHubNamespace
      value: "namespace"
    - name: enableEntityManagement
      value: "false"
    - name: enableInOrderMessageDelivery
      value: "false"
    # 仅当 enableEntityManagement 设置为 true 时才需要以下四个属性
    - name: resourceGroupName
      value: "test-rg"
    - name: subscriptionID
      value: "value of Azure subscription ID"
    - name: partitionCount
      value: "1"
    - name: messageRetentionInDays
      value: "3"
    # 检查点存储属性
    - name: storageAccountName
      value: "myeventhubstorage"
    - name: storageAccountKey
      value: "112233445566778899"
    - name: storageContainerName
      value: "myeventhubstoragecontainer"
    # 传递 storageAccountKey 的替代方案
    - name: storageConnectionString
      value: "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<account-key>"
    # 可选元数据
    - name: getAllMessageProperties
      value: "true"
    - name: direction
      value: "input, output"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规格元数据字段

字段	必填	绑定支持	详情	示例
`eventHub`	Y*	输入/输出	Event Hubs hub 的名称（“topic”）。当使用 Microsoft Entra ID 身份验证或连接字符串不包含 `EntityPath` 值时必需	`mytopic`
`connectionString`	Y*	输入/输出	Event Hub 或 Event Hub 命名空间的连接字符串。 * 与 `eventHubNamespace` 字段互斥。 * 当不使用 Microsoft Entra ID 身份验证时必需	`"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` 或 `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}"`
`eventHubNamespace`	Y*	输入/输出	Event Hub 命名空间名称。 * 与 `connectionString` 字段互斥。 * 当使用 Microsoft Entra ID 身份验证时必需	`"namespace"`
`enableEntityManagement`	N	输入/输出	允许管理 EventHub 命名空间和存储帐户的布尔值。默认值：`false`	`"true"`, `"false"`
`enableInOrderMessageDelivery`	N	输入/输出	允许按发布顺序传递消息的布尔值。这假设在发布或发布时设置了 `partitionKey` 以确保跨分区的顺序。默认值：`false`	`"true"`, `"false"`
`resourceGroupName`	N	输入/输出	Event Hub 命名空间所属的资源组名称。当启用实体管理时必需	`"test-rg"`
`subscriptionID`	N	输入/输出	Azure 订阅 ID 值。当启用实体管理时必需	`"azure subscription id"`
`partitionCount`	N	输入/输出	新 Event Hub 命名空间的分区数。仅在启用实体管理时使用。默认值：`"1"`	`"2"`
`messageRetentionInDays`	N	输入/输出	在新创建的 Event Hub 命名空间中保留消息的天数。仅在启用实体管理时使用。默认值：`"1"`	`"90"`
`consumerGroup`	Y	输入	要侦听的 Event Hubs 消费者组的名称	`"group1"`
`storageAccountName`	Y	输入	用于检查点存储的存储帐户名称。	`"myeventhubstorage"`
`storageAccountKey`	Y*	输入	检查点存储帐户的存储帐户密钥。 * 使用 Microsoft Entra ID 时，如果服务主体也有权访问存储帐户，则可以省略此字段。	`"112233445566778899"`
`storageConnectionString`	Y*	输入	检查点存储的连接字符串，是指定 `storageAccountKey` 的替代方案	`"DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>"`
`storageContainerName`	Y	输入	存储帐户名称的存储容器名称。	`"myeventhubstoragecontainer"`
`getAllMessageProperties`	N	输入	当设置为 `true` 时，从 Event Hub 消息中检索所有用户/应用程序/自定义属性，并在返回的事件元数据中转发它们。默认设置为 `"false"`。	`"true"`, `"false"`
`direction`	N	输入/输出	绑定的方向。	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID 身份验证

Azure Event Hubs 发布/订阅组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的相关组件元数据字段，请参阅向 Azure 进行身份验证的文档。

绑定支持

此组件支持输出绑定，具有以下操作：

create：向 Azure Event Hubs 发布新消息

输入绑定到 Azure IoT Hub 事件

Azure IoT Hub 提供一个与 Event Hubs 兼容的端点，因此 Dapr 应用程序可以创建输入绑定，使用 Event Hubs 绑定组件来读取 Azure IoT Hub 事件。

由 Azure IoT Hub 设备创建的设备到云事件将包含其他IoT Hub 系统属性，Dapr 的 Azure Event Hubs 绑定将在响应元数据中返回以下内容：

系统属性名称	描述与路由查询关键字
`iothub-connection-auth-generation-id`	发送消息的设备的 connectionDeviceGenerationId。请参阅 IoT Hub 设备标识属性。
`iothub-connection-auth-method`	用于对发送消息的设备进行身份验证的 connectionAuthMethod。
`iothub-connection-device-id`	发送消息的设备的 deviceId。请参阅 IoT Hub 设备标识属性。
`iothub-connection-module-id`	发送消息的设备的 moduleId。请参阅 IoT Hub 设备标识属性。
`iothub-enqueuedtime`	设备到云消息被 IoT Hub 接收的 enqueuedTime，采用 RFC3339 格式。
`message-id`	用户可设置的 AMQP messageId。

例如，HTTP Read() 响应的标头将包含：

{
  'user-agent': 'fasthttp',
  'host': '127.0.0.1:3000',
  'content-type': 'application/json',
  'content-length': '120',
  'iothub-connection-device-id': 'my-test-device',
  'iothub-connection-auth-generation-id': '637618061680407492',
  'iothub-connection-auth-method': '{"scope":"module","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}',
  'iothub-connection-module-id': 'my-test-module-a',
  'iothub-enqueuedtime': '2021-07-13T22:08:09Z',
  'message-id': 'my-custom-message-id',
  'x-opt-sequence-number': '35',
  'x-opt-enqueued-time': '2021-07-13T22:08:09Z',
  'x-opt-offset': '21560',
  'traceparent': '00-4655608164bc48b985b42d39865f3834-ed6cf3697c86e7bd-01'
}

1.15 - Azure OpenAI binding 规范

Azure OpenAI binding 组件的详细文档

组件格式

若要设置 Azure OpenAI binding，请创建类型为 bindings.azure.openai 的组件。请参阅本指南了解如何创建和应用 binding 配置。请参阅此处获取 Azure OpenAI 服务的文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.openai
  version: v1
  metadata:
  - name: apiKey # 必填
    value: "1234567890abcdef"
  - name: endpoint # 必填
    value: "https://myopenai.openai.azure.com"

警告

上述示例将 apiKey 作为纯字符串使用。建议按照此处所述使用 secret store 来管理密钥。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`endpoint`	Y	Output	Azure OpenAI 服务端点 URL。	`"https://myopenai.openai.azure.com"`
`apiKey`	Y*	Output	Azure OpenAI 服务的访问密钥。仅在不使用 Microsoft Entra ID 身份验证时需要。	`"1234567890abcdef"`
`azureTenantId`	Y*	Input	Azure OpenAI 资源的租户 ID。仅当未提供 `apiKey` 时需要。	`"tenentID"`
`azureClientId`	Y*	Input	Binding 应使用的客户端 ID，用于创建或更新 Azure OpenAI 订阅并对传入消息进行身份验证。仅当未提供 `apiKey` 时需要。	`"clientId"`
`azureClientSecret`	Y*	Input	Binding 应使用的客户端密钥，用于创建或更新 Azure OpenAI 订阅并对传入消息进行身份验证。仅当未提供 `apiKey` 时需要。	`"clientSecret"`

Microsoft Entra ID 身份验证

Azure OpenAI binding 组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的组件元数据字段，请参阅向 Azure 进行身份验证的文档。

配置示例

apiVersion: dapr.io/v1alpha1
kind: component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.openai
  version: v1
  metadata:
  - name: endpoint
    value: "https://myopenai.openai.azure.com"
  - name: azureTenantId
    value: "***"
  - name: azureClientId
    value: "***"
  - name: azureClientSecret
    value: "***"

Binding 支持

此组件支持以下操作的输出 binding：

completion：补全 API
chat-completion：聊天补全 API
get-embedding：嵌入 API

Completion API

要使用提示调用补全 API，请使用 POST 方法调用 Azure OpenAI binding，并使用以下 JSON 请求体：

{
  "operation": "completion",
  "data": {
    "deploymentId": "my-model",
    "prompt": "A dog is",
    "maxTokens":5
    }
}

数据参数包括：

deploymentId - 指定要使用的模型部署 ID 的字符串。
prompt - 指定要生成补全的提示的字符串。
maxTokens - （可选）定义要生成的 token 最大数量。补全 API 默认为 16。
temperature - （可选）定义 0 到 2 之间的采样温度。较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）则使其更加聚焦和确定性。补全 API 默认为 1.0。
topP - （可选）定义采样温度。补全 API 默认为 1.0。
n - （可选）定义要生成的补全数量。补全 API 默认为 1。
presencePenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值会根据新 token 是否出现在已有文本中来对其进行惩罚，从而增加模型谈论新主题的可能性。补全 API 默认为 0.0。
frequencyPenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值会根据新 token 在已有文本中的现有频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。补全 API 默认为 0.0。

在 Azure OpenAI API 文档中阅读有关这些参数的重要性和用法的更多信息。

示例

curl -d '{ "data": {"deploymentId: "my-model" , "prompt": "A dog is ", "maxTokens":15}, "operation": "completion" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下 JSON：

[
  {
    "finish_reason": "length",
    "index": 0,
    "text": " a pig in a dress.\n\nSun, Oct 20, 2013"
  },
  {
    "finish_reason": "length",
    "index": 1,
    "text": " the only thing on earth that loves you\n\nmore than he loves himself.\"\n\n"
  }
]

Chat Completion API

要执行聊天补全操作，请使用 POST 方法调用 Azure OpenAI binding，并使用以下 JSON 请求体：

{
    "operation": "chat-completion",
    "data": {
        "deploymentId": "my-model",
        "messages": [
            {
                "role": "system",
                "message": "You are a bot that gives really short replies"
            },
            {
                "role": "user",
                "message": "Tell me a joke"
            }
        ],
        "n": 2,
        "maxTokens": 30,
        "temperature": 1.2
    }
}

数据参数包括：

deploymentId - 指定要使用的模型部署 ID 的字符串。
messages - 将用于生成聊天补全的消息数组。每条消息的格式为：
- role - 指定消息角色的字符串。可以是 user、system 或 assistant。
- message - 指定该角色的对话消息的字符串。
maxTokens - （可选）定义要生成的 token 最大数量。聊天补全 API 默认为 16。
temperature - （可选）定义 0 到 2 之间的采样温度。较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）则使其更加聚焦和确定性。聊天补全 API 默认为 1.0。
topP - （可选）定义采样温度。聊天补全 API 默认为 1.0。
n - （可选）定义要生成的补全数量。聊天补全 API 默认为 1。
presencePenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值会根据新 token 是否出现在已有文本中来对其进行惩罚，从而增加模型谈论新主题的可能性。聊天补全 API 默认为 0.0。
frequencyPenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值会根据新 token 在已有文本中的现有频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。聊天补全 API 默认为 0.0。

示例

curl -d '{
  "data": {
      "deploymentId": "my-model",
      "messages": [
          {
              "role": "system",
              "message": "You are a bot that gives really short replies"
          },
          {
              "role": "user",
              "message": "Tell me a joke"
          }
      ],
      "n": 2,
      "maxTokens": 30,
      "temperature": 1.2
  },
  "operation": "chat-completion"
}' \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下 JSON：

[
  {
    "finish_reason": "stop",
    "index": 0,
    "message": {
      "content": "Why was the math book sad? Because it had too many problems.",
      "role": "assistant"
    }
  },
  {
    "finish_reason": "stop",
    "index": 1,
    "message": {
      "content": "Why did the tomato turn red? Because it saw the salad dressing!",
      "role": "assistant"
    }
  }
]

Get Embedding API

get-embedding 操作返回给定输入的向量表示，可以轻松被机器学习模型和其他算法使用。要执行 get-embedding 操作，请使用 POST 方法调用 Azure OpenAI binding，并使用以下 JSON 请求体：

{
    "operation": "get-embedding",
    "data": {
        "deploymentId": "my-model",
        "message": "The capital of France is Paris."
    }
}

数据参数包括：

deploymentId - 指定要使用的模型部署 ID 的字符串。
message - 指定要嵌入的文本的字符串。

示例

curl -d '{
  "data": {
      "deploymentId": "embeddings",
      "message": "The capital of France is Paris."
  },
  "operation": "get-embedding"
}' \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下 JSON：

[0.018574921,-0.00023652936,-0.0057790717,.... (ada 总共 1536 个浮点数)]

了解有关 Azure OpenAI 输出 binding 的更多信息

观看以下社区呼叫演示以了解有关 Azure OpenAI 输出 binding 的更多信息。

1.16 - Azure Service Bus Queues 绑定规范

Azure Service Bus Queues 绑定组件的详细文档

组件格式

要设置 Azure Service Bus Queues 绑定，请创建类型为 bindings.azure.servicebusqueues 的组件。有关如何创建和应用绑定配置，请参阅此指南。

连接字符串身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.servicebusqueues
  version: v1
  metadata:
  - name: connectionString # 当不使用 Azure 身份验证时必需。
    value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}"
  - name: queueName
    value: "queue1"
  # - name: timeoutInSec # 可选
  #   value: "60"
  # - name: handlerTimeoutInSec # 可选
  #   value: "60"
  # - name: disableEntityManagement # 可选
  #   value: "false"
  # - name: maxDeliveryCount # 可选
  #   value: "3"
  # - name: lockDurationInSec # 可选
  #   value: "60"
  # - name: lockRenewalInSec # 可选
  #   value: "20"
  # - name: maxActiveMessages # 可选
  #   value: "10000"
  # - name: maxConcurrentHandlers # 可选
  #   value: "10"
  # - name: defaultMessageTimeToLiveInSec # 可选
  #   value: "10"
  # - name: autoDeleteOnIdleInSec # 可选
  #   value: "3600"
  # - name: minConnectionRecoveryInSec # 可选
  #   value: "2"
  # - name: maxConnectionRecoveryInSec # 可选
  #   value: "300"
  # - name: maxRetriableErrorsPerSec # 可选
  #   value: "10"
  # - name: publishMaxRetries # 可选
  #   value: "5"
  # - name: publishInitialRetryIntervalInMs # 可选
  #   value: "500"
  # - name: direction
  #   value: "input, output"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详细说明	示例
`connectionString`	Y	输入/输出	Service Bus 连接字符串。除非使用 Microsoft Entra ID 身份验证，否则为必需。	`"Endpoint=sb://************"`
`queueName`	Y	输入/输出	Service Bus 队列名称。队列名称不区分大小写，并将始终被强制转换为小写。	`"queuename"`
`timeoutInSec`	N	输入/输出	对 Azure Service Bus 端点的所有调用的超时时间（秒）。请注意，此选项影响网络调用，与应用于消息的 TTL 无关。默认值：`"60"`	`"60"`
`namespaceName`	N	输入/输出	用于设置 Service Bus 命名空间地址的参数，格式为完全限定域名。如果使用 Microsoft Entra ID 身份验证，则为必需。	`"namespace.servicebus.windows.net"`
`disableEntityManagement`	N	输入/输出	当设置为 true 时，队列和订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
`lockDurationInSec`	N	输入/输出	定义消息在过期前被锁定的时间长度（秒）。仅在订阅创建期间使用。默认值由服务器设置。	`"30"`
`autoDeleteOnIdleInSec`	N	输入/输出	在自动删除空闲订阅之前等待的时间（秒）。仅在订阅创建期间使用。必须大于或等于 300 秒。默认值：`"0"`（禁用）	`"3600"`
`defaultMessageTimeToLiveInSec`	N	输入/输出	默认消息生存时间（秒）。仅在订阅创建期间使用。	`"10"`
`maxDeliveryCount`	N	输入/输出	定义服务器尝试传递消息的次数。仅在订阅创建期间使用。默认值由服务器设置。	`"10"`
`minConnectionRecoveryInSec`	N	输入/输出	在连接失败时尝试重新连接到 Azure Service Bus 之前等待的最小时间间隔（秒）。默认值：`"2"`	`"5"`
`maxConnectionRecoveryInSec`	N	输入/输出	在连接失败时尝试重新连接到 Azure Service Bus 之前等待的最大时间间隔（秒）。每次尝试后，组件会在最小值和最大值之间等待一个随机秒数，且每次递增。默认值：`"300"`（5 分钟）	`"600"`
`maxActiveMessages`	N	定义一次要处理或在缓冲区中的最大消息数。此值应至少与最大并发处理程序数一样大。默认值：`"1"`	`"1"`
`handlerTimeoutInSec`	N	输入	调用应用程序处理程序的超时时间。默认值：`"0"`（无超时）	`"30"`
`minConnectionRecoveryInSec`	N	输入	在连接失败时尝试重新连接到 Azure Service Bus 之前等待的最小时间间隔（秒）。默认值：`"2"`	`"5"`
`maxConnectionRecoveryInSec`	N	输入	在连接失败时尝试重新连接到 Azure Service Bus 之前等待的最大时间间隔（秒）。每次尝试后，绑定会在最小值和最大值之间等待一个随机秒数，且每次递增。默认值：`"300"`（5 分钟）	`"600"`
`lockRenewalInSec`	N	输入	定义缓冲消息锁的续订频率。默认值：`"20"`。	`"20"`
`maxActiveMessages`	N	输入	定义一次要处理或在缓冲区中的最大消息数。此值应至少与最大并发处理程序数一样大。默认值：`"1"`	`"2000"`
`maxConcurrentHandlers`	N	输入	定义最大并发消息处理程序数；设置为 `0` 表示无限制。默认值：`"1"`	`"10"`
`maxRetriableErrorsPerSec`	N	输入	每秒处理的最大可重试错误数。如果消息处理失败并出现可重试错误，组件会在开始处理另一条消息之前添加延迟，以避免立即重新处理失败的消息。默认值：`"10"`	`"10"`
`publishMaxRetries`	N	输出	当 Azure Service Bus 响应"太忙"以限制消息时的最大重试次数。默认值：`"5"`	`"5"`
`publishInitialRetryIntervalInMs`	N	输出	当 Azure Service Bus 限制消息时的初始指数退避时间（毫秒）。默认值：`"500"`	`"500"`
`direction`	N	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID 身份验证

Azure Service Bus Queues 绑定组件支持使用所有 Microsoft Entra ID 机制进行身份验证，包括托管标识。有关更多信息以及根据 Microsoft Entra ID 身份验证机制的选择提供的相应组件元数据字段，请参阅Azure 身份验证文档。

配置示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.servicebusqueues
  version: v1
  metadata:
  - name: azureTenantId
    value: "***"
  - name: azureClientId
    value: "***"
  - name: azureClientSecret
    value: "***"
  - name: namespaceName
    # 使用 Azure 身份验证时必需。
    # 必须是完全限定域名
    value: "servicebusnamespace.servicebus.windows.net"
  - name: queueName
    value: queue1
  - name: ttlInSeconds
    value: 60

绑定支持

此组件同时支持输入和输出绑定接口。

此组件支持输出绑定，具有以下操作：

create：将消息发布到指定的队列

消息元数据

Azure Service Bus 消息使用其他上下文元数据扩展了 Dapr 消息格式。某些元数据字段由 Azure Service Bus 本身设置（只读），其他字段可以在通过 Invoke 绑定调用发布消息时由客户端设置。

发送带有元数据的消息

要在发送消息时设置 Azure Service Bus 元数据，请在 HTTP 请求或 gRPC 元数据上设置查询参数，如此处所述。

metadata.MessageId
metadata.CorrelationId
metadata.SessionId
metadata.Label
metadata.ReplyTo
metadata.PartitionKey
metadata.To
metadata.ContentType
metadata.ScheduledEnqueueTimeUtc
metadata.ReplyToSessionId

注意

metadata.MessageId 属性不会设置 Dapr 返回的 cloud event 的 id 属性，应单独处理。
metadata.ScheduledEnqueueTimeUtc 属性支持 RFC1123 和 RFC3339 时间戳格式。

接收带有元数据的消息

当 Dapr 调用您的应用程序时，它会使用 HTTP 标头或 gRPC 元数据将 Azure Service Bus 消息元数据附加到请求中。除了上面列出的可设置元数据之外，您还可以访问以下只读消息元数据。

metadata.DeliveryCount
metadata.LockedUntilUtc
metadata.LockToken
metadata.EnqueuedTimeUtc
metadata.SequenceNumber

要了解有关这些元数据属性用途的更多详细信息，请参阅官方 Azure Service Bus 文档。

此外，原始 Azure Service Bus 消息的所有 ApplicationProperties 条目都会作为 metadata.<application property's name> 附加。

注意

所有时间都由服务器填充，不会针对时钟偏差进行调整。

为每条消息指定 TTL

生存时间可以在每个队列级别定义（如上所示）或在消息级别定义。在消息级别定义的值会覆盖在队列级别设置的任何值。

要在消息级别设置生存时间，请在绑定调用期间使用请求正文中的 metadata 部分：字段名称为 ttlInSeconds。

curl -X POST http://localhost:3500/v1.0/bindings/myServiceBusQueue \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "ttlInSeconds": "60"
        },
        "operation": "create"
      }'

计划消息

消息可以计划延迟处理。

要计划消息，请在绑定调用期间使用请求正文中的 metadata 部分：字段名称为 ScheduledEnqueueTimeUtc。

支持的时间戳格式为 RFC1123 和 RFC3339。

curl -X POST http://localhost:3500/v1.0/bindings/myServiceBusQueue \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "ScheduledEnqueueTimeUtc": "Tue, 02 Jan 2024 15:04:05 GMT"
        },
        "operation": "create"
      }'

1.17 - Azure SignalR 绑定规范

Azure SignalR 绑定组件的详细文档

组件格式

若要设置 Azure SignalR 绑定，需创建一个类型为 bindings.azure.signalr 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.signalr
  version: v1
  metadata:
  - name: connectionString
    value: "Endpoint=https://<your-azure-signalr>.service.signalr.net;AccessKey=<your-access-key>;Version=1.0;"
  - name: hub  # Optional
    value: "<hub name>"

Warning

上述示例将密钥以纯字符串形式使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`connectionString`	Y	Output	Azure SignalR 连接字符串	`"Endpoint=https://<your-azure-signalr>.service.signalr.net;AccessKey=<your-access-key>;Version=1.0;"`
`hub`	N	Output	定义消息发送到的 Hub。Hub 可以在发布到输出绑定时作为元数据值（键为 “hub”）动态定义	`"myhub"`
`endpoint`	N	Output	Azure SignalR 的终结点；如果 `connectionString` 中未包含或使用 Microsoft Entra ID 时必需	`"https://<your-azure-signalr>.service.signalr.net"`
`accessKey`	N	Output	访问密钥	`"your-access-key"`

Microsoft Entra ID 身份验证

Azure SignalR 绑定组件支持使用所有 Microsoft Entra ID 机制进行身份验证。请参阅向 Azure 进行身份验证的文档，根据您选择的 Microsoft Entra ID 身份验证机制了解相关组件元数据字段。

您可以通过两种选项使用 Microsoft Entra ID 对此组件进行身份验证：

传递单独的元数据键：
- endpoint 用于终结点
- 如需要：azureClientId、azureTenantId 和 azureClientSecret
传递指定了 AuthType=aad 的连接字符串：
- 系统分配的托管标识：Endpoint=https://<servicename>.service.signalr.net;AuthType=aad;Version=1.0;
- 用户分配的托管标识：Endpoint=https://<servicename>.service.signalr.net;AuthType=aad;ClientId=<clientid>;Version=1.0;
- Microsoft Entra ID 应用程序：Endpoint=https://<servicename>.service.signalr.net;AuthType=aad;ClientId=<clientid>;ClientSecret=<clientsecret>;TenantId=<tenantid>;Version=1.0;
  注意，如果您的应用程序的 ClientSecret 包含 ; 字符，则不能使用连接字符串。

绑定支持

此组件支持 输出绑定，具有以下操作：

create

其他信息

默认情况下，Azure SignalR 输出绑定将向所有已连接的用户广播消息。若要缩小受众范围，有两个选项，均可在消息的 Metadata 属性中进行配置：

group：将消息发送到特定的 Azure SignalR 组
user：将消息发送到特定的 Azure SignalR 用户

向 Azure SignalR 输出绑定发布的应用程序应发送具有以下合约的消息：

{
    "data": {
        "Target": "<enter message name>",
        "Arguments": [
            {
                "sender": "dapr",
                "text": "Message from dapr output binding"
            }
        ]
    },
    "metadata": {
        "group": "chat123"
    },
    "operation": "create"
}

有关将 Azure SignalR 集成到解决方案中的更多信息，请查看文档

1.18 - Azure Storage Queues binding spec

Detailed documentation on the Azure Storage Queues binding component

组件格式

若要设置 Azure Storage Queues 绑定，请创建类型为 bindings.azure.storagequeues 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.azure.storagequeues
  version: v1
  metadata:
  - name: accountName
    value: "account1"
  - name: accountKey
    value: "***********"
  - name: queueName
    value: "myqueue"
# - name: pollingInterval
#   value: "30s"
# - name: ttlInSeconds
#   value: "60"
# - name: decodeBase64
#   value: "false"
# - name: encodeBase64
#   value: "false"
# - name: endpoint
#   value: "http://127.0.0.1:10001"
# - name: visibilityTimeout
#   value: "30s"
# - name: initialVisibilityDelay
#   value: "30s"
# - name: direction 
#   value: "input, output"

Warning

上述示例将密钥以纯文本字符串形式使用。建议按照此处所述，使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详细信息	示例
`accountName`	Y	Input/Output	Azure 存储账户的名称	`"account1"`
`accountKey`	Y*	Input/Output	Azure 存储账户的访问密钥。仅在不使用 Microsoft Entra ID 身份验证时需要。	`"access-key"`
`queueName`	Y	Input/Output	Azure 存储队列的名称	`"myqueue"`
`pollingInterval`	N	Output	设置轮询 Azure Storage Queues 以获取新消息的间隔，以 Go duration 值表示。默认：`"10s"`	`"30s"`
`ttlInSeconds`	N	Output	用于设置默认消息生存时间的参数。如果省略此参数，消息将在 10 分钟后过期。另请参阅此处	`"60"`
`decodeBase64`	N	Input	配置是否将从存储队列接收的 base64 内容解码为字符串。默认为 `false`	`true`, `false`
`encodeBase64`	N	Output	如果启用，在上传到 Azure 存储队列之前将数据负载进行 base64 编码。默认 `false`。	`true`, `false`
`endpoint`	N	Input/Output	可选的自定义端点 URL。这在使用 Azurite 模拟器或为 Azure 存储使用自定义域时很有用（尽管后者不受官方支持）。端点必须是完整的基础 URL，包括协议（`http://` 或 `https://`）、IP 或 FQDN 以及可选端口。	`"http://127.0.0.1:10001"` 或 `"https://accountName.queue.example.com"`
`initialVisibilityDelay`	N	Input	允许设置自定义队列可见性超时，以避免立即重试最近失败的消息。默认为 30 秒。	`"100s"`
`visibilityTimeout`	N	Input	设置消息在添加到队列后变为可见之前的延迟。还可以通过在调用请求的元数据中设置 `initialVisibilityDelay` 属性来为每条消息指定此延迟。默认为 0 秒。	`"30s"`
`direction`	N	Input/Output	绑定的方向。	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID 身份验证

Azure Storage Queue 绑定组件支持使用所有 Microsoft Entra ID 机制进行身份验证。请参阅向 Azure 进行身份验证的文档，根据您选择的 Microsoft Entra ID 身份验证机制，了解相关的组件元数据字段。

绑定支持

此组件同时支持 输入和输出 绑定接口。

此组件支持具有以下操作的 输出绑定：

create

为每条消息指定 TTL

生存时间可以在队列级别定义（如上所示）或在消息级别定义。在消息级别定义的值会覆盖在队列级别设置的任何值。

要在消息级别设置生存时间，请在绑定调用期间使用请求正文中的 metadata 部分。

字段名称为 ttlInSeconds。

示例：

curl -X POST http://localhost:3500/v1.0/bindings/myStorageQueue \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "ttlInSeconds": "60"
        },
        "operation": "create"
      }'

为每条消息指定初始可见性延迟

初始可见性延迟可以在队列级别或消息级别定义。在消息级别定义的值会覆盖在队列级别设置的任何值。

要在消息级别设置初始可见性延迟值，请在绑定调用期间使用请求正文中的 metadata 部分。

字段名称为 initialVisbilityDelay。

示例：

curl -X POST http://localhost:3500/v1.0/bindings/myStorageQueue \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "initialVisbilityDelay": "30"
        },
        "operation": "create"
      }'

1.19 - Cloudflare Queues 绑定规范

Cloudflare Queues 组件的详细文档

组件格式

用于 Dapr 的此输出绑定允许与 Cloudflare Queues 交互以发布新消息。目前无法使用 Dapr 从队列消费消息。

要设置 Cloudflare Queues 绑定，请创建类型为 bindings.cloudflare.queues 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.cloudflare.queues
  version: v1
  # 如果 Dapr 正在为您管理 Worker，请增加 initTimeout
  initTimeout: "120s"
  metadata:
    # 现有 Cloudflare Queue 的名称（必需）
    - name: queueName
      value: ""
    # Worker 的名称（必需）
    - name: workerName
      value: ""
    # PEM 编码的 Ed25519 私钥（必需）
    - name: key
      value: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQ...
        -----END PRIVATE KEY-----
    # Cloudflare 账户 ID（让 Dapr 管理 Worker 所需）
    - name: cfAccountID
      value: ""
    # Cloudflare 的 API 令牌（让 Dapr 管理 Worker 所需）
    - name: cfAPIToken
      value: ""
    # Worker 的 URL（如果在 Dapr 之外预创建 Worker 则必需）
    - name: workerUrl
      value: ""

警告

上面的示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详细信息	示例
`queueName`	Y	输出	现有 Cloudflare Queue 的名称	`"mydaprqueue"`
`key`	Y	输出	Ed25519 私钥，PEM 编码	见上方示例
`cfAccountID`	Y/N	输出	Cloudflare 账户 ID。让 Dapr 管理 Worker 时必需。	`"456789abcdef8b5588f3d134f74ac"def`
`cfAPIToken`	Y/N	输出	Cloudflare 的 API 令牌。让 Dapr 管理 Worker 时必需。	`"secret-key"`
`workerUrl`	Y/N	输出	Worker 的 URL。如果在 Dapr 之外预配置 Worker 则必需。	`"https://mydaprqueue.mydomain.workers.dev`

当您配置 Dapr 为您创建 Worker 时，您可能需要为组件的 initTimeout 属性设置更长的值，以便为部署 Worker 脚本预留足够的时间。例如：initTimeout: "120s"

绑定支持

此组件支持具有以下操作的输出绑定：

publish（别名：create）：向队列发布消息。
传递给绑定的数据将按原样用作发布到队列的消息正文。
此操作不接受任何元数据属性。

创建 Cloudflare Queue

要使用此组件，您必须在 Cloudflare 账户中创建一个 Cloudflare Queue。

您可以通过以下两种方式之一创建新队列：

使用 Cloudflare 控制面板

使用 Wrangler CLI：

# 如需身份验证，请先执行 `npx wrangler login`
npx wrangler queues create <NAME>
# 例如：`npx wrangler queues create myqueue`

配置 Worker

由于 Cloudflare Queues 只能由在 Workers 上运行的脚本访问，Dapr 需要维护一个 Worker 来与队列通信。

Dapr 可以自动为您管理 Worker，或者您可以自己预先配置 Worker。在 workerd 上运行时，预先配置 Worker 是唯一支持的选项。

重要

为每个 Dapr 组件使用单独的 Worker。不要为不同的 Cloudflare Queues 绑定使用相同的 Worker 脚本，也不要为 Dapr 中不同的 Cloudflare 组件（例如，Workers KV 状态存储和 Queues 绑定）使用相同的 Worker 脚本。

如果您想让 Dapr 为您管理 Worker，您需要提供这 3 个元数据选项：

workerName：Worker 脚本的名称。这将是您的 Worker URL 的第一部分。例如，如果为您的 Cloudflare 账户配置的 “workers.dev” 域是 mydomain.workers.dev 并且您将 workerName 设置为 mydaprqueue，Dapr 部署的 Worker 将在 https://mydaprqueue.mydomain.workers.dev 上可用。
cfAccountID：您的 Cloudflare 账户的 ID。登录到 Cloudflare 控制面板后，您可以在浏览器的 URL 栏中找到它，ID 紧跟在 dash.cloudflare.com 之后。例如，如果 URL 是 https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef，则 cfAccountID 的值是 456789abcdef8b5588f3d134f74acdef。
cfAPIToken：具有创建和编辑 Workers 权限的 API 令牌。您可以在 Cloudflare 控制面板的 “My Profile” 部分的 “API Tokens” 页面中创建它：
1. 点击 “Create token”。
2. 选择 “Edit Cloudflare Workers” 模板。
3. 按照屏幕上的说明生成新的 API 令牌。

当 Dapr 配置为为您管理 Worker 时，当 Dapr 运行时启动时，它会检查 Worker 是否存在且是最新的。如果 Worker 不存在，或者它使用的是过时的版本，Dapr 会自动为您创建或升级它。

如果您不想授予 Dapr 为您部署 Worker 脚本的权限，您可以手动配置一个 Worker 供 Dapr 使用。请注意，如果您有多个 Dapr 组件通过 Worker 与 Cloudflare 服务交互，您需要为每个组件创建单独的 Worker。

要手动配置 Worker 脚本，您需要在本地计算机上安装 Node.js。

创建一个新文件夹来放置 Worker 的源代码，例如：daprworker。
如果您还没有这样做，请使用以下命令通过 Wrangler（Cloudflare Workers CLI）进行身份验证：npx wrangler login。
在新创建的文件夹中，创建一个新的 wrangler.toml 文件，内容如下，并适当填写缺失的信息：

# Worker 的名称，例如 "mydaprqueue"
name = ""

# 不要更改这些选项
main = "worker.js"
compatibility_date = "2022-12-09"
usage_model = "bundled"

[vars]
# 将此设置为 Ed25519 密钥的**公钥**部分，PEM 编码（换行符替换为 `\n`）。
# 示例：
# PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowB...=\n-----END PUBLIC KEY-----"
PUBLIC_KEY = ""
# 将此设置为您的 Worker 名称（与上面的 "name" 属性值相同），例如 "mydaprqueue"。
TOKEN_AUDIENCE = ""

# 将接下来的两个值设置为您的 Queue 名称，例如 "myqueue"。
# 注意它们将被设置为相同的值。
[[queues.producers]]
queue = ""
binding = ""

注意：有关如何生成 Ed25519 密钥对，请参阅下一节。在部署 Worker 时，请确保使用密钥的公钥部分！

将 Worker 的（预编译和压缩的）代码复制到 worker.js 文件中。您可以使用以下命令执行此操作：

# 将此设置为您正在使用的 Dapr 版本
DAPR_VERSION="release-1.18"
curl -LfO "https://raw.githubusercontent.com/dapr/components-contrib/${DAPR_VERSION}/internal/component/cloudflare/workers/code/worker.js"

使用 Wrangler 部署 Worker：

npx wrangler publish

部署 Worker 后，您需要使用这两个元数据选项来初始化组件：

workerName：Worker 脚本的名称。这是您在 wrangler.toml 文件中的 name 属性中设置的值。
workerUrl：已部署的 Worker 的 URL。npx wrangler command 命令将向您显示完整的 URL，例如 https://mydaprqueue.mydomain.workers.dev。

生成 Ed25519 密钥对

所有 Cloudflare Workers 都在公共 Internet 上监听，因此 Dapr 需要使用额外的身份验证和数据保护措施，以确保没有其他人员或应用程序可以与您的 Worker 通信（从而与您的 Cloudflare Queue 通信）。这些措施包括行业标准措施，例如：

Dapr 向 Worker 发出的所有请求都通过不记名令牌（技术上讲是 JWT）进行身份验证，该令牌使用 Ed25519 密钥签名。
Dapr 与您的 Worker 之间的所有通信都通过加密连接进行，使用 TLS (HTTPS)。
不记名令牌在每个请求上生成，仅在短时间内有效（目前为一分钟）。

要让 Dapr 颁发不记名令牌并让您的 Worker 验证它们，您需要生成一个新的 Ed25519 密钥对。以下是使用 OpenSSL 或 step CLI 生成密钥对的示例。

自 OpenSSL 1.1.0 起支持生成 Ed25519 密钥，因此如果您使用的是旧版本的 OpenSSL，以下命令将不起作用。

Mac 用户注意：在 macOS 上，Apple 附带的 “openssl” 二进制文件实际上基于 LibreSSL，截至目前它不支持 Ed25519 密钥。如果您使用的是 macOS，请使用 step CLI，或使用 brew install openssl@3 从 Homebrew 安装 OpenSSL 3.0，然后将以下命令中的 openssl 替换为 $(brew --prefix)/opt/openssl@3/bin/openssl。

您可以使用 OpenSSL 生成新的 Ed25519 密钥对：

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

在 macOS 上，使用来自 Homebrew 的 openssl@3：

$(brew --prefix)/opt/openssl@3/bin/openssl genpkey -algorithm ed25519 -out private.pem
$(brew --prefix)/opt/openssl@3/bin/openssl pkey -in private.pem -pubout -out public.pem

如果您还没有 step CLI，请按照官方说明进行安装。

接下来，您可以使用 step CLI 生成新的 Ed25519 密钥对：

step crypto keypair \
  public.pem private.pem \
  --kty OKP --curve Ed25519 \
  --insecure --no-password

无论您如何生成密钥对，按照上述说明，您将拥有两个文件：

private.pem 包含密钥的私钥部分；使用此文件的内容作为组件元数据的**key**属性。
public.pem 包含密钥的公钥部分，仅当您手动部署 Worker 时才需要（按照上一节中的说明）。

警告

请保护密钥的私钥部分并将其视为机密值！

1.20 - commercetools GraphQL 绑定规范

commercetools GraphQL 绑定组件的详细文档

组件格式

要设置 commercetools GraphQL 绑定，需创建一个类型为 bindings.commercetools 的组件。有关如何创建和应用绑定配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.commercetools
  version: v1
  metadata:
  - name: region # 必填。
    value: "region"
  - name: provider # 必填。
    value: "gcp"
  - name: projectKey # 必填。
    value: "<project-key>"
  - name: clientID # 必填。
    value: "*****************"
  - name: clientSecret # 必填。
    value: "*****************"
  - name: scopes # 必填。
    value: "<project-scopes>"

警告

上述示例将密钥以纯文本字符串形式使用。建议按照此处的说明，使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`region`	Y	输出	commercetools 项目的区域	`"europe-west1"`
`provider`	Y	输出	云提供商，可以是 gcp 或 aws	`"gcp"`, `"aws"`
`projectKey`	Y	输出	commercetools 项目的项目键
`clientID`	Y	输出	项目的 commercetools 客户端 ID
`clientSecret`	Y	输出	项目的 commercetools 客户端密钥
`scopes`	Y	输出	项目的 commercetools 作用域	`"manage_project:project-key"`

更多信息请参阅 commercetools - 创建 API 客户端和 commercetools - 区域。

绑定支持

此组件支持输出绑定，包含以下操作：

create

1.21 - Cron 绑定规范

Cron 绑定组件的详细文档

组件格式

要设置 Cron 绑定，需创建一个类型为 bindings.cron 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.cron
  version: v1
  metadata:
  - name: schedule
    value: "@every 15m" # 有效的 cron 调度
  - name: direction
    value: "input"

规范元数据字段

字段	必填	绑定支持	详情	示例
`schedule`	Y	Input	要使用的有效 cron 调度。详见此	`"@every 15m"`
`direction`	N	Input	绑定的方向	`"input"`

调度格式

Dapr Cron 绑定支持以下格式：

字符	描述	可接受的值
1	秒	0 到 59，或 *
2	分钟	0 到 59，或 *
3	小时	0 到 23，或 *（UTC）
4	日期	1 到 31，或 *
5	月份	1 到 12，或 *
6	星期	0 到 7（其中 0 和 7 代表星期日），或 *

例如：

30 * * * * * - 每 30 秒
0 */15 * * * * - 每 15 分钟
0 30 3-6,20-23 * * * - 在凌晨 3-6 点和晚上 8-11 点范围内，每小时的第 30 分钟
CRON_TZ=America/New_York 0 30 04 * * * - 纽约时间每天凌晨 4:30

您可以在此了解更多关于 cron 及其支持格式的信息

为方便使用，Dapr Cron 绑定还支持一些快捷方式：

@every 15s，其中 s 表示秒，m 表示分钟，h 表示小时
@daily 或 @hourly，从绑定初始化的时间开始按该周期运行

监听 Cron 绑定

设置 Cron 绑定后，您只需监听与组件名称匹配的端点。假设 [NAME] 为 scheduled。这将通过 HTTP POST 请求发起。以下示例展示了一个简单的 Node.js Express 应用如何在 /scheduled 端点上接收调用并向控制台写入消息。

app.post('/scheduled', async function(req, res){
    console.log("scheduled endpoint called", req.body)
    res.status(200).send()
});

运行此代码时，请注意 /scheduled 端点每 15 分钟会被 Dapr 边车调用一次。

绑定支持

此组件支持输入绑定接口。

1.22 - Apache Dubbo binding 规范

Apache Dubbo binding 组件的详细文档

组件格式

要设置 Apache Dubbo binding，创建一个类型为 bindings.dubbo 的组件。参见此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.dubbo
  version: v1
  metadata:
    - name: interfaceName
      value: "com.example.UserService"
    - name: methodName
      value: "getUser"
    # 可选
    - name: version
      value: "1.0.0"
    - name: group
      value: "mygroup"
    - name: providerHostname
      value: "localhost"
    - name: providerPort
      value: "8080"

注意

Dubbo binding 默认不需要认证或 secret 配置。但是，如果您的 Dubbo 部署需要安全通信，您可以为敏感值集成 Dapr 的 secret store。

Spec 元数据字段

字段	必需	绑定支持	详情	示例
`interfaceName`	Y	Output	要调用的 Dubbo 接口名称。	`"com.example.UserService"`
`methodName`	Y	Output	在接口上调用的方法名。	`"getUser"`
`version`	N	Output	Dubbo 服务的版本。	`"1.0.0"`
`group`	N	Output	Dubbo 服务的分组名称。	`"mygroup"`
`providerHostname`	N	Output	Dubbo 提供者的主机名。	`"localhost"`
`providerPort`	N	Output	Dubbo 提供者的端口。	`"8080"`

绑定支持

此组件支持输出 binding，具有以下操作：

create：调用 Dubbo 服务方法。

示例：调用 Dubbo 服务

要使用 binding 调用 Dubbo 服务：

{
  "operation": "create",
  "metadata": {
    "interfaceName": "com.example.UserService",
    "methodName": "getUser",
    "version": "1.0.0",
    "providerHostname": "localhost",
    "providerPort": "8080"
  },
  "data": {
    "userId": "12345"
  }
}

data 字段包含发送到 Dubbo 服务方法的请求负载。

1.23 - GCP Pub/Sub 绑定规范

GCP Pub/Sub 绑定组件的详细文档

组件格式

要设置 GCP Pub/Sub 绑定，请创建类型为 bindings.gcp.pubsub 的组件。有关如何创建和应用绑定配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.gcp.pubsub
  version: v1
  metadata:
  - name: topic
    value: "topic1"
  - name: subscription
    value: "subscription1"
  - name: type
    value: "service_account"
  - name: project_id
    value: "project_111"
  - name: private_key_id
    value: "*************"
  - name: client_email
    value: "name@domain.com"
  - name: client_id
    value: "1111111111111111"
  - name: auth_uri
    value: "https://accounts.google.com/o/oauth2/auth"
  - name: token_uri
    value: "https://oauth2.googleapis.com/token"
  - name: auth_provider_x509_cert_url
    value: "https://www.googleapis.com/oauth2/v1/certs"
  - name: client_x509_cert_url
    value: "https://www.googleapis.com/robot/v1/metadata/x509/<project-name>.iam.gserviceaccount.com"
  - name: private_key
    value: "PRIVATE KEY"
  - name: direction
    value: "input, output"

Warning

上面的示例将密钥作为纯字符串使用。建议使用 secret store 来管理密钥，具体说明请参见此处。

规范元数据字段

字段	必填	绑定支持	详情	示例
`topic`	Y	Output	GCP Pub/Sub topic 名称	`"topic1"`
`subscription`	N	GCP Pub/Sub subscription 名称	`"name1"`
`type`	Y	Output	GCP 凭据类型	`service_account`
`project_id`	Y	Output	GCP 项目 id	`projectId`
`private_key_id`	N	Output	GCP 私钥 id	`"privateKeyId"`
`private_key`	Y	Output	GCP 凭据私钥。替换为 x509 证书	`12345-12345`
`client_email`	Y	Output	GCP 客户端邮箱	`"client@email.com"`
`client_id`	N	Output	GCP 客户端 id	`0123456789-0123456789`
`auth_uri`	N	Output	Google 账户 OAuth 端点	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	Output	Google 账户 token uri	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	Output	GCP 凭据证书 url	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	Output	GCP 凭据项目 x509 证书 url	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`
`direction`	N	Input/Output	绑定的方向。	`"input"`、`"output"`、`"input, output"`

绑定支持

此组件支持 input 和 output 绑定接口。

此组件支持 output 绑定，并具有以下操作：

create

1.24 - GCP Storage Bucket binding 规范

GCP Storage Bucket binding 组件的详细文档

组件格式

要设置 GCP Storage Bucket binding，请创建类型为 bindings.gcp.bucket 的组件。有关如何创建和应用 binding 配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.gcp.bucket
  version: v1
  metadata:
  - name: bucket
    value: "mybucket"
  - name: type
    value: "service_account"
  - name: project_id
    value: "project_111"
  - name: private_key_id
    value: "*************"
  - name: client_email
    value: "name@domain.com"
  - name: client_id
    value: "1111111111111111"
  - name: auth_uri
    value: "https://accounts.google.com/o/oauth2/auth"
  - name: token_uri
    value: "https://oauth2.googleapis.com/token"
  - name: auth_provider_x509_cert_url
    value: "https://www.googleapis.com/oauth2/v1/certs"
  - name: client_x509_cert_url
    value: "https://www.googleapis.com/robot/v1/metadata/x509/<project-name>.iam.gserviceaccount.com"
  - name: private_key
    value: "PRIVATE KEY"
  - name: decodeBase64
    value: "<bool>"
  - name: encodeBase64
    value: "<bool>"
  - name: contentType
    value: "<string>"

警告

上述示例将密钥作为纯文本字符串使用。建议使用 secret store 来存储密钥，如此处所述。

规范元数据字段

字段	必需	Binding 支持	详细说明	示例
`bucket`	Y	Output	bucket 名称	`"mybucket"`
`project_id`	Y	Output	GCP 项目 ID	`projectId`
`type`	N	Output	GCP 凭据类型	`"service_account"`
`private_key_id`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 文档中的 `private_key_id` 字段	`"privateKeyId"`
`private_key`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `private_key` 字段。替换为 x509 证书	`12345-12345`
`client_email`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `client_email` 字段	`"client@email.com"`
`client_id`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `client_id` 字段	`0123456789-0123456789`
`auth_uri`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `auth_uri` 字段	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `token_uri` 字段	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `auth_provider_x509_cert_url` 字段	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	Output	如果使用显式凭据，此字段应包含服务账号 json 中的 `client_x509_cert_url` 字段	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`
`decodeBase64`	N	Output	在保存到 bucket 存储之前解码 base64 文件内容的配置。（用于保存二进制内容的文件）。`true` 是唯一允许的肯定值。其他肯定变体如 `"True", "1"` 不可接受。默认为 `false`	`true`, `false`
`encodeBase64`	N	Output	在返回内容之前编码 base64 文件内容的配置。（用于打开二进制内容的文件）。`true` 是唯一允许的肯定值。其他肯定变体如 `"True", "1"` 不可接受。默认为 `false`	`true`, `false`
`contentType`	N	Output	为 bucket 中创建的对象设置的 MIME 类型。如果未指定，GCP 将尝试自动检测内容类型。	`"text/csv"`, `"application/json"`, `"image/png"`

GCP 凭据

由于 GCP Storage Bucket 组件使用 GCP Go 客户端库，默认情况下它使用 Application Default Credentials 进行身份验证。这在 Authenticate to GCP Cloud services using client libraries 指南中有进一步说明。此外，请参阅如何设置 Application Default Credentials。

GCP 凭据

Binding 支持

此组件支持以下操作的输出 binding：

create : 创建文件
get : 获取文件
bulkGet : 批量获取对象
delete : 删除文件
list: 列出文件
copy: 复制文件
move: 移动文件
rename: 重命名文件

创建文件

要执行 create 操作，使用 POST 方法调用 GCP Storage Bucket binding 并提供以下 JSON 请求体：

注意：默认情况下会生成一个随机 UUID。有关设置名称的元数据支持，请参见下文

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

元数据参数包括：

key - （可选）对象的名称
decodeBase64 - （可选）在保存到存储之前解码 base64 文件内容的配置
contentType - （可选）正在创建的对象的 MIME 类型

示例

将文本保存到随机生成的 UUID 文件

在 Windows 上，使用 cmd 提示符（PowerShell 具有不同的转义机制）

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文本保存到指定文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"key\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "key": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

保存具有正确内容类型的 CSV 文件

curl -d "{ \"operation\": \"create\", \"data\": \"$(cat data.csv | base64)\", \"metadata\": { \"key\": \"data.csv\", \"contentType\": \"text/csv\", \"decodeBase64\": \"true\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "'"$(base64 < data.csv)"'", "metadata": { "key": "data.csv", "contentType": "text/csv", "decodeBase64": "true" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

上传文件

要上传文件，将文件内容作为数据负载传递；对于二进制内容，您可能需要对其进行 Base64 编码。

然后您可以像往常一样上传它：

curl -d "{ \"operation\": \"create\", \"data\": \"(YOUR_FILE_CONTENTS)\", \"metadata\": { \"key\": \"my-test-file.jpg\", \"contentType\": \"image/jpeg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "$(cat my-test-file.jpg | base64)", "metadata": { "key": "my-test-file.jpg", "contentType": "image/jpeg", "decodeBase64": "true" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体将包含以下 JSON：

{
    "objectURL":"https://storage.googleapis.com/<your bucket>/<key>",
}

获取对象

要执行 get 文件操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数包括：

key - 对象的名称
encodeBase64 - （可选）在返回内容之前编码 base64 文件内容的配置。

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含存储在对象中的值。

批量获取对象

要执行一次性检索所有 bucket 文件的批量获取操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "bulkGet",
}

元数据参数包括：

encodeBase64 - （可选）在返回所有文件的内容之前编码 base64 文件内容的配置

示例

curl -d '{ \"operation\": \"bulkget\"}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "bulkget"}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含一个对象数组，其中每个对象代表 bucket 中的一个文件，具有以下结构：

[
  {
    "name": "file1.txt",
    "data": "content of file1",
    "attrs": {
      "bucket": "mybucket",
      "name": "file1.txt",
      "size": 1234,
      ...
    }
  },
  {
    "name": "file2.txt",
    "data": "content of file2",
    "attrs": {
      "bucket": "mybucket",
      "name": "file2.txt",
      "size": 5678,
      ...
    }
  }
]

数组中的每个对象包含：

name：文件名
data：文件内容
attrs：来自 GCP Storage 的对象属性，包括创建时间、大小、内容类型等元数据

删除对象

要执行 delete 对象操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数包括：

key - 对象的名称

示例

删除对象

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

如果成功，将返回 HTTP 204 (No Content) 和空响应体。

列出对象

要执行 list 对象操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "list",
  "data": {
    "maxResults": 10,
    "prefix": "file",
    "delimiter": "i0FvxAn2EOEL6"
  }
}

数据参数包括：

maxResults - （可选）设置响应中返回的键的最大数量。默认情况下，操作最多返回 1,000 个键名。响应可能包含较少的键，但绝不会包含更多。
prefix - （可选）可用于过滤以 prefix 开头的对象。
delimiter - （可选）可用于将结果限制为给定"目录"中的对象。如果没有 delimiter，则返回 prefix 下的整个树

响应

响应体包含找到的对象列表。

对象列表将以以下形式的 JSON 数组返回：

[
	{
		"Bucket": "<your bucket>",
		"Name": "02WGzEdsUWNlQ",
		"ContentType": "image/png",
		"ContentLanguage": "",
		"CacheControl": "",
		"EventBasedHold": false,
		"TemporaryHold": false,
		"RetentionExpirationTime": "0001-01-01T00:00:00Z",
		"ACL": null,
		"PredefinedACL": "",
		"Owner": "",
		"Size": 5187,
		"ContentEncoding": "",
		"ContentDisposition": "",
		"MD5": "aQdLBCYV0BxA51jUaxc3pQ==",
		"CRC32C": 1058633505,
		"MediaLink": "https://storage.googleapis.com/download/storage/v1/b/<your bucket>/o/02WGzEdsUWNlQ?generation=1631553155678071&alt=media",
		"Metadata": null,
		"Generation": 1631553155678071,
		"Metageneration": 1,
		"StorageClass": "STANDARD",
		"Created": "2021-09-13T17:12:35.679Z",
		"Deleted": "0001-01-01T00:00:00Z",
		"Updated": "2021-09-13T17:12:35.679Z",
		"CustomerKeySHA256": "",
		"KMSKeyName": "",
		"Prefix": "",
		"Etag": "CPf+mpK5/PICEAE="
	}
]

复制对象

要执行 copy 对象操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "copy",
  "metadata": {
    "key": "source-file.txt",
    "destinationBucket": "destination-bucket-name"
  }
}

元数据参数包括：

key - 源对象的名称（必需）
destinationBucket - 目标 bucket 的名称（必需）

移动对象

要执行 move 对象操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "move",
  "metadata": {
    "key": "source-file.txt",
    "destinationBucket": "destination-bucket-name"
  }
}

元数据参数包括：

key - 源对象的名称（必需）
destinationBucket - 目标 bucket 的名称（必需）

重命名对象

要执行 rename 对象操作，使用 POST 方法调用 GCP bucket binding 并提供以下 JSON 请求体：

{
  "operation": "rename",
  "metadata": {
    "key": "old-name.txt",
    "newName": "new-name.txt"
  }
}

元数据参数包括：

key - 对象的当前名称（必需）
newName - 对象的新名称（必需）

1.25 - GraphQL 绑定规范

GraphQL 绑定组件的详细文档

组件格式

要设置 GraphQL 绑定，请创建一个类型为 bindings.graphql 的组件。有关如何创建和应用绑定配置的说明，请参阅此指南。为了将普通配置设置（例如 endpoint）与 headers 分开，在 header 名称上使用 “header:” 作为前缀。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: example.bindings.graphql
spec:
  type: bindings.graphql
  version: v1
  metadata:
    - name: endpoint
      value: "http://localhost:8080/v1/graphql"
    - name: header:x-hasura-access-key
      value: "adminkey"
    - name: header:Cache-Control
      value: "no-cache"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

Field	Required	Binding support	Details	Example
`endpoint`	Y	Output	GraphQL 端点字符串更多详细信息请参阅此处	`"http://localhost:4000/graphql/graphql"`
`header:[HEADERKEY]`	N	Output	GraphQL header。在 `name` 中指定 header 键，在 `value` 中指定 header 值。	`"no-cache"`（见上文）
`variable:[VARIABLEKEY]`	N	Output	GraphQL 查询变量。在 `name` 中指定变量名，在 `value` 中指定变量值。	`"123"`（见下文）

GraphQL 绑定内部使用 GraphQL client。

绑定支持

此组件支持输出绑定，具有以下操作：

query
mutation

query

query 操作用于 query 语句，它返回元数据以及以行值数组形式的数据。

请求

in := &dapr.InvokeBindingRequest{
Name:      "example.bindings.graphql",
Operation: "query",
Metadata: map[string]string{ "query": `query { users { name } }`},
}

要使用需要查询变量的 query，请向 metadata 映射添加一个键值对，其中对应于查询变量的每个键都是以 variable: 为前缀的变量名称

in := &dapr.InvokeBindingRequest{
Name: "example.bindings.graphql",
Operation: "query",
Metadata: map[string]string{ 
  "query": `query HeroNameAndFriends($episode: string!) { hero(episode: $episode) { name } }`,
  "variable:episode": "JEDI",
}

1.26 - HTTP binding 规范

HTTP binding 组件的详细文档

备选方案

服务调用 API 允许调用非 Dapr HTTP 端点，是推荐的方式。阅读 “如何操作：使用 HTTP 调用非 Dapr 端点” 了解更多信息。

配置 Dapr 组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
    - name: url
      value: "http://something.com"
    #- name: maxResponseBodySize
    #  value: "100Mi" # 可选，从响应中读取的最大数据量
    #- name: MTLSRootCA
    #  value: "/Users/somepath/root.pem" # 可选，根 CA 路径或 PEM 编码字符串
    #- name: MTLSClientCert
    #  value: "/Users/somepath/client.pem" # 可选，客户端证书路径或 PEM 编码字符串
    #- name: MTLSClientKey
    #  value: "/Users/somepath/client.key" # 可选，客户端密钥路径或 PEM 编码字符串
    #- name: MTLSRenegotiation
    #  value: "RenegotiateOnceAsClient" # 可选，可选值之一：RenegotiateNever、RenegotiateOnceAsClient、RenegotiateFreelyAsClient
    #- name: securityToken # 可选，<作为头部包含在 HTTP 请求中的令牌>
    #  secretKeyRef:
    #    name: mysecret
    #    key: "mytoken"
    #- name: securityTokenHeader
    #  value: "Authorization: Bearer" # 可选，<安全令牌的头部名称>
    #- name: errorIfNot2XX
    #  value: "false" # 可选

规范元数据字段

字段	必填	Binding 支持	详情	示例
`url`	Y	输出	要调用的 HTTP 端点的基础 URL	`http://host:port/path`、`http://myservice:8000/customers`
`maxResponseBodySize`	N	输出	要读取的响应的最大长度。整数被解释为字节；为方便起见，可以添加 `Ki, Mi, Gi`（SI）或 `k	M
`MTLSRootCA`	N	输出	根 CA 证书路径或 PEM 编码字符串
`MTLSClientCert`	N	输出	客户端证书路径或 PEM 编码字符串
`MTLSClientKey`	N	输出	客户端私钥路径或 PEM 编码字符串
`MTLSRenegotiation`	N	输出	要使用的 mTLS 重新协商类型	`RenegotiateOnceAsClient`
`securityToken`	N	输出	要作为头部添加到 HTTP 请求的令牌值。与 `securityTokenHeader` 一起使用
`securityTokenHeader`	N	输出	HTTP 请求上 `securityToken` 的头部名称
`errorIfNot2XX`	N	输出	当响应不在 2xx 范围内时是否应抛出 binding 错误。默认为 `true`

MTLSRootCA、MTLSClientCert 和 MTLSClientKey 的值可以通过三种方式提供：

secret store 引用：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: http://something.com
  - name: MTLSRootCA
    secretKeyRef:
      name: mysecret
      key: myrootca
auth:
  secretStore: <NAME_OF_SECRET_STORE_COMPONENT>

文件路径：可以将文件的绝对路径作为字段的值提供。
PEM 编码字符串：也可以将 PEM 编码的字符串作为字段的值提供。

注意

元数据字段 MTLSRootCA、MTLSClientCert 和 MTLSClientKey 用于配置 mTLS 认证。要使用 mTLS 认证，必须提供所有三个字段。有关更多详细信息，请参阅 mTLS。您也可以仅提供 MTLSRootCA，以启用由自定义 CA 签名的证书的 HTTPS 连接。有关更多详细信息，请参阅 HTTPS 部分。

Binding 支持

此组件支持 输出 binding，支持以下 HTTP 方法/动词：

create ：出于向后兼容性考虑，被视为 post
get ：读取数据/记录
head ：与 get 相同，但服务器不返回响应体
post ：通常用于创建记录或发送命令
put ：更新数据/记录
patch ：有时用于更新记录的字段子集
delete ：删除数据/记录
options ：请求有关可用通信选项的信息（不常用）
trace ：用于调用远程的应用层请求消息回送（不常用）

请求

操作元数据字段

上述所有操作都支持以下元数据字段

字段	必填	详情	示例
`path`	N	要附加到基础 URL 的路径。用于访问特定的 URI。	`"/1234"`、`"/search?lastName=Jones"`
首字母大写的字段	N	任何首字母大写的字段都将作为请求头部发送	`"Content-Type"`、`"Accept"`

检索数据

要从 HTTP 端点检索数据，请使用 GET 方法调用 HTTP binding 并使用以下 JSON 正文：

{
  "operation": "get"
}

可以选择指定路径以与资源 URI 交互：

{
  "operation": "get",
  "metadata": {
    "path": "/things/1234"
  }
}

响应

响应正文包含 HTTP 端点返回的数据。data 字段包含 HTTP 响应正文，作为字节切片（通过 curl 进行 Base64 编码）。metadata 字段包含：

字段	必填	详情	示例
`statusCode`	Y	HTTP 状态码	`200`、`404`、`503`
`status`	Y	状态描述	`"200 OK"`、`"201 Created"`
首字母大写的字段	N	任何首字母大写的字段都将作为请求头部发送	`"Content-Type"`

示例

请求基础 URL

curl -d "{ \"operation\": \"get\" }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

请求特定路径

curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

发送和更新数据

要向 HTTP 端点发送数据，请使用 POST、PUT 或 PATCH 方法调用 HTTP binding 并使用以下 JSON 正文：

注意

任何以大写字母开头的元数据字段都将作为请求头部传递。例如，默认的内容类型为 application/json; charset=utf-8。可以通过设置 Content-Type 元数据字段来覆盖。

{
  "operation": "post",
  "data": "content (default is JSON)",
  "metadata": {
    "path": "/things",
    "Content-Type": "application/json; charset=utf-8"
  }
}

示例

发布新记录

curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

使用 HTTPS

通过配置 Dapr 边车以信任服务器的 SSL 证书，HTTP binding 也可以与 HTTPS 端点一起使用。

将 binding URL 更新为使用 https 而不是 http。
如果需要添加自定义 TLS 证书，请参阅如何操作：在 Dapr 边车中安装证书，在边车中安装 TLS 证书。

示例

更新 binding 组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: https://my-secured-website.com # 使用 HTTPS

在边车中安装 TLS 证书

当边车未在容器内运行时，TLS 证书可以直接安装在主机操作系统上。

以下是边车作为容器运行时的示例。SSL 证书位于主机上的 /tmp/ssl/cert.pem。

version: '3'
services:
  my-app:
    # ...
  dapr-sidecar:
    image: "daprio/daprd:1.8.0"
    command: [
      "./daprd",
     "-app-id", "myapp",
     "-app-port", "3000",
     ]
    volumes:
        - "./components/:/components"
        - "/tmp/ssl/:/certificates" # 将证书文件夹挂载到边车容器的 /certificates
    environment:
      - "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    depends_on:
      - my-app

边车可以从各种源读取 TLS 证书。有关更多信息，请参阅如何操作：将 Pod 卷挂载到 Dapr 边车。在此示例中，我们将 TLS 证书存储为 Kubernetes secret。

kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem

下面的 YAML 是 Kubernetes 部署的示例，该部署将上述 secret 挂载到边车，并设置 SSL_CERT_DIR 以安装证书。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
  labels:
    app: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "myapp"
        dapr.io/app-port: "8000"
        dapr.io/volume-mounts: "cert-vol:/certificates" # 将证书文件夹挂载到边车容器的 /certificates
        dapr.io/env: "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    spec:
      volumes:
        - name: cert-vol
          secret:
            secretName: myapp-cert
...

安全地调用 binding

curl -d "{ \"operation\": \"get\" }" \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

注意

还可以使用 MTLSRootCA 元数据选项配置 HTTPS binding 支持。这将把指定的证书添加到 binding 的受信任证书列表中。两种方法没有特定的偏好。虽然 MTLSRootCA 选项易于使用且不需要对边车进行任何更改，但它仅接受一个证书。如果您需要信任多个证书，则需要按照上述步骤在边车中安装它们。

使用 mTLS 或在 HTTPS 的同时启用客户端 TLS 认证

您可以通过在 binding 组件中提供 MTLSRootCA、MTLSClientCert 和 MTLSClientKey 元数据字段，将 HTTP binding 配置为使用 mTLS 或客户端 TLS 认证以及 HTTPS。

这些字段可以作为文件路径或 pem 编码字符串传递：

如果提供文件路径，则读取文件并使用其内容。
如果提供 PEM 编码的字符串，则按原样使用该字符串。

配置这些字段后，Dapr 边车使用提供的证书在 TLS 握手过程中向服务器验证自身。

如果远程服务器强制执行 TLS 重新协商，您还需要设置元数据字段 MTLSRenegotiation。此字段接受以下选项之一：

RenegotiateNever
RenegotiateOnceAsClient
RenegotiateFreelyAsClient

有关更多详细信息，请参阅 Go RenegotiationSupport 文档。

当配置 HTTP binding 进行通信的服务器需要 mTLS 或客户端 TLS 认证时，您可以使用此功能。

1.27 - Huawei OBS binding 规范

Huawei OBS binding 组件的详细文档

组件格式

要设置 Huawei Object Storage Service (OBS)（输出）binding，请创建类型为 bindings.huawei.obs 的组件。有关如何创建和应用 binding 配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.huawei.obs
  version: v1
  - name: bucket
    value: "<your-bucket-name>"
  - name: endpoint
    value: "<obs-bucket-endpoint>"
  - name: accessKey
    value: "<your-access-key>"
  - name: secretKey
    value: "<your-secret-key>"
  # optional fields
  - name: region
    value: "<your-bucket-region>"

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体方法请参阅此处。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`bucket`	Y	Output	要写入的 Huawei OBS bucket 名称	`"My-OBS-Bucket"`
`endpoint`	Y	Output	特定的 Huawei OBS 端点	`"obs.cn-north-4.myhuaweicloud.com"`
`accessKey`	Y	Output	访问此资源的 Huawei Access Key (AK)	`"************"`
`secretKey`	Y	Output	访问此资源的 Huawei Secret Key (SK)	`"************"`
`region`	N	Output	bucket 的特定华为区域	`"cn-north-4"`

Binding 支持

此组件支持输出 binding，包含以下操作：

create：创建文件
upload：上传文件
get：获取文件
delete：删除文件
list：列出文件

创建文件

要执行创建操作，请使用 POST 方法调用 Huawei OBS binding，并传入以下 JSON 请求体：

注意：默认情况下会生成一个随机的 UUID。有关设置目标文件名的元数据支持，请参见下文

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

示例

将文本保存到随机生成的 UUID 文件

在 Windows 上，请使用 cmd 提示符（PowerShell 具有不同的转义机制）

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

将文本保存到特定文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"key\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "key": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应 JSON 请求体包含 statusCode 和 versionId 字段。仅当启用了 bucket 版本控制时，versionId 才会返回值，否则为空字符串。

上传文件

要上传二进制文件（例如 .jpg、.zip），请使用 POST 方法调用 Huawei OBS binding，并传入以下 JSON 请求体：

注意：如果您未指定 key，默认情况下会生成一个随机 UUID。有关设置目标文件名的元数据支持，请参见以下示例。此 API 可用于上传常规文件，例如纯文本文件。

{
  "operation": "upload",
  "metadata": {
     "key": "DESTINATION_FILE_NAME"
   },
  "data": {
     "sourceFile": "PATH_TO_YOUR_SOURCE_FILE"
   }
}

示例

curl -d "{ \"operation\": \"upload\", \"data\": { \"sourceFile\": \".\my-test-file.jpg\" }, \"metadata\": { \"key\": \"my-test-file.jpg\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "upload", "data": { "sourceFile": "./my-test-file.jpg" }, "metadata": { "key": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应 JSON 请求体包含 statusCode 和 versionId 字段。仅当启用了 bucket 版本控制时，versionId 才会返回值，否则为空字符串。

获取对象

要执行获取文件操作，请使用 POST 方法调用 Huawei OBS binding，并传入以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数包括：

key - 对象的名称

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应请求体包含存储在对象中的值。

删除对象

要执行删除对象操作，请使用 POST 方法调用 Huawei OBS binding，并传入以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

元数据参数包括：

key - 对象的名称

示例

删除对象

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

成功时返回 HTTP 204（No Content）和空请求体。

列出对象

要执行列出对象操作，请使用 POST 方法调用 Huawei OBS binding，并传入以下 JSON 请求体：

{
  "operation": "list",
  "data": {
    "maxResults": 5,
    "prefix": "dapr-",
    "marker": "obstest",
    "delimiter": "jpg"
  }
}

数据参数包括：

maxResults -（可选）设置响应中返回的最大键数。默认情况下，此操作最多返回 1,000 个键名。响应可能包含较少的键，但绝不会包含更多。
prefix -（可选）将响应限制为以指定前缀开头的键。
marker -（可选）marker 是您希望 Huawei OBS 开始列出的位置。Huawei OBS 从此指定的键之后开始列出。Marker 可以是 bucket 中的任何键。然后在后续调用中可以使用 marker 值来请求下一组列表项。
delimiter -（可选）分隔符是用于对键进行分组的字符。它返回的对象/文件的键不同于由分隔符模式指定的键。

示例

curl -d '{ \"operation\": \"list\", \"data\": { \"maxResults\": 5, \"prefix\": \"dapr-\", \"marker\": \"obstest\", \"delimiter\": \"jpg\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "list", "data": { "maxResults": 5, "prefix": "dapr-", "marker": "obstest", "delimiter": "jpg" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应请求体包含找到的对象列表。

1.28 - InfluxDB 绑定规范

InfluxDB 绑定组件的详细文档

组件格式

要设置 InfluxDB 绑定，请创建一个类型为 bindings.influx 的组件。有关如何创建和应用绑定配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.influx
  version: v1
  metadata:
  - name: url # 必填
    value: "<INFLUX-DB-URL>"
  - name: token # 必填
    value: "<TOKEN>"
  - name: org # 必填
    value: "<ORG>"
  - name: bucket # 必填
    value: "<BUCKET>"

警告

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`url`	Y	Output	InfluxDB 实例的 URL	`"http://localhost:8086"`
`token`	Y	Output	InfluxDB 的授权令牌	`"mytoken"`
`org`	Y	Output	InfluxDB 组织	`"myorg"`
`bucket`	Y	Output	要写入的 Bucket 名称	`"mybucket"`

绑定支持

此组件支持输出绑定，包含以下操作：

create
query

查询

要查询 InfluxDB，请使用 query 操作，并在调用元数据中提供一个 raw 键，其值为查询语句：

curl -X POST http://localhost:3500/v1.0/bindings/myInfluxBinding \
  -H "Content-Type: application/json" \
  -d "{
        \"metadata\": {
          \"raw\": "SELECT * FROM 'sith_lords'"
        },
        \"operation\": \"query\"
      }"

1.29 - Kafka 绑定规范

Kafka 绑定组件的详细文档

组件格式

要设置 Kafka 绑定，请创建一个类型为 bindings.kafka 的组件。有关如何创建和应用绑定配置，请参阅本指南。有关使用 secretKeyRef 的详细信息，请参阅如何在组件中引用密钥指南。

所有组件元数据字段值都可以携带模板化元数据值，这些值在 Dapr 边车启动时解析。例如，您可以选择使用 {namespace} 作为 consumerGroup，以便在不同的命名空间中使用相同的主题和相同的 appId，如本文中所述。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-binding
spec:
  type: bindings.kafka
  version: v1
  metadata:
  - name: topics # 可选。用于输入绑定。
    value: "topic1,topic2"
  - name: brokers # 必需。
    value: "localhost:9092,localhost:9093"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: publishTopic # 可选。用于输出绑定。
    value: "topic3"
  - name: authRequired # 必需。
    value: "true"
  - name: saslUsername # 当 authRequired 为 `true` 时必需。
    value: "user"
  - name: saslPassword # 当 authRequired 为 `true` 时必需。
    secretKeyRef:
      name: kafka-secrets
      key: "saslPasswordSecret"
  - name: saslMechanism
    value: "SHA-512"
  - name: initialOffset # 可选。用于输入绑定。
    value: "newest"
  - name: maxMessageBytes # 可选。
    value: "1024"
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: "2.0.0"
  - name: direction
    value: "input, output"
  - name: schemaRegistryURL # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry URL。
    value: http://localhost:8081
  - name: schemaRegistryAPIKey # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry API Key。
    value: XYAXXAZ
  - name: schemaRegistryAPISecret # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API Secret。
    value: "ABCDEFGMEADFF"
  - name: schemaCachingEnabled # 可选。使用 Schema Registry Avro 序列化/反序列化时。启用 schema 缓存。
    value: true
  - name: schemaLatestVersionCacheTTL # 可选。使用 Schema Registry Avro 序列化/反序列化时。使用可用最新 schema 发布消息时 schema 缓存的 TTL。
    value: 5m
  - name: escapeHeaders # 可选。
    value: false

规范元数据字段

字段	必需	绑定支持	详细说明	示例
`topics`	N	输入	以逗号分隔的主题字符串。	`"mytopic1,topic2"`
`brokers`	Y	输入/输出	以逗号分隔的 Kafka broker 字符串。	`"localhost:9092,dapr-kafka.myapp.svc.cluster.local:9093"`
`clientID`	N	输入/输出	用户提供的字符串，随每个请求发送到 Kafka broker，用于日志记录、调试和审计目的。	`"my-dapr-app"`
`consumerGroup`	N	输入	用于监听的 Kafka 消费者组。发布到主题的每条记录都会传递给订阅该主题的每个消费者组中的一个消费者。	`"group1"`
`consumeRetryEnabled`	N	输入/输出	通过设置为 `"true"` 来启用消费重试。在 Kafka 绑定组件中默认为 `false`。	`"true"`, `"false"`
`publishTopic`	Y	输出	要发布到的主题。	`"mytopic"`
`authRequired`	N	已弃用	使用 Kafka broker 启用 SASL 身份验证。	`"true"`, `"false"`
`authType`	Y	输入/输出	配置或禁用身份验证。支持的值：`none`、`password`、`mtls`、`oidc` 或 `oidc_private_key_jwt`	`"password"`, `"none"`
`saslUsername`	N	输入/输出	用于身份验证的 SASL 用户名。仅当 `authRequired` 设置为 `"true"` 时才需要。	`"adminuser"`
`saslPassword`	N	输入/输出	用于身份验证的 SASL 密码。可以是 `secretKeyRef` 以使用密钥引用。仅当 `authRequired` 设置为 `"true"` 时才需要。	`""`, `"KeFg23!"`
`saslMechanism`	N	输入/输出	您想使用的 SASL 身份验证机制。仅当 `authtype` 设置为 `"password"` 时才需要。如果未提供，默认为 `PLAINTEXT`，这可能会导致某些服务（如 Amazon Managed Service for Kafka）中断。	`"SHA-512", "SHA-256", "PLAINTEXT"`
`initialOffset`	N	输入	如果之前未提交偏移量，则使用的初始偏移量。应为 “newest” 或 “oldest”。默认为 “newest”。	`"oldest"`
`maxMessageBytes`	N	输入/输出	单个 Kafka 消息允许的最大字节数。默认为 1024。	`"2048"`
`oidcTokenEndpoint`	N	输入/输出	OAuth2 身份提供者访问令牌端点的完整 URL。当 `authType` 设置为 `oidc` 或 `oidc_private_key_jwt` 时必需	“https://identity.example.com/v1/token"
`oidcClientID`	N	输入/输出	在身份提供者中预配的 OAuth2 客户端 ID。当 `authType` 设置为 `oidc` 或 `oidc_private_key_jwt` 时必需	`"dapr-kafka"`
`oidcClientSecret`	N	输入/输出	在身份提供者中预配的 OAuth2 客户端密钥：当 `authType` 设置为 `oidc` 时必需	`"KeFg23!"`
`oidcScopes`	N	输入/输出	使用访问令牌请求的以逗号分隔的 OAuth2/OIDC 范围列表。当 `authType` 设置为 `oidc` 或 `oidc_private_key_jwt` 时建议使用。默认为 `"openid"`	`"openid,kafka-prod"`
`oidcClientAssertionCert`	N	输入/输出	用于身份验证的 OAuth2 客户端断言证书。当 `authType` 设置为 `oidc_private_key_jwt` 时必需。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"`
`oidcClientAssertionKey`	N	输入/输出	用于身份验证的 OAuth2 客户端断言密钥。当 `authType` 设置为 `oidc_private_key_jwt` 时必需。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"`
`oidcResource`	N	输入/输出	使用访问令牌请求的 OAuth2 资源。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"api://kafka"`
`oidcAudience`	N	输入/输出	使用访问令牌请求的 OAuth2 受众。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"http://<idp-host>/realms/local"`
`oidcKid`	N	输入/输出	使用访问令牌请求的 OAuth2 密钥 ID (kid)。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"1234567890"`
`version`	N	输入/输出	Kafka 集群版本。默认为 2.0.0。请注意，对于 EventHubs with Kafka，此值必须强制设置为 `1.0.0`。	`"1.0.0"`
`direction`	N	输入/输出	绑定的方向。	`"input"`, `"output"`, `"input, output"`
`oidcExtensions`	N	输入/输出	包含 JSON 编码字典的字符串，表示使用访问令牌请求的 OAuth2/OIDC 扩展	`{"cluster":"kafka","poolid":"kafkapool"}`
`schemaRegistryURL`	N	使用 Schema Registry Avro 序列化/反序列化时必需。Schema Registry URL。	`http://localhost:8081`
`schemaRegistryAPIKey`	N	使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API Key。	`XYAXXAZ`
`schemaRegistryAPISecret`	N	使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API Secret。	`ABCDEFGMEADFF`
`schemaCachingEnabled`	N	使用 Schema Registry Avro 序列化/反序列化时。启用 schema 缓存。默认为 `true`	`true`
`schemaLatestVersionCacheTTL`	N	使用 Schema Registry Avro 序列化/反序列化时。使用可用最新 schema 发布消息时 schema 缓存的 TTL。默认为 5 分钟	`5m`
`clientConnectionTopicMetadataRefreshInterval`	N	输入/输出	客户端连接的主题元数据与 broker 刷新的时间间隔，以 Go duration 格式表示。默认为 `9m`。	`"4m"`
`clientConnectionKeepAliveInterval`	N	输入/输出	客户端连接在与 broker 保持连接的最大时间，以 Go duration 格式表示，之后将关闭连接。零值（默认）表示无限期保持连接。	`"4m"`
`consumerFetchDefault`	N	输入/输出	在每个请求中从 broker 获取的默认消息字节数。默认为 `"1048576"` 字节。	`"2097152"`
`heartbeatInterval`	N	输入	向消费者协调器发送心跳的间隔。该值最多应设置为 `sessionTimeout` 值的 1/3。默认为 `"3s"`。	`"5s"`
`sessionTimeout`	N	输入	使用 Kafka 的组管理功能时用于检测客户端故障的超时时间。如果 broker 在此会话超时到期前未能收到来自消费者的任何心跳，则消费者将被移除并启动重新平衡。默认为 `"10s"`。	`"20s"`
`escapeHeaders`	N	输入	启用消费者接收的消息标头值的 URL 转义。允许接收通常在 HTTP 标题中不允许的特殊字符内容。默认为 `false`。	`true`

注意

使用 Azure EventHubs with Kafka 时，元数据 version 必须设置为 1.0.0。

绑定支持

此组件同时支持输入和输出绑定接口。

此组件支持以下操作的输出绑定：

create

身份验证

Kafka 支持多种身份验证方案，Dapr 支持其中几种：SASL 密码、mTLS、OIDC/OAuth2。了解有关 Kafka 绑定和 Kafka 发布订阅组件的 Kafka 身份验证方法的更多信息。

指定分区键

调用 Kafka 绑定时，可以通过在请求正文中使用 metadata 部分来提供可选的分区键。

字段名称为 partitionKey。

示例：

curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "partitionKey": "key1"
        },
        "operation": "create"
      }'

响应

如果成功，将返回 HTTP 204（无内容）和空正文。

1.30 - Kitex

Kitex binding 组件的详细文档

概述

Kitex 的 binding 主要利用 Kitex 中的 generic-call 功能。更多详情请参考 Kitex generic-call 的官方文档。目前，Kitex 仅支持 Thrift generic calls。集成到 components-contrib 的实现采用 binary generic calls。

组件格式

要设置 Kitex binding，请创建一个类型为 bindings.kitex 的组件。请参阅如何：使用输出 binding 与外部资源交互指南，了解如何创建和应用 binding 配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: bindings.kitex
spec:
  type: bindings.kitex
  version: v1
  metadata: 
  - name: hostPorts
    value: "127.0.0.1:8888"
  - name: destService
    value: "echo"
  - name: methodName
    value: "echo"
  - name: version
    value: "0.5.0"

规范元数据字段

bindings.kitex 的 InvokeRequest.Metadata 要求客户端在进行调用时填写四个必需项：

hostPorts
destService
methodName
version

字段	必填	Binding 支持	详情	示例
`hostPorts`	Y	输出	Kitex 服务器（Thrift）的 IP 地址和端口信息	`"127.0.0.1:8888"`
`destService`	Y	输出	Kitex 服务器（Thrift）的服务名称	`"echo"`
`methodName`	Y	输出	Kitex 服务器（Thrift）特定服务名称下的方法名称	`"echo"`
`version`	Y	输出	Kitex 版本	`"0.5.0"`

Binding 支持

此组件支持输出 binding，支持以下操作：

get

示例

使用 Kitex binding 时：

客户端需要传入正确的 Thrift 编码的二进制数据
服务器需要是 Thrift Server。

kitex_output_test 可作为参考。例如，变量 reqData 需要在发送前由 Thrift 协议_编码_，返回的数据需要由 Thrift 协议解码。

请求

{
  "operation": "get",
  "metadata": {
    "hostPorts": "127.0.0.1:8888",
    "destService": "echo",
    "methodName": "echo",
    "version":"0.5.0"
  },
  "data": reqdata
}

1.31 - KubeMQ 绑定规范

KubeMQ 绑定组件的详细文档

组件格式

要设置 KubeMQ 绑定，请创建类型为 bindings.kubemq 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: binding-topic
spec:
  type: bindings.kubemq
  version: v1
  metadata:
    - name: address
      value: "localhost:50000"
    - name: channel
      value: "queue1"
    - name: direction
      value: "input, output"

规范元数据字段

字段	必填	详情	示例
`address`	Y	KubeMQ 服务器的地址	`"localhost:50000"`
`channel`	Y	队列通道名称	`"queue1"`
`authToken`	N	用于连接的身份验证 JWT 令牌。查看 KubeMQ Authentication	`"ew..."`
`autoAcknowledged`	N	设置接收到的队列消息是否自动确认	`"true"` 或 `"false"`（默认为 `"false"`）
`pollMaxItems`	N	设置每次连接时轮询的消息数量	`"1"`
`pollTimeoutSeconds`	N	设置每次轮询间隔的时间（秒）	`"3600"`
`direction`	N	绑定的方向	`"input"`、`"output"`、`"input, output"`

绑定支持

此组件同时支持 输入和输出 绑定接口。

创建 KubeMQ broker

获取 KubeMQ Key。
等待包含您的密钥的邮件确认

您可以使用 Docker 运行 KubeMQ broker：

docker run -d -p 8080:8080 -p 50000:50000 -p 9090:9090 -e KUBEMQ_TOKEN=<your-key> kubemq/kubemq

然后您可以使用客户端端口与服务器交互：localhost:50000

获取 KubeMQ Key。
等待包含您的密钥的邮件确认

然后运行以下 kubectl 命令：

kubectl apply -f https://deploy.kubemq.io/init

kubectl apply -f https://deploy.kubemq.io/key/<your-key>

安装 KubeMQ CLI

访问 KubeMQ CLI 并下载最新版本的 CLI。

浏览 KubeMQ Dashboard

打开浏览器并导航到 http://localhost:8080

安装了 KubeMQCTL 后，运行以下命令：

kubemqctl get dashboard

或者，安装了 kubectl 后，运行 port-forward 命令：

kubectl port-forward svc/kubemq-cluster-api -n kubemq 8080:8080

KubeMQ 文档

访问 KubeMQ Documentation 获取更多信息。

1.32 - Kubernetes Events 绑定规范

Kubernetes Events 绑定组件的详细文档

组件格式

要设置 Kubernetes Events 绑定，需创建类型为 bindings.kubernetes 的组件。有关如何创建和应用绑定配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.kubernetes
  version: v1
  metadata:
  - name: namespace
    value: "<NAMESPACE>"
  - name: resyncPeriodInSec
    value: "<seconds>"
  - name: direction
    value: "input"

规范元数据字段

字段	是否必填	绑定支持	详细信息	示例
`namespace`	Y	Input	从指定 Kubernetes 命名空间读取事件	`"default"`
`resyncPeriodInSec`	N	Input	从 Kubernetes API 服务器刷新事件列表的时间间隔。默认值为 `"10"`	`"15"`
`direction`	N	Input	绑定的数据流向方向	`"input"`
`kubeconfigPath`	N	Input	kubeconfig 文件的路径。如未指定，绑定将使用默认的集群内配置	`"/path/to/kubeconfig"`

绑定支持

此组件支持输入绑定接口。

输出格式

绑定接收到的输出格式为 bindings.ReadResponse，其中 Data 字段包含如下结构：

 {
   "event": "",
   "oldVal": {
     "metadata": {
       "name": "hello-node.162c2661c524d095",
       "namespace": "kube-events",
       "selfLink": "/api/v1/namespaces/kube-events/events/hello-node.162c2661c524d095",
       ...
     },
     "involvedObject": {
       "kind": "Deployment",
       "namespace": "kube-events",
       ...
     },
     "reason": "ScalingReplicaSet",
     "message": "Scaled up replica set hello-node-7bf657c596 to 1",
     ...
   },
   "newVal": {
     "metadata": { "creationTimestamp": "null" },
     "involvedObject": {},
     "source": {},
     "firstTimestamp": "null",
     "lastTimestamp": "null",
     "eventTime": "null",
     ...
   }
 }

提供三种事件类型：

添加：仅填充 newVal 字段，oldVal 字段为空的 v1.Event，event 值为 add
删除：仅填充 oldVal 字段，newVal 字段为空的 v1.Event，event 值为 delete
更新：同时填充 oldVal 和 newVal 字段，event 值为 update

必需权限

要从 Kubernetes 使用 events，需通过 Kubernetes 的 [RBAC Auth] 机制为用户/组/服务账户分配权限。

角色

需要包含以下规则之一，以授予 get、watch 和 list events 的权限。API 组可根据需要设置为尽可能受限。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: <ROLENAME>
rules:
- apiGroups: [""]
  resources: ["events"]
  verbs: ["get", "watch", "list"]

RoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: <NAME>
subjects:
- kind: ServiceAccount
  name: default # 可根据需要修改
roleRef:
  kind: Role
  name: <ROLENAME> # 与上述名称一致
  apiGroup: ""

1.33 - Local Storage 绑定规范

Local Storage 绑定组件的详细文档

组件格式

要设置 Local Storage 绑定，请创建一个类型为 bindings.localstorage 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.localstorage
  version: v1
  metadata:
  - name: rootPath
    value: "<string>"

规范元数据字段

字段	必填	绑定支持	详情	示例
`rootPath`	Y	Output	可读取/保存文件的根路径锚点	`"/temp/files"`

绑定支持

此组件支持输出绑定，包含以下操作：

create : 创建文件
get : 获取文件
list : 列出文件
delete : 删除文件

创建文件

要执行创建文件操作，请使用 POST 方法调用 Local Storage 绑定，并提供以下 JSON 请求体：

注意：默认情况下，会生成一个随机 UUID。请参阅下方的 Metadata 支持以设置名称

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

示例

保存文本到随机生成的 UUID 文件

在 Windows 上，使用 cmd 提示符（PowerShell 有不同的转义机制）

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

保存文本到指定文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"fileName\": \"my-test-file.txt\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "fileName": "my-test-file.txt" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

保存二进制文件

要上传文件，请将其编码为 Base64。绑定会自动检测 Base64 编码。

curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"fileName\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "fileName": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体将包含以下 JSON：

{
   "fileName": "<filename>"
}

获取文件

要执行获取文件操作，请使用 POST 方法调用 Local Storage 绑定，并提供以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "fileName": "myfile"
  }
}

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"fileName\": \"myfile\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "fileName": "myfile" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含存储在文件中的值。

列出文件

要执行列出文件操作，请使用 POST 方法调用 Local Storage 绑定，并提供以下 JSON 请求体：

{
  "operation": "list"
}

如果您只想列出 rootPath 下特定目录中的文件，请在元数据中将相对目录名称指定为 fileName。

{
  "operation": "list",
  "metadata": {
    "fileName": "my/cool/directory"
  }
}

示例

curl -d '{ \"operation\": \"list\", \"metadata\": { \"fileName\": \"my/cool/directory\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "list", "metadata": { "fileName": "my/cool/directory" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应是一个文件名的 JSON 数组。

删除文件

要执行删除文件操作，请使用 POST 方法调用 Local Storage 绑定，并提供以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "fileName": "myfile"
  }
}

示例

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"fileName\": \"myfile\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "fileName": "myfile" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

如果成功，将返回 HTTP 204（无内容）和空响应体。

元数据信息

默认情况下，Local Storage 输出绑定会自动生成一个 UUID 作为文件名。可以在消息的元数据属性中进行配置。

{
    "data": "file content",
    "metadata": {
        "fileName": "filename.txt"
    },
    "operation": "create"
}

1.34 - MQTT3 binding 规范

MQTT3 binding 组件的详细文档

组件格式

要设置 MQTT3 binding，请创建一个类型为 bindings.mqtt3 的组件。请参阅此指南了解如何创建和应用 binding 配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.mqtt3
  version: v1
  metadata:
    - name: url
      value: "tcp://[username][:password]@host.domain[:port]"
    - name: topic
      value: "mytopic"
    - name: consumerID
      value: "myapp"
    # 可选
    - name: retain
      value: "false"
    - name: cleanSession
      value: "false"
    - name: backOffMaxRetries
      value: "0"
    - name: direction
      value: "input, output"

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体描述请参见此处。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`url`	Y	Input/Output	MQTT broker 的地址。可以是 `secretKeyRef` 以使用密钥引用。对于非 TLS 通信，使用 `tcp://` URI scheme。对于 TLS 通信，使用 `ssl://` URI scheme。	`"tcp://[username][:password]@host.domain[:port]"`
`topic`	Y	Input/Output	要监听或发送事件的主题。	`"mytopic"`
`consumerID`	Y	Input/Output	用于连接到 MQTT broker 的客户端 ID。	`"myMqttClientApp"`
`retain`	N	Input/Output	定义消息是否由 broker 保存为指定主题的最后一个已知良好值。默认为 `"false"`。	`"true"`, `"false"`
`cleanSession`	N	Input/Output	如果为 `"true"`，则在向 MQTT broker 发送的连接消息中设置 `clean_session` 标志。默认为 `"false"`。	`"true"`, `"false"`
`caCert`	使用 TLS 时必填	Input/Output	PEM 格式的证书颁发机构（CA）证书，用于验证服务器 TLS 证书。	见下方示例
`clientCert`	使用 TLS 时必填	Input/Output	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	见下方示例
`clientKey`	使用 TLS 时必填	Input/Output	PEM 格式的 TLS 客户端密钥。必须与 `clientCert` 一起使用。可以是 `secretKeyRef` 以使用密钥引用。	见下方示例
`backOffMaxRetries`	N	Input	在返回错误之前处理消息的最大重试次数。默认为 `"0"`，表示不进行重试。可以指定 `"-1"` 表示消息应无限重试，直到成功处理或应用程序关闭。组件将在重试之间等待 5 秒。	`"3"`
`direction`	N	Input/Output	binding 的方向	`"input"`, `"output"`, `"input, output"`

使用 TLS 进行通信

要配置使用 TLS 的通信，请确保 MQTT broker（例如 emqx）配置为支持证书，并在组件配置中提供 caCert、clientCert、clientKey 元数据。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-binding
spec:
  type: bindings.mqtt3
  version: v1
  metadata:
    - name: url
      value: "ssl://host.domain[:port]"
    - name: topic
      value: "topic1"
    - name: consumerID
      value: "myapp"
    # TLS 配置
    - name: caCert
      value: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    - name: clientCert
      value: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    - name: clientKey
      secretKeyRef:
        name: myMqttClientKey
        key: myMqttClientKey
    # 可选
    - name: retain
      value: "false"
    - name: cleanSession
      value: "false"
    - name: backoffMaxRetries
      value: "0"

请注意，虽然 caCert 和 clientCert 值可能不是密钥，但为了方便，它们也可以从 Dapr 密钥存储中引用。

消费共享主题

当消费共享主题时，每个消费者必须具有唯一标识符。如果运行应用程序的多个实例，您可以使用 {uuid} 标记配置组件的 consumerID 元数据，这将在启动时为每个实例提供随机生成的 consumerID 值。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-binding
  namespace: default
spec:
  type: bindings.mqtt3
  version: v1
  metadata:
  - name: consumerID
    value: "{uuid}"
  - name: url
    value: "tcp://admin:public@localhost:1883"
  - name: topic
    value: "topic1"
  - name: retain
    value: "false"
  - name: cleanSession
    value: "true"
  - name: backoffMaxRetries
    value: "0"

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体描述请参见此处。

在这种情况下，每次 Dapr 重启时消费者 ID 的值都是随机的，因此您还应该将 cleanSession 设置为 "true"。

Binding 支持

此组件同时支持 输入和输出 binding 接口。

此组件支持以下操作的 输出 binding：

create：发布新消息

按请求设置主题

您可以在每次请求时覆盖组件元数据中的主题：

{
  "operation": "create",
  "metadata": {
    "topic": "myTopic"
  },
  "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
}

按请求设置 retain 属性

您可以在每次请求时覆盖组件元数据中的 retain 属性：

{
  "operation": "create",
  "metadata": {
    "retain": "true"
  },
  "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
}

1.35 - MySQL & MariaDB 绑定规范

MySQL 绑定组件的详细文档

组件格式

MySQL 绑定允许连接到 MySQL 和 MariaDB 数据库。在本文档中，我们使用"MySQL"来指代这两种数据库。

要设置 MySQL 绑定，需创建一个类型为 bindings.mysql 的组件。请参阅此指南了解如何创建和应用绑定配置。

MySQL 绑定内部使用 Go-MySQL-Driver。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.mysql
  version: v1
  metadata:
    - name: url # 必填，以 DSN 格式定义数据库连接
      value: "<CONNECTION_STRING>"
    - name: pemPath # 可选
      value: "<PEM PATH>"
    - name: maxIdleConns
      value: "<MAX_IDLE_CONNECTIONS>"
    - name: maxOpenConns
      value: "<MAX_OPEN_CONNECTIONS>"
    - name: connMaxLifetime
      value: "<CONNECTION_MAX_LIFE_TIME>"
    - name: connMaxIdleTime
      value: "<CONNECTION_MAX_IDLE_TIME>"

警告

上述示例将密钥以纯文本字符串的形式使用。建议按照此处的描述，使用密钥存储来管理密钥。请注意，你不能仅对用户名/密码使用密钥。如果使用密钥，则必须用于完整的连接字符串。

规范元数据字段

字段	必填	绑定支持	详情	示例
`url`	Y	输出	以数据源名称（DSN）格式表示数据库连接。参见此处的 SSL 详情	`"user:password@tcp(localhost:3306)/dbname"`
`pemPath`	Y	输出	PEM 文件的路径。用于 SSL 连接	`"path/to/pem/file"`
`maxIdleConns`	N	输出	最大空闲连接数。大于 0 的整数	`"10"`
`maxOpenConns`	N	输出	最大打开连接数。大于 0 的整数	`"10"`
`connMaxLifetime`	N	输出	最大连接生存时间。持续时间字符串	`"12s"`
`connMaxIdleTime`	N	输出	最大连接空闲时间。持续时间字符串	`"12s"`

SSL 连接

如果你的服务器需要 SSL，你的连接字符串必须以 &tls=custom 结尾，例如：

"<user>:<password>@tcp(<server>:3306)/<database>?allowNativePasswords=true&tls=custom"

你必须将 <PEM PATH> 替换为 PEM 文件的完整路径。如果你使用的是 Azure Database for MySQL，请参阅 Azure 关于 SSL 数据库连接的文档，了解如何下载所需的证书。与 MySQL 的连接至少需要 TLS 1.2 版本。

多条语句

默认情况下，MySQL Go driver 每个查询/命令仅支持一条 SQL 语句。

要允许在一个查询中使用多条语句，你需要向查询字符串添加 multiStatements=true，例如：

"<user>:<password>@tcp(<server>:3306)/<database>?multiStatements=true"

虽然这允许批量查询，但也大大增加了 SQL 注入的风险。仅返回第一个查询的结果，所有其他结果都被静默丢弃。

绑定支持

此组件支持具有以下操作的输出绑定：

exec
query
close

参数化查询

此绑定支持参数化查询，允许将 SQL 查询本身与用户提供的值分开。出于安全原因，强烈建议使用参数化查询，因为它们可以防止 SQL 注入攻击。

例如：

-- ❌ 错误！在查询中包含值，并且容易受到 SQL 注入攻击。
SELECT * FROM mytable WHERE user_key = 'something';

-- ✅ 正确！使用参数化查询。
-- 这将使用参数 ["something"] 执行
SELECT * FROM mytable WHERE user_key = ?;

exec

exec 操作可用于 DDL 操作（如表创建），以及仅返回元数据（例如受影响的行数）的 INSERT、UPDATE、DELETE 操作。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "exec",
  "metadata": {
    "sql": "INSERT INTO foo (id, c1, ts) VALUES (?, ?, ?)",
    "params": "[1, \"demo\", \"2020-09-24T11:45:05Z07:00\"]"
  }
}

响应

{
  "metadata": {
    "operation": "exec",
    "duration": "294µs",
    "start-time": "2020-09-24T11:13:46.405097Z",
    "end-time": "2020-09-24T11:13:46.414519Z",
    "rows-affected": "1",
    "sql": "INSERT INTO foo (id, c1, ts) VALUES (?, ?, ?)"
  }
}

query

query 操作用于 SELECT 语句，它返回元数据以及以行值数组形式的数据。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "query",
  "metadata": {
    "sql": "SELECT * FROM foo WHERE id < $1",
    "params": "[3]"
  }
}

响应

{
  "metadata": {
    "operation": "query",
    "duration": "432µs",
    "start-time": "2020-09-24T11:13:46.405097Z",
    "end-time": "2020-09-24T11:13:46.420566Z",
    "sql": "SELECT * FROM foo WHERE id < ?"
  },
  "data": [
    {column_name: value, column_name: value, ...},
    {column_name: value, column_name: value, ...},
    {column_name: value, column_name: value, ...},
  ]
}

这里 column_name 是查询返回的列的名称，value 是该列的值。请注意，值作为字符串或数字返回（特定于语言的数据类型）

close

close 操作可用于显式关闭数据库连接并将其返回到连接池。此操作没有任何响应。

请求

{
  "operation": "close"
}

1.36 - PostgreSQL 绑定规范

PostgreSQL 绑定组件的详细文档

组件格式

要设置 PostgreSQL 绑定，需创建一个类型为 bindings.postgresql 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.postgresql
  version: v1
  metadata:
    # 连接字符串
    - name: connectionString
      value: "<CONNECTION STRING>"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

使用连接字符串进行身份验证

使用 PostgreSQL 连接字符串进行身份验证时，以下元数据选项是必需的。

字段	必需	详情	示例
`connectionString`	Y	PostgreSQL 数据库的连接字符串。有关如何定义连接字符串的信息，请参阅 PostgreSQL 关于数据库连接的文档。	`"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`

使用单独的连接参数进行身份验证

除了使用连接字符串外，您还可以选择指定单独的连接参数。这些参数等同于标准的 PostgreSQL 连接参数。

字段	必需	详情	示例
`host`	Y	PostgreSQL 服务器的主机名或 IP 地址	`"localhost"`
`hostaddr`	N	PostgreSQL 服务器的 IP 地址（host 的替代选项）	`"127.0.0.1"`
`port`	Y	PostgreSQL 服务器的端口号	`"5432"`
`database`	Y	要连接的数据库名称	`"my_db"`
`user`	Y	用于连接的 PostgreSQL 用户	`"postgres"`
`password`	Y	PostgreSQL 用户的密码	`"example"`
`sslRootCert`	N	SSL 根证书文件的路径	`"/path/to/ca.crt"`

注意

使用单独的连接参数时，这些参数将覆盖 connectionString 中存在的参数。

使用 Microsoft Entra ID 进行身份验证

支持使用 Microsoft Entra ID 对 Azure Database for PostgreSQL 进行身份验证。可以使用 Dapr 支持的所有身份验证方法，包括客户端凭据（“服务主体”）和托管标识。

字段	必需	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以使组件能够从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含用户，该用户对应于在 PostgreSQL 内部创建的映射到 Microsoft Entra ID 标识的用户名称；这通常是相应主体的名称（例如 Microsoft Entra ID 应用程序的名称）。此连接字符串不应包含任何密码。	`"host=mydb.postgres.database.azure.com user=myapplication port=5432 database=my_db sslmode=require"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-…"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-…"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

支持使用 AWS IAM 对所有版本的 PostgreSQL 类型组件进行身份验证。连接字符串中指定的用户必须是数据库中已存在的用户，并且是已授予 rds_iam 数据库角色的 AWS IAM 启用用户。身份验证基于 AWS 身份验证配置文件，或提供的 AccessKey/SecretKey。 AWS 身份验证令牌将在其过期时间之前动态轮换。

字段	必需	详情	示例
`useAWSIAM`	Y	必须设置为 `true` 以使组件能够从 AWS IAM 获取访问令牌。此身份验证方法仅适用于 AWS Relational Database Service for PostgreSQL 数据库。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含已存在的用户，该用户对应于在 PostgreSQL 内部创建的映射到 AWS IAM 策略的用户名称。此连接字符串不应包含任何密码。请注意，对于 AWS，数据库名称字段由 dbname 表示。	`"host=mydb.postgres.database.aws.com user=myapplication port=5432 dbname=my_db sslmode=require"`
`awsRegion`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘region’。部署 AWS Relational Database Service 的 AWS 区域。	`"us-east-1"`
`awsAccessKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘accessKey’。与 IAM 账户关联的 AWS 访问密钥	`"AKIAIOSFODNN7EXAMPLE"`
`awsSecretKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘secretKey’。与访问密钥关联的密钥	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`awsSessionToken`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅当您使用临时安全凭证时才需要会话令牌。	`"TOKEN"`

其他元数据选项

字段	必需	绑定支持	详情	示例
`timeout`	N	输出	数据库操作的超时时间，格式为 Go duration。整数将被解释为秒数。默认为 `20s`	`"30s"`, `30`
`maxConns`	N	输出	此组件池化的最大连接数。设置为 0 或更小以使用默认值，默认值为 4 或 CPU 数量中的较大者。	`"4"`
`connectionMaxIdleTime`	N	输出	在连接池中自动关闭未使用连接之前的最大空闲时间。默认情况下，没有此值，由数据库驱动程序选择。	`"5m"`
`queryExecMode`	N	输出	控制执行查询的默认模式。默认情况下，Dapr 使用扩展协议并自动准备和缓存预处理语句。但是，这可能与 PGBouncer 等代理不兼容。在这种情况下，使用 `exec` 或 `simple_protocol` 可能更合适。	`"simple_protocol"`

URL 格式

PostgreSQL 绑定内部使用 pgx connection pool，因此 connectionString 参数可以是任何有效的连接字符串，格式为 DSN 或 URL：

DSN 示例

user=dapr password=secret host=dapr.example.com port=5432 dbname=my_dapr sslmode=verify-ca

URL 示例

postgres://dapr:secret@dapr.example.com:5432/my_dapr?sslmode=verify-ca

这两种方法也支持连接池配置变量：

pool_min_conns: 整数 0 或更大
pool_max_conns: 大于 0 的整数
pool_max_conn_lifetime: 持续时间字符串
pool_max_conn_idle_time: 持续时间字符串
pool_health_check_period: 持续时间字符串

绑定支持

此组件支持输出绑定，具有以下操作：

exec
query
close

参数化查询

此绑定支持参数化查询，允许将 SQL 查询本身与用户提供的值分开。出于安全原因，强烈建议使用参数化查询，因为它们可以防止 SQL 注入攻击。

例如：

-- ❌ 错误！在查询中包含值，并且容易受到 SQL 注入攻击。
SELECT * FROM mytable WHERE user_key = 'something';

-- ✅ 正确！使用参数化查询。
-- 这将使用参数 ["something"] 执行
SELECT * FROM mytable WHERE user_key = $1;

exec

exec 操作可用于 DDL 操作（如表创建），以及仅返回元数据（例如受影响的行数）的 INSERT、UPDATE、DELETE 操作。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "exec",
  "metadata": {
    "sql": "INSERT INTO foo (id, c1, ts) VALUES ($1, $2, $3)",
    "params": "[1, \"demo\", \"2020-09-24T11:45:05Z07:00\"]"
  }
}

响应

{
  "metadata": {
    "operation": "exec",
    "duration": "294µs",
    "start-time": "2020-09-24T11:13:46.405097Z",
    "end-time": "2020-09-24T11:13:46.414519Z",
    "rows-affected": "1",
    "sql": "INSERT INTO foo (id, c1, ts) VALUES ($1, $2, $3)"
  }
}

query

query 操作用于 SELECT 语句，它以行值数组的形式返回数据以及元数据。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "query",
  "metadata": {
    "sql": "SELECT * FROM foo WHERE id < $1",
    "params": "[3]"
  }
}

响应

{
  "metadata": {
    "operation": "query",
    "duration": "432µs",
    "start-time": "2020-09-24T11:13:46.405097Z",
    "end-time": "2020-09-24T11:13:46.420566Z",
    "sql": "SELECT * FROM foo WHERE id < $1"
  },
  "data": "[
    [0,\"test-0\",\"2020-09-24T04:13:46Z\"],
    [1,\"test-1\",\"2020-09-24T04:13:46Z\"],
    [2,\"test-2\",\"2020-09-24T04:13:46Z\"]
  ]"
}

close

close 操作可用于显式关闭数据库连接并将其返回到池中。此操作没有任何响应。

请求

{
  "operation": "close"
}

1.37 - Postmark binding 规范

Postmark binding 组件的详细文档

组件格式

要设置 Postmark binding，请创建一个类型为 bindings.postmark 的组件。有关如何创建和应用 binding 配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: postmark
spec:
  type: bindings.postmark
  metadata:
  - name: accountToken
    value: "YOUR_ACCOUNT_TOKEN" # 必填，这是您的 Postmark 账户令牌
  - name: serverToken
    value: "YOUR_SERVER_TOKEN" # 必填，这是您的 Postmark 服务器令牌
  - name: emailFrom
    value: "testapp@dapr.io" # 可选
  - name: emailTo
    value: "dave@dapr.io" # 可选
  - name: subject
    value: "Hello!" # 可选

Warning

上述示例使用纯文本字符串形式的密钥。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`accountToken`	Y	Output	Postmark 账户令牌，应将其视为密钥值	`"account token"`
`serverToken`	Y	Output	Postmark 服务器令牌，应将其视为密钥值	`"server token"`
`emailFrom`	N	Output	如果设置，则指定电子邮件的"发件人"地址	`"me@exmaple.com"`
`emailTo`	N	Output	如果设置，则指定电子邮件的"收件人"地址	`"me@example.com"`
`emailCc`	N	Output	如果设置，则指定电子邮件的"抄送"地址	`"me@example.com"`
`emailBcc`	N	Output	如果设置，则指定电子邮件的"密送"地址	`"me@example.com"`
`subject`	N	Output	如果设置，则指定电子邮件的主题	`"me@example.com"`

您也可以在输出 binding 请求中指定任何可选的元数据属性（例如 emailFrom、emailTo、subject 等）。

综合来看，组件配置和请求负载中的可选元数据属性应至少包含 emailFrom、emailTo 和 subject 字段，因为成功发送电子邮件需要这些字段。

Binding 支持

此组件支持 输出 binding，具有以下操作：

create

示例请求负载

{
  "operation": "create",
  "metadata": {
    "emailTo": "changeme@example.net",
    "subject": "An email from Dapr Postmark binding"
  },
  "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
}

1.38 - RabbitMQ 绑定规范

RabbitMQ 绑定组件的详细文档

组件格式

要设置 RabbitMQ 绑定，需创建一个类型为 bindings.rabbitmq 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.rabbitmq
  version: v1
  metadata:
  - name: queueName
    value: "queue1"
  - name: host
    value: "amqp://[username][:password]@host.domain[:port]"
  - name: durable
    value: "true"
  - name: deleteWhenUnused
    value: "false"
  - name: ttlInSeconds
    value: "60"
  - name: prefetchCount
    value: "0"
  - name: exclusive
    value: "false"
  - name: maxPriority
    value: "5"
  - name: contentType
    value: "text/plain"
  - name: reconnectWaitInSeconds
    value: "5"
  - name: externalSasl
    value: "false"
  - name: caCert
    value: "null"
  - name: clientCert
    value: "null"
  - name: clientKey
    value: "null"
  - name: direction 
    value: "input, output"

警告

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，具体操作请参阅此处。

规范元数据字段

当发布新的 RabbitMQ 消息时，关联元数据中的所有值都会被添加到消息的标头值中。

字段	必填	绑定支持	详情	示例
`queueName`	Y	Input/Output	RabbitMQ 队列名称	`"myqueue"`
`host`	Y	Input/Output	RabbitMQ 主机地址	`"amqp://[username][:password]@host.domain[:port]"` 或使用 TLS：`"amqps://[username][:password]@host.domain[:port]"`
`durable`	N	Output	告诉 RabbitMQ 将消息持久化到存储。默认值为 `"false"`	`"true"`, `"false"`
`deleteWhenUnused`	N	Input/Output	启用或禁用自动删除。默认值为 `"false"`	`"true"`, `"false"`
`ttlInSeconds`	N	Output	在 RabbitMQ 队列级别设置默认消息存活时间。如果省略此参数，消息将不会过期，会一直存在于队列中直到被处理。另请参阅此处	`60`
`prefetchCount`	N	Input	设置通道预取设置（QoS）。如果省略此参数，QoS 会将值设置为 0，表示无限制	`0`
`exclusive`	N	Input/Output	确定主题是否为独占主题。默认值为 `"false"`	`"true"`, `"false"`
`maxPriority`	N	Input/Output	用于设置优先级队列的参数。如果省略此参数，队列将创建为常规队列而非优先级队列。值范围为 1 到 255。另请参阅此处	`"1"`, `"10"`
`contentType`	N	Input/Output	消息的内容类型。默认值为 “text/plain”。	`"text/plain"`, `"application/cloudevent+json"` 等
`reconnectWaitInSeconds`	N	Input/Output	表示客户端在断开连接后尝试重新连接到服务器之前应等待的持续时间（秒）。默认值为 `"5"`。	`"5"`, `"10"`
`externalSasl`	N	Input/Output	使用 TLS 时，是否应从额外字段（如 CN）获取用户名。请参阅 RabbitMQ 身份验证机制。默认值为 `"false"`。	`"true"`, `"false"`
`caCert`	N	Input/Output	用于 TLS 连接的 CA 证书。默认值为 `null`。	`"-----BEGIN CERTIFICATE-----\nMI..."`
`clientCert`	N	Input/Output	用于 TLS 连接的客户端证书。默认值为 `null`。	`"-----BEGIN CERTIFICATE-----\nMI..."`
`clientKey`	N	Input/Output	用于 TLS 连接的客户端密钥。默认值为 `null`。	`"-----BEGIN PRIVATE KEY-----\nMI..."`
`direction`	N	Input/Output	绑定的方向。	`"input"`, `"output"`, `"input, output"`

绑定支持

此组件同时支持输入和输出绑定接口。

此组件支持输出绑定，具有以下操作：

create

为每条消息指定 TTL

存活时间可以在队列级别（如上所示）或消息级别定义。在消息级别定义的值会覆盖队列级别设置的任何值。

要在消息级别设置存活时间，请在绑定调用期间使用请求体中的 metadata 部分。

字段名称为 ttlInSeconds。

示例：

curl -X POST http://localhost:3500/v1.0/bindings/myRabbitMQ \
  -H "Content-Type: application/json" \
  -d "{
        \"data\": {
          \"message\": \"Hi\"
        },
        \"metadata\": {
          \"ttlInSeconds\": "60"
        },
        \"operation\": \"create\"
      }"

curl -X POST http://localhost:3500/v1.0/bindings/myRabbitMQ \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "ttlInSeconds": "60"
        },
        "operation": "create"
      }'

为每条消息指定优先级

优先级可以在消息级别定义。如果设置了 maxPriority 参数，高优先级消息将优先于其他低优先级消息。

要在消息级别设置优先级，请在绑定调用期间使用请求体中的 metadata 部分。

字段名称为 priority。

示例：

curl -X POST http://localhost:3500/v1.0/bindings/myRabbitMQ \
  -H "Content-Type: application/json" \
  -d "{
        \"data\": {
          \"message\": \"Hi\"
        },
        \"metadata\": {
          "priority": \"5\"
        },
        \"operation\": \"create\"
      }"

curl -X POST http://localhost:3500/v1.0/bindings/myRabbitMQ \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        },
        "metadata": {
          "priority": "5"
        },
        "operation": "create"
      }'

1.39 - Redis binding spec

Redis 绑定组件的详细文档

组件格式

要设置 Redis 绑定，需创建一个类型为 bindings.redis 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.redis
  version: v1
  metadata:
  - name: redisHost
    value: "<address>:6379"
  - name: redisPassword
    value: "**************"
  - name: useEntraID
    value: "true"
  - name: enableTLS
    value: "<bool>"

Warning

上述示例使用明文字符串表示密钥。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`redisHost`	Y	输出	redis 主机的连接字符串。如果 `"redisType"` 为 `"cluster"`，可以是多个用逗号分隔的主机或单个主机。使用 Redis Sentinel（`"failover"` 为 `"true"`）时，也可以提供多个 sentinel 地址，用逗号分隔。	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379`
`redisPassword`	N	输出	Redis 密码	`"password"`
`redisUsername`	N	输出	Redis 主机的用户名。默认为空。请确保您的 redis 服务器版本为 6 或以上，并且已正确创建 acl 规则。	`"username"`
`useEntraID`	N	输出	为 Azure Cache for Redis 实现 EntraID 支持。启用此功能前： `redisHost` 名称必须以 `"server:port"` 的形式指定必须启用 TLS 在创建 Redis 实例 > Azure Cache for Redis下了解有关此设置的更多信息	`"true"`, `"false"`
`enableTLS`	N	输出	如果 Redis 实例支持带有公共证书的 TLS，可以配置为启用或禁用 TLS。默认为 `"false"`	`"true"`, `"false"`
`clientCert`	N	输出	客户端证书的内容，用于需要客户端证书的 Redis 实例。必须与 `clientKey` 一起使用，并且 `enableTLS` 必须设置为 true。建议按照此处的说明使用密钥存储	`"----BEGIN CERTIFICATE-----\nMIIC..."`
`clientKey`	N	输出	客户端私钥的内容，与 `clientCert` 结合使用进行身份验证。建议按照此处的说明使用密钥存储	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
`failover`	N	输出	用于启用故障转移配置的属性。需要设置 sentinelMasterName。启用时，redisHost 应包含 sentinel 地址。默认为 `"false"`	`"true"`, `"false"`
`sentinelMasterName`	N	输出	sentinel 主节点名称。请参阅 Redis Sentinel 文档	`""`, `"mymaster"`
`sentinelUsername`	N	输出	Redis Sentinel 的用户名。仅在 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"username"`
`sentinelPassword`	N	输出	Redis Sentinel 的密码。仅在 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"password"`
`redeliverInterval`	N	输出	检查待重新投递消息的间隔时间。默认为 `"60s"`。`"0"` 禁用重新投递。	`"30s"`
`processingTimeout`	N	输出	消息在尝试重新投递前必须保持待处理的时间量。默认为 `"15s"`。`"0"` 禁用重新投递。	`"30s"`
`redisType`	N	输出	redis 的类型。有两个有效值，一个是 `"node"` 用于单节点模式，另一个是 `"cluster"` 用于 redis 集群模式。默认为 `"node"`。	`"cluster"`
`redisDB`	N	输出	连接到 redis 后选择的数据库。如果 `"redisType"` 是 `"cluster"`，则忽略此选项。默认为 `"0"`。	`"0"`
`redisMaxRetries`	N	输出	放弃前重试命令的最大次数。默认不重试失败的命令。	`"5"`
`redisMinRetryInterval`	N	输出	每次重试之间 redis 命令的最小退避时间。默认为 `"8ms"`； `"-1"` 禁用退避。	`"8ms"`
`redisMaxRetryInterval`	N	输出	每次重试之间 redis 命令的最大退避时间。默认为 `"512ms"`；`"-1"` 禁用退避。	`"5s"`
`dialTimeout`	N	输出	建立新连接的拨号超时时间。默认为 `"5s"`。	`"5s"`
`readTimeout`	N	输出	套接字读取超时时间。如果达到超时，redis 命令将以超时失败而不是阻塞。默认为 `"3s"`，`"-1"` 表示无超时。	`"3s"`
`writeTimeout`	N	输出	套接字写入超时时间。如果达到超时，redis 命令将以超时失败而不是阻塞。默认为 readTimeout。	`"3s"`
`poolSize`	N	输出	套接字连接的最大数量。默认为每个 CPU 10 个连接，由 runtime.NumCPU 报告。	`"20"`
`poolTimeout`	N	输出	如果所有连接都忙，客户端等待连接的时间量，然后返回错误。默认为 readTimeout + 1 秒。	`"5s"`
`maxConnAge`	N	输出	连接的年龄，客户端在该年龄后关闭连接。默认不关闭旧连接。	`"30m"`
`minIdleConns`	N	输出	保持打开的最小空闲连接数，以避免与创建新连接相关的性能下降。默认为 `"0"`。	`"2"`
`idleCheckFrequency`	N	输出	空闲连接清理器执行的空闲检查频率。默认为 `"1m"`。 `"-1"` 禁用空闲连接清理器。	`"-1"`
`idleTimeout`	N	输出	客户端关闭空闲连接的时间量。应小于服务器的超时时间。默认为 `"5m"`。 `"-1"` 禁用空闲超时检查。	`"10m"`

绑定支持

此组件支持具有以下操作的输出绑定：

create
get
delete

create

您可以使用 create 操作在 Redis 中存储记录。这将设置一个键来保存一个值。如果该键已存在，则覆盖该值。

请求

{
  "operation": "create",
  "metadata": {
    "key": "key1"
  },
  "data": {
    "Hello": "World",
    "Lorem": "Ipsum"
  }
}

响应

如果成功，返回 HTTP 204（无内容）和空正文。

get

您可以使用 get 操作在 Redis 中获取记录。这将获取一个先前设置的键。

这采用一个可选参数 delete，默认为 false。当设置为 true 时，此操作使用 Redis 的 GETDEL 操作。例如，它返回先前设置的 value 然后删除它。

请求

{
  "operation": "get",
  "metadata": {
    "key": "key1"
  },
  "data": {
  }
}

响应

{
  "data": {
    "Hello": "World",
    "Lorem": "Ipsum"
  }
}

带有 delete 标志的请求

{
  "operation": "get",
  "metadata": {
    "key": "key1",
    "delete": "true"
  },
  "data": {
  }
}

delete

您可以使用 delete 操作在 Redis 中删除记录。无论键是否存在，都返回成功。

请求

{
  "operation": "delete",
  "metadata": {
    "key": "key1"
  }
}

响应

如果成功，返回 HTTP 204（无内容）和空正文。

创建 Redis 实例

Dapr 可以使用任何 Redis 实例 - 容器化、在本地开发机器上运行或托管云服务，只要 Redis 的版本为 5.0.0 或更高版本。

注意：Dapr 不支持 Redis >= 7。建议使用 Redis 6

Dapr CLI 将自动为您创建并设置 Redis Streams 实例。当您运行 dapr init 时，Redis 实例将通过 Docker 安装，组件文件将在默认目录中创建。（$HOME/.dapr/components 目录（Mac/Linux）或 Windows 上的 %USERPROFILE%\.dapr\components）。

您可以使用 Helm 在我们的 Kubernetes 集群中快速创建 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis --set image.tag=6.2

运行 kubectl get pods 以查看 Redis 容器现在正在您的集群中运行。

在您的 redis.yaml 文件中添加 redis-master:6379 作为 redisHost。例如：

    metadata:
    - name: redisHost
      value: redis-master:6379

接下来，我们将获取 Redis 密码，根据我们使用的操作系统略有不同：
- Windows：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" > encoded.b64，这将创建一个包含您的编码密码的文件。接下来，运行 certutil -decode encoded.b64 password.txt，这会将您的 redis 密码放入名为 password.txt 的文本文件中。复制密码并删除这两个文件。
- Linux/MacOS：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode 并复制输出的密码。
将此密码作为 redisPassword 值添加到您的 redis.yaml 文件中。例如：
```
    - name: redisPassword
      value: "lhDOkwTlp0"
```

AWS Redis

使用官方 Microsoft 文档创建 Azure Cache for Redis 实例。
实例创建后，从 Azure 门户获取主机名（FQDN）和访问密钥。
- 对于主机名：
  - 导航到资源的概述页面。
  - 复制主机名值。
- 对于访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存您的密钥。
将您的密钥和主机名添加到 Dapr 可以应用到集群的 redis.yaml 文件中。
- 如果您正在运行示例，将主机和密钥添加到提供的 redis.yaml 中。
- 如果您从头开始创建项目，请按照组件格式部分中的说明创建 redis.yaml 文件。
将 redisHost 键设置为 [上一步的主机名]:6379，将 redisPassword 键设置为您之前保存的密钥。
**注意：**在生产级应用程序中，请遵循密钥管理说明来安全地管理您的密钥。
启用 EntraID 支持：
- 在您的 Azure Redis 服务器上启用 Entra ID 身份验证。这可能需要几分钟。
- 将 useEntraID 设置为 "true" 以实现 Azure Cache for Redis 的 EntraID 支持。
将 enableTLS 设置为 "true" 以支持 TLS。

注意：useEntraID 假定您的 UserPrincipal（通过 AzureCLICredential）或系统分配的托管标识具有 RedisDataOwner 角色权限。如果使用用户分配的标识，您需要指定 azureClientID 属性。

GCP Cloud MemoryStore

注意

Dapr CLI 在自托管模式下作为 dapr init 命令的一部分自动部署本地 redis 实例。

Redis Sentinel 配置

使用 Redis Sentinel 实现高可用性时，将 redisType 设置为 "node"，使用 failover: "true" 启用故障转移模式，并提供 sentinel 主节点名称。可以在 redisHost 字段中以逗号分隔的列表形式指定多个 sentinel 地址以实现冗余。

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: redis-pubsub
spec:
  type: pubsub.redis
  version: v1
  metadata:
  - name: redisHost
    value: "sentinel1:26379,sentinel2:26379,sentinel3:26379"
  - name: redisType
    value: "node"
  - name: failover
    value: "true"
  - name: sentinelMasterName
    value: "mymaster"
  ```

1.40 - RethinkDB 绑定规范

RethinkDB 绑定组件的详细文档

组件格式

RethinkDB 状态存储支持事务，这意味着它可用于支持 Dapr actors。Dapr 仅持久化 actor 的当前状态，不允许用户跟踪 actor 状态随时间如何变化。

为了使用户能够跟踪 actor 状态的变化，此绑定利用 RethinkDB 的内置能力来监控 RethinkDB 表以及在变化时同时包含 old 和 new 状态的事件。此绑定在 Dapr 状态表上创建一个订阅，并使用 Dapr 输入绑定接口流式传输这些变化。

要设置 RethinkDB 状态变更绑定，请创建类型为 bindings.rethinkdb.statechange 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: changes
spec:
  type: bindings.rethinkdb.statechange
  version: v1
  metadata:
  - name: address
    value: "<REPLACE-RETHINKDB-ADDRESS>" # 必填，例如 127.0.0.1:28015 或 rethinkdb.default.svc.cluster.local:28015。
  - name: database
    value: "<REPLACE-RETHINKDB-DB-NAME>" # 必填，例如 dapr（仅限字母数字）
  - name: direction 
    value: "<DIRECTION-OF-RETHINKDB-BINDING>"

规范元数据字段

字段	必填	绑定支持	详细信息	示例
`address`	Y	Input	RethinkDB 服务器地址	`"27.0.0.1:28015"`, `"rethinkdb.default.svc.cluster.local:28015"`
`database`	Y	Input	RethinDB 数据库名称	`"dapr"`
`direction`	N	Input	绑定的方向	`"input"`

绑定支持

此组件仅支持输入绑定接口。

1.41 - Apache RocketMQ binding 规范

Apache RocketMQ binding 组件的详细文档

组件格式

要设置 Apache RocketMQ binding，请创建一个类型为 bindings.rocketmq 的组件。
有关如何创建和应用 binding 配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.rocketmq
  version: v1
  metadata:
    - name: accessProto
      value: "tcp"
    - name: nameServer
      value: "localhost:9876"
    - name: endpoint
      value: "http://localhost:8080"
    - name: topics
      value: "topic1,topic2"
    - name: consumerGroup
      value: "my-consumer-group"
    # 可选
    - name: consumerBatchSize
      value: "10"
    - name: consumerThreadNums
      value: "4"
    - name: retries
      value: "3"
    - name: instanceId
      value: "my-instance"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用 secret store 来管理密钥。

规范元数据字段

字段	必填	Binding 支持	详情	示例
`topics`	Y	Input/Output	用于发布或订阅的以逗号分隔的主题列表。	`"topic1,topic2"`
`nameServer`	N	Input/Output	RocketMQ name server 地址。	`"localhost:9876"`
`endpoint`	N	Input/Output	RocketMQ 端点（用于 `http` 协议）。	`"http://localhost:8080"`
`accessProto`	N	Input/Output	用于连接 RocketMQ 的 SDK 协议。	`"tcp"`, `"tcp-cgo"`, `"http"`
`consumerGroup`	N	Input/Output	RocketMQ 订阅者的消费者组名称。	`"my-consumer-group"`
`consumerBatchSize`	N	Input	消费消息的批次大小。	`"10"`
`consumerThreadNums`	N	Input	消费者线程数量（用于 `tcp-cgo` 协议）。	`"4"`
`instanceId`	N	Input/Output	RocketMQ 命名空间实例 ID。	`"my-instance"`
`nameServerDomain`	N	Input/Output	RocketMQ name server 的域名。	`"rocketmq.example.com"`
`retries`	N	Input/Output	连接到 RocketMQ broker 的重试次数。	`"3"`
`accessKey`	N	Input/Output	用于身份验证的访问密钥。如果启用了访问控制，则为必填项。	`"access-key"`
`secretKey`	N	Input/Output	用于身份验证的密钥。如果启用了访问控制，则为必填项。	`"secret-key"`

注意：accessKey 和 secretKey 可以存储在 Dapr secret store 中，而不是存储在 YAML 文件中，以提高安全性。

使用访问密钥进行身份验证

要使用访问密钥身份验证，请在配置中包含以下元数据字段：

- name: accessKey
  secretKeyRef:
    name: rocketmq-secrets
    key: accessKey
- name: secretKey
  secretKeyRef:
    name: rocketmq-secrets
    key: secretKey

这允许从 secret store 安全地获取凭据。

Binding 支持

此组件同时支持输入和输出 binding 接口。

此组件支持以下操作的输出 binding：

create：发布新消息
read：从 RocketMQ 主题消费消息

按请求设置主题

您可以按请求覆盖组件元数据中的主题：

{
  "operation": "create",
  "metadata": {
    "topics": "dynamicTopic"
  },
  "data": "This is a test message for RocketMQ!"
}

重试行为

使用 retries 元数据字段指定 Dapr 在失败前应尝试连接 RocketMQ 的次数：

- name: retries
  value: "5"

1.42 - SFTP binding spec

Secure File Transfer Protocol (SFTP) binding 组件的详细文档

组件格式

要设置 SFTP binding，请创建一个类型为 bindings.sftp 的组件。请参阅本指南了解如何创建和应用 binding 配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.sftp
  version: v1
  metadata:
  - name: rootPath
    value: "<string>"
  - name: address
    value: "<string>"
  - name: username
    value: "<string>"
  - name: password
    value: "*****************"
  - name: privateKey
    value: "*****************"
  - name: privateKeyPassphrase
    value: "*****************"
  - name: hostPublicKey
    value: "*****************"
  - name: knownHostsFile
    value: "<string>"
  - name: insecureIgnoreHostKey
    value: "<bool>"
  - name: sequentialMode
    value: "<bool>"

规范元数据字段

Field	Required	Binding support	Details	Example
`rootPath`	Y	Output	默认工作目录的根路径	`"/path"`
`address`	Y	Output	SFTP 服务器地址	`"localhost:22"`
`username`	Y	Output	用于认证的用户名	`"username"`
`password`	N	Output	用于用户名/密码认证的密码	`"password"`
`privateKey`	N	Output	用于公钥认证的私钥	"\|- —–BEGIN OPENSSH PRIVATE KEY—– ***************** —–END OPENSSH PRIVATE KEY—–"
`privateKeyPassphrase`	N	Output	用于公钥认证的私钥密码	`"passphrase"`
`hostPublicKey`	N	Output	用于主机验证的主机公钥	`"ecdsa-sha2-nistp256 *** root@openssh-server"`
`knownHostsFile`	N	Output	用于主机验证的已知主机文件	`"/path/file"`
`insecureIgnoreHostKey`	N	Output	允许跳过主机验证。默认为 `"false"`	`"true"`, `"false"`
`sequentialMode`	N	Output	用于指定单个 SFTP 连接内是否允许多个并发操作。将此设置为 true 可以防止可能干扰严格 SFTP 服务器的并发操作。默认为 `"false"`	`"true"`, `"false"`

Binding 支持

此组件支持输出 binding，包含以下操作：

create：创建文件
get：获取文件
list：列出文件
delete：删除文件

创建文件

要执行创建文件操作，请使用 POST 方法调用 SFTP binding，并附带以下 JSON 请求体：

{
  "operation": "create",
  "data": "<YOUR_BASE_64_CONTENT>",
  "metadata": {
    "fileName": "<filename>",
  }
}

示例

curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"fileName\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "fileName": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含以下 JSON：

{
   "fileName": "<filename>"
}

获取文件

要执行获取文件操作，请使用 POST 方法调用 SFTP binding，并附带以下 JSON 请求体：

{
  "operation": "get",
  "metadata": {
    "fileName": "<filename>"
  }
}

示例

curl -d '{ \"operation\": \"get\", \"metadata\": { \"fileName\": \"filename\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "fileName": "filename" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应体包含文件中存储的值。

列出文件

要执行列出文件操作，请使用 POST 方法调用 SFTP binding，并附带以下 JSON 请求体：

{
  "operation": "list"
}

如果您只想列出 rootPath 下某个特定目录中的文件，请在元数据中将相对目录名称指定为 fileName。

{
  "operation": "list",
  "metadata": {
    "fileName": "my/cool/directory"
  }
}

示例

curl -d '{ \"operation\": \"list\", \"metadata\": { \"fileName\": \"my/cool/directory\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "list", "metadata": { "fileName": "my/cool/directory" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

响应是一个文件名的 JSON 数组。

删除文件

要执行删除文件操作，请使用 POST 方法调用 SFTP binding，并附带以下 JSON 请求体：

{
  "operation": "delete",
  "metadata": {
    "fileName": "myfile"
  }
}

示例

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"fileName\": \"myfile\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "fileName": "myfile" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应

如果成功，返回 HTTP 204（No Content）和空响应体。

1.43 - SMTP 绑接规范

SMTP 绑接组件的详细文档

组件格式

要设置 SMTP 绑接，请创建类型为 bindings.smtp 的组件。有关如何创建和应用绑接配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: smtp
spec:
  type: bindings.smtp
  version: v1
  metadata:
  - name: host
    value: "smtp host"
  - name: port
    value: "smtp port"
  - name: user
    value: "username"
  - name: password
    value: "password"
  - name: skipTLSVerify
    value: true|false
  - name: emailFrom
    value: "sender@example.com"
  - name: emailTo
    value: "receiver@example.com"
  - name: emailCC
    value: "cc@example.com"
  - name: emailBCC
    value: "bcc@example.com"
  - name: subject
    value: "subject"
  - name: priority
    value: "[value 1-5]"

警告

上述示例配置中包含以纯文本形式呈现的用户名和密码。建议按照此处的说明使用 secret store 来管理密钥。

规范元数据字段

字段	必填	绑接支持	详情	示例
`host`	Y	Output	SMTP 服务器运行的主机地址	`"smtphost"`
`port`	Y	Output	SMTP 服务器监听的端口	`"9999"`
`user`	Y	Output	用于 SMTP 服务器身份验证的用户名	`"user"`
`password`	Y	Output	用户的密码	`"password"`
`skipTLSVerify`	N	Output	如果设置为 true，将不会验证 SMTP 服务器的 TLS 证书。默认值为 `"false"`	`"true"`, `"false"`
`emailFrom`	N	Output	如果设置，指定发件人的电子邮件地址。参见此处	`"me@example.com"`
`emailTo`	N	Output	如果设置，指定收件人的电子邮件地址。参见此处	`"me@example.com"`
`emailCc`	N	Output	如果设置，指定抄送的电子邮件地址。参见此处	`"me@example.com"`
`emailBcc`	N	Output	如果设置，指定密送的电子邮件地址。参见此处	`"me@example.com"`
`subject`	N	Output	如果设置，指定电子邮件的主题。参见此处	`"邮件主题"`
`priority`	N	Output	如果设置，指定电子邮件的优先级（X-Priority），从 1（最低）到 5（最高）（默认值：3）。参见此处	`"1"`

绑接支持

该组件支持输出绑接，具有以下操作：

create

示例请求

您可以在每个请求中指定以下可选元数据属性：

emailFrom
emailTo
emailCC
emailBCC
subject
priority

发送电子邮件时，配置和请求中的元数据会被合并。合并后的元数据集必须至少包含 emailFrom、emailTo 和 subject 字段。

emailTo、emailCC 和 emailBCC 字段可以包含多个以分号分隔的电子邮件地址。

示例：

{
  "operation": "create",
  "metadata": {
    "emailTo": "dapr-smtp-binding@example.net",
    "emailCC": "cc1@example.net; cc2@example.net",
    "subject": "电子邮件主题",
    "priority": "1"
  },
  "data": "测试 Dapr SMTP 绑接"
}

emailTo、emailCC 和 emailBCC 字段可以包含多个以分号分隔的电子邮件地址。

1.44 - Twilio SendGrid binding spec

Twilio SendGrid 绑定组件的详细文档

组件格式

要设置 Twilio SendGrid 绑定，需创建一个类型为 bindings.twilio.sendgrid 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: sendgrid
spec:
  type: bindings.twilio.sendgrid
  version: v1
  metadata:
  - name: emailFrom
    value: "testapp@dapr.io" # optional
  - name: emailFromName
    value: "test app" # optional
  - name: emailTo
    value: "dave@dapr.io" # optional
  - name: emailToName
    value: "dave" # optional
  - name: subject
    value: "Hello!" # optional
  - name: emailCc
    value: "jill@dapr.io" # optional
  - name: emailBcc
    value: "bob@dapr.io" # optional
  - name: dynamicTemplateId
    value: "d-123456789" # optional
  - name: dynamicTemplateData
    value: '{"customer":{"name":"John Smith"}}' # optional
  - name: apiKey
    value: "YOUR_API_KEY" # required, this is your SendGrid key

Warning

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体说明请参见此处。

规范元数据字段

字段	必填	绑定支持	详情	示例
`apiKey`	Y	Output	SendGrid API 密钥，应将其视为机密值	`"apikey"`
`emailFrom`	N	Output	如果设置，则指定电子邮件的"发件人"邮箱地址。仅允许单个邮箱地址。可选字段，参见下文	`"me@example.com"`
`emailFromName`	N	Output	如果设置，则指定电子邮件的"发件人"名称。可选字段，参见下文	`"me"`
`emailTo`	N	Output	如果设置，则指定电子邮件的"收件人"邮箱地址。仅允许单个邮箱地址。可选字段，参见下文	`"me@example.com"`
`emailToName`	N	Output	如果设置，则指定电子邮件的"收件人"名称。可选字段，参见下文	`"me"`
`emailCc`	N	Output	如果设置，则指定电子邮件的"抄送"邮箱地址。仅允许单个邮箱地址。可选字段，参见下文	`"me@example.com"`
`emailBcc`	N	Output	如果设置，则指定电子邮件的"密送"邮箱地址。仅允许单个邮箱地址。可选字段，参见下文	`"me@example.com"`
`subject`	N	Output	如果设置，则指定电子邮件的主题。可选字段，参见下文	`"subject of the email"`

绑定支持

该组件支持输出绑定，包含以下操作：

create

示例请求载荷

您也可以在输出绑定请求中指定任何可选的元数据属性（例如 emailFrom、emailTo、subject 等）。

{
  "operation": "create",
  "metadata": {
    "emailTo": "changeme@example.net",
    "subject": "An email from Dapr SendGrid binding"
  },
  "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
}

动态模板

如果使用动态模板，需要提供 dynamicTemplateId，然后使用 dynamicTemplateData：

{
  "operation": "create",
  "metadata": {
    "emailTo": "changeme@example.net",
    "subject": "An template email from Dapr SendGrid binding",
    "dynamicTemplateId": "d-123456789",
    "dynamicTemplateData": "{\"customer\":{\"name\":\"John Smith\"}}"
  }
}

1.45 - Twilio SMS 绑定规范

Twilio SMS 绑定组件的详细文档

组件格式

要设置 Twilio SMS 绑定，请创建一个类型为 bindings.twilio.sms 的组件。有关如何创建和应用绑定配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.twilio.sms
  version: v1
  metadata:
  - name: toNumber # required.
    value: "111-111-1111"
  - name: fromNumber # required.
    value: "222-222-2222"
  - name: accountSid # required.
    value: "*****************"
  - name: authToken # required.
    value: "*****************"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用 secret store 来存储密钥。

规范元数据字段

字段	必填	绑定支持	详情	示例
`toNumber`	Y	Output	接收短信的目标号码	`"111-111-1111"`
`fromNumber`	Y	Output	发送方电话号码	`"222-222-2222"`
`accountSid`	Y	Output	Twilio 账户 SID	`"account sid"`
`authToken`	Y	Output	Twilio 认证令牌	`"auth token"`

绑定支持

该组件支持以下操作的输出绑定：

create

1.46 - Wasm

WebAssembly 绑定组件的详细文档

概述

借助 WebAssembly，你可以安全地运行以其他语言编译的代码。运行时执行 WebAssembly 模块（Wasm），它们通常是带有 .wasm 扩展名的二进制文件。

Wasm 绑定允许你通过向其传递命令行参数或环境变量来调用编译为 Wasm 的程序，就像使用普通子进程一样。例如，即使 Dapr 是用 Go 编写的，并且运行在未安装 Python 的平台上，你也可以使用 Python 来满足调用请求！

Wasm 二进制文件必须是使用 WebAssembly 系统接口（WASI）编译的程序。该二进制文件可以是你编写的程序（例如 Go），或者是你用于运行内联脚本的解释器（例如 Python）。

你至少需要指定一个使用规范 WASI 版本 wasi_snapshot_preview1（也称为 wasip1）编译的 Wasm 二进制文件，通常简称为 wasi。

注意： 如果使用 Go 1.21+ 编译，这是 GOOS=wasip1 GOARCH=wasm。在 TinyGo、Rust 和 Zig 中，这是目标 wasm32-wasi。

你也可以重用现有的二进制文件。例如，Wasm Language Runtimes 分发了已编译为 WASI 的解释器（包括 PHP、Python 和 Ruby）。

Wasm 二进制文件从 URL 加载。例如，URL file://rewrite.wasm 从进程的当前目录加载 rewrite.wasm。在 Kubernetes 上，请参阅如何：将 Pod 卷挂载到 Dapr 边车以配置可以包含 Wasm 二进制文件的文件系统挂载。也可以从远程 URL 获取 Wasm 二进制文件。在这种情况下，URL 必须精确指向一个 Wasm 二进制文件。例如：

http://example.com/rewrite.wasm，或
https://example.com/rewrite.wasm。

Dapr 使用 wazero 来运行这些二进制文件，因为它没有依赖项。这使得除了 Dapr 本身之外，无需安装任何东西即可使用 WebAssembly。

Wasm 输出绑定支持使用 wasi-http 规范进行 HTTP 客户端调用。你可以在以下位置找到多种语言进行 HTTP 调用的示例代码：

注意

如果你只是想进行 HTTP 调用，使用服务调用 API会更简单。但是，如果你需要添加自己的逻辑——例如，过滤或调用多个 API 端点——请考虑使用 Wasm。

组件格式

要配置 Wasm 绑定，请创建类型为 bindings.wasm 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: wasm
spec:
  type: bindings.wasm
  version: v1
  metadata:
    - name: url
      value: "file://uppercase.wasm"

规范元数据字段

字段	详情	必填	示例
`url`	包含要实例化的 Wasm 二进制文件的资源 URL。支持的协议包括 `file://`、`http://` 和 `https://`。`file://` URL 的路径相对于 Dapr 进程，除非它以 `/` 开头。	true	`file://hello.wasm`, `https://example.com/hello.wasm`

绑定支持

此组件支持 输出绑定，具有以下操作：

execute

示例请求

data 字段（如果存在）将是程序的 STDIN。你可以选择在每个请求中传递元数据属性：

args 任何 CLI 参数，以逗号分隔。这不包括程序名称。

例如，考虑将 url 绑定到 Ruby 解释器，例如来自 webassembly-language-runtimes：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: wasm
spec:
  type: bindings.wasm
  version: v1
  metadata:
  - name: url
    value: "https://github.com/vmware-labs/webassembly-language-runtimes/releases/download/ruby%2F3.2.0%2B20230215-1349da9/ruby-3.2.0-slim.wasm"

假设你想在端口 3500 上启动 Dapr 并使用 Wasm 绑定，你可以运行：

$ dapr run --app-id wasm --dapr-http-port 3500 --resources-path components

以下请求返回 Hello "salaboy"：

$ curl -X POST http://localhost:3500/v1.0/bindings/wasm -d'
{
  "operation": "execute",
  "metadata": {
    "args": "-ne,print \"Hello \"; print"
  },
  "data": "salaboy"
}'

1.47 - Zeebe command binding 规范

Zeebe command binding 组件的详细文档

组件格式

要设置 Zeebe command binding，请创建类型为 bindings.zeebe.command 的组件。请参阅此指南了解如何创建和应用 binding 配置。

请参阅此处获取 Zeebe 文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.zeebe.command
  version: v1
  metadata:
  - name: gatewayAddr
    value: "<host>:<port>"
  - name: gatewayKeepAlive
    value: "45s"
  - name: usePlainTextConnection
    value: "true"
  - name: caCertificatePath
    value: "/path/to/ca-cert"

规范元数据字段

字段	必填	Binding 支持	详情	示例
`gatewayAddr`	Y	输出	Zeebe gateway 地址	`"localhost:26500"`
`gatewayKeepAlive`	N	输出	设置向 gateway 发送保活消息的频率。默认为 45 秒	`"45s"`
`usePlainTextConnection`	N	输出	是否使用纯文本连接	`"true"`, `"false"`
`caCertificatePath`	N	输出	CA 证书的路径	`"/path/to/ca-cert"`

Binding 支持

此组件支持输出 binding，包含以下操作：

topology
deploy-process
deploy-resource
create-instance
cancel-instance
set-variables
resolve-incident
publish-message
activate-jobs
complete-job
fail-job
update-job-retries
throw-error

输出 binding

Zeebe 在底层使用了 gRPC，作为我们在此 binding 中使用的 Zeebe 客户端的基础。请参阅 gRPC API 参考以获取更多信息。

topology

topology 操作获取 gateway 所属集群的当前拓扑结构。

要执行 topology 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {},
  "operation": "topology"
}

响应

binding 返回以下 JSON 响应：

{
  "brokers": [
    {
      "nodeId": null,
      "host": "172.18.0.5",
      "port": 26501,
      "partitions": [
        {
          "partitionId": 1,
          "role": null,
          "health": null
        }
      ],
      "version": "0.26.0"
    }
  ],
  "clusterSize": 1,
  "partitionsCount": 1,
  "replicationFactor": 1,
  "gatewayVersion": "0.26.0"
}

响应值为：

brokers - 此集群中的 broker 列表
- nodeId - broker 的唯一（在集群内）节点 ID
- host - broker 的主机名
- port - broker 的端口
- port - broker 的端口
- partitions - 在此 broker 上管理或复制的分区列表
  - partitionId - 此分区的唯一 ID
  - role - broker 在此分区中的角色
  - health - 此分区的健康状态
- version - broker 版本
clusterSize - 集群中有多少节点
partitionsCount - 集群中分布了多少分区
replicationFactor - 此集群配置的复制因子
gatewayVersion - gateway 版本

deploy-process

‘deploy-resource’ 的已弃用别名。

deploy-resource

deploy-resource 操作向 Zeebe 部署单个资源。资源可以是流程（BPMN）或决策和决策需求（DMN）。

要执行 deploy-resource 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": "YOUR_FILE_CONTENT",
  "metadata": {
    "fileName": "products-process.bpmn"
  },
  "operation": "deploy-resource"
}

元数据参数为：

fileName - 资源文件的名称

响应

binding 返回以下 JSON 响应：

{
  "key": 2251799813685252,
  "deployments": [
    {
      "Metadata": {
        "Process": {
          "bpmnProcessId": "products-process",
          "version": 2,
          "processDefinitionKey": 2251799813685251,
          "resourceName": "products-process.bpmn"
        }
      }
    }
  ]
}

{
  "key": 2251799813685253,
  "deployments": [
    {
      "Metadata": {
        "Decision": {
          "dmnDecisionId": "products-approval",
          "dmnDecisionName": "Products approval",
          "version": 1,
          "decisionKey": 2251799813685252,
          "dmnDecisionRequirementsId": "Definitions_0c98xne",
          "decisionRequirementsKey": 2251799813685251
        }
      }
    },
    {
      "Metadata": {
        "DecisionRequirements": {
          "dmnDecisionRequirementsId": "Definitions_0c98xne",
          "dmnDecisionRequirementsName": "DRD",
          "version": 1,
          "decisionRequirementsKey": 2251799813685251,
          "resourceName": "products-approval.dmn"
        }
      }
    }
  ]
}

响应值为：

key - 标识部署的唯一键
deployments - 已部署资源的列表，例如流程
- metadata - 部署元数据，每个部署只有一个元数据
  - process- 已部署流程的元数据
    - bpmnProcessId - bpmn 流程 ID，在部署期间解析；与版本一起形成特定流程定义的唯一标识符
    - version - 分配的流程版本
    - processDefinitionKey - 分配的键，作为此流程的唯一标识符
    - resourceName - 解析此流程所用的资源名称
  - decision - 已部署决策的元数据
    - dmnDecisionId - dmn 决策 ID，在部署期间解析；与版本一起形成特定决策的唯一标识符
    - dmnDecisionName - 决策的 dmn 名称，在部署期间解析
    - version - 分配的决策版本
    - decisionKey - 分配的决策键，作为此决策的唯一标识符
    - dmnDecisionRequirementsId - 此决策所属的决策需求图的 dmn ID，在部署期间解析
    - decisionRequirementsKey - 此决策所属的决策需求图的分配键
  - decisionRequirements - 已部署决策需求的元数据
    - dmnDecisionRequirementsId - dmn 决策需求 ID，在部署期间解析；与版本一起形成特定决策的唯一标识符
    - dmnDecisionRequirementsName - 决策需求的 dmn 名称，在部署期间解析
    - version - 分配的决策需求版本
    - decisionRequirementsKey - 分配的决策需求键，作为此决策需求的唯一标识符
    - resourceName - 解析此决策需求所用的资源名称

create-instance

create-instance 操作创建并启动指定流程的实例。用于创建实例的流程定义可以使用其唯一键（由 deploy-process 操作返回）指定，也可以使用 BPMN 流程 ID 和版本指定。

请注意，只有具有无启动事件的流程才能通过此命令启动。

通常，流程创建和执行是解耦的。这意味着该命令创建一个新的流程实例，并立即返回流程实例 ID 作为响应。流程的执行在发送响应之后进行。然而，有些用例需要在流程执行完成时收集其结果。通过定义 withResult 属性，该命令可以"同步"执行流程并通过一组变量接收结果。响应在流程执行完成时发送。

有关更多信息，请访问官方文档。

要执行 create-instance 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "bpmnProcessId": "products-process",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "create-instance"
}

{
  "data": {
    "processDefinitionKey": 2251799813685895,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "create-instance"
}

{
  "data": {
    "bpmnProcessId": "products-process",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    },
    "withResult": true,
    "requestTimeout": "30s",
    "fetchVariables": ["productId"]
  },
  "operation": "create-instance"
}

数据参数为：

bpmnProcessId - 要实例化的流程定义的 BPMN 流程 ID
processDefinitionKey - 标识要实例化的流程定义的唯一键
version - （可选，默认：最新版本）要实例化的流程的版本
variables - （可选）JSON 文档，将为流程实例的根变量作用域实例化变量；它必须是 JSON 对象，因为变量将以键值方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是数组而不是对象
withResult - （可选，默认：false）如果设置为 true，流程将被同步实例化和执行
requestTimeout - （可选，仅在 withResult=true 时使用）超时时间，如果流程在 requestTimeout 之前未完成，请求将被关闭。如果 requestTimeout = 0，则使用 gateway 中配置的通用 requestTimeout
fetchVariables - （可选，仅在 withResult=true 时使用）要包含在响应的 variables 属性中的变量名称列表。如果为空，将返回根作用域中的所有可见变量

响应

binding 返回以下 JSON 响应：

{
  "processDefinitionKey": 2251799813685895,
  "bpmnProcessId": "products-process",
  "version": 3,
  "processInstanceKey": 2251799813687851,
  "variables": "{\"productId\":\"some-product-id\"}"
}

响应值为：

processDefinitionKey - 用于创建流程实例的流程定义的键
bpmnProcessId - 用于创建流程实例的流程定义的 BPMN 流程 ID
version - 用于创建流程实例的流程定义的版本
processInstanceKey - 创建的流程实例的唯一标识符
variables - （可选，仅在请求中使用了 withResult=true）由根作用域中的可见变量组成的 JSON 文档；作为序列化的 JSON 文档返回

cancel-instance

cancel-instance 操作取消正在运行的流程实例。

要执行 cancel-instance 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "processInstanceKey": 2251799813687851
  },
  "operation": "cancel-instance"
}

数据参数为：

processInstanceKey - 流程实例键

响应

binding 不返回响应正文。

set-variables

set-variables 操作为元素实例（例如流程实例、流元素实例）创建或更新变量。

要执行 set-variables 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "elementInstanceKey": 2251799813687880,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "set-variables"
}

数据参数为：

elementInstanceKey - 特定元素的唯一标识符；可以是流程实例键（在实例创建时获得），也可以是给定元素，例如服务任务（请参阅 job 消息上的 elementInstanceKey）
local - （可选，默认：false）如果为 true，变量将严格合并到本地作用域（由 elementInstanceKey 指示）；这意味着变量不会传播到上层作用域。例如，假设我们有两个作用域 ‘1’ 和 ‘2’，每个都有有效变量：1 => { "foo" : 2 }，2 => { "bar" : 1 }。如果我们发送更新请求，elementInstanceKey = 2，variables { "foo" : 5 }，并且 local 为 true，那么作用域 1 将保持不变，作用域 2 现在将是 { "bar" : 1, "foo" 5 }。但是如果 local 为 false，那么作用域 1 将是 { "foo": 5 }，作用域 2 将是 { "bar" : 1 }
variables - JSON 序列化文档，将变量描述为键值对；文档的根必须是对象

响应

binding 返回以下 JSON 响应：

{
  "key": 2251799813687896
}

响应值为：

key - set variables 命令的唯一键

resolve-incident

resolve-incident 操作解决事件。

要执行 resolve-incident 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "incidentKey": 2251799813686123
  },
  "operation": "resolve-incident"
}

数据参数为：

incidentKey - 要解决的事件的唯一 ID

响应

binding 不返回响应正文。

publish-message

publish-message 操作发布单个消息。消息将发布到从其关联键计算出的特定分区。

要执行 publish-message 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "messageName": "product-message",
    "correlationKey": "2",
    "timeToLive": "1m",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    },
  },  
  "operation": "publish-message"
}

数据参数为：

messageName - 消息的名称
correlationKey - （可选）消息的关联键
timeToLive - （可选）消息应在 broker 上缓冲多长时间
messageId - （可选）消息的唯一 ID；可以省略。仅用于确保只有一条具有给定 ID 的消息会被发布（在其生命周期内）
variables - （可选）消息变量作为 JSON 文档；要有效，文档的根必须是对象，例如 { “a”: “foo” }。[ “foo” ] 将无效

响应

binding 返回以下 JSON 响应：

{
  "key": 2251799813688225
}

响应值为：

key - 已发布的消息的唯一 ID

activate-jobs

activate-jobs 操作以轮询方式遍历所有已知分区，激活达到所请求最大数量的作业，并在激活时将其流式传输回客户端。

要执行 activate-jobs 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "jobType": "fetch-products",
    "maxJobsToActivate": 5,
    "timeout": "5m",
    "workerName": "products-worker",
    "fetchVariables": [
      "productId",
      "productName",
      "productKey"
    ],
    "requestTimeout": "30s"
  },
  "operation": "activate-jobs"
}

数据参数为：

jobType - 作业类型，在 BPMN 流程中定义（例如 <zeebe:taskDefinition type="fetch-products" />）
maxJobsToActivate - 此请求要激活的最大作业数
timeout - （可选，默认：5 分钟）在此调用后返回的作业在超时之前不会被另一调用激活
workerName - （可选，默认：default）激活作业的工作程序名称，主要用于日志记录目的
fetchVariables - （可选）要作为作业变量获取的变量列表；如果为空，将返回激活时作业作用域的所有可见变量
requestTimeout - （可选）请求将在至少激活一个作业时或 requestTimeout 之后完成。如果 requestTimeout = 0，则使用默认超时。如果 requestTimeout < 0，则禁用长轮询，请求立即完成，即使没有激活作业

响应

binding 返回以下 JSON 响应：

[
  {
    "key": 2251799813685267,
    "type": "fetch-products",
    "processInstanceKey": 2251799813685260,
    "bpmnProcessId": "products",
    "processDefinitionVersion": 1,
    "processDefinitionKey": 2251799813685249,
    "elementId": "Activity_test",
    "elementInstanceKey": 2251799813685266,
    "customHeaders": "{\"process-header-1\":\"1\",\"process-header-2\":\"2\"}",
    "worker": "test", 
    "retries": 1,
    "deadline": 1694091934039,
    "variables":"{\"productId\":\"some-product-id\"}"
  }
]

响应值为：

key - 键，作业的唯一标识符
type - 作业类型（应与请求的类型匹配）
processInstanceKey - 作业的流程实例键
bpmnProcessId - 作业流程定义的 bpmn 流程 ID
processDefinitionVersion - 作业流程定义的版本
processDefinitionKey - 作业流程定义的键
elementId - 关联的任务元素 ID
elementInstanceKey - 标识关联任务的唯一键，在流程实例作用域内唯一
customHeaders - 在建模期间定义的一组自定义标头；作为序列化的 JSON 文档返回
worker - 激活此作业的工作程序的名称
retries - 此作业剩余的重试次数（应始终为正数）
deadline - 作业可以再次激活的时间，作为 UNIX epoch 时间戳发送
variables - 在激活时计算，由任务作用域的所有可见变量组成；作为序列化的 JSON 文档返回

complete-job

complete-job 操作使用给定的负载完成作业，从而允许完成关联的服务任务。

要执行 complete-job 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "jobKey": 2251799813686172,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "complete-job"
}

数据参数为：

jobKey - 唯一作业标识符，从 activate jobs 响应中获得
variables - （可选）表示当前任务作用域中变量的 JSON 文档

响应

binding 不返回响应正文。

fail-job

fail-job 操作将作业标记为失败；如果 retries 参数为正数，则作业将可以立即再次激活，工作程序可以再次尝试处理它。但是如果为零或负数，将引发事件，使用给定的 errorMessage 进行标记，并且在事件解决之前作业将无法激活。

要执行 fail-job 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "jobKey": 2251799813685739,
    "retries": 5,
    "errorMessage": "some error occurred",
    "retryBackOff": "30s",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "fail-job"
}

数据参数为：

jobKey - 唯一作业标识符，在激活作业时获得
retries - 作业应剩余的重试次数
errorMessage - （可选）描述作业失败原因的消息；如果作业耗尽重试次数并引发事件，这特别有用，因为此消息可以帮助解释引发事件的原因
retryBackOff - （可选）下次重试的退避超时
variables - （可选）JSON 文档，将在作业关联的任务的本地作用域实例化变量；它必须是 JSON 对象，因为变量将以键值方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是数组而不是对象

响应

binding 不返回响应正文。

update-job-retries

update-job-retries 操作更新作业的剩余重试次数。这对于已用尽重试次数的作业最有用，前提是根本问题已解决。

要执行 update-job-retries 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "jobKey": 2251799813686172,
    "retries": 10
  },
  "operation": "update-job-retries"
}

数据参数为：

jobKey - 唯一作业标识符，通过 activate-jobs 操作获得
retries - 作业的新重试次数；必须为正数

响应

binding 不返回响应正文。

throw-error

throw-error 操作抛出错误以指示在处理作业时发生了业务错误。错误由错误代码标识，并由流程中具有相同错误代码的错误捕获事件处理。

要执行 throw-error 操作，请使用 POST 方法调用 Zeebe command binding，并使用以下 JSON 请求体：

{
  "data": {
    "jobKey": 2251799813686172,
    "errorCode": "product-fetch-error",
    "errorMessage": "The product could not be fetched",
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "throw-error"
}

数据参数为：

jobKey - 唯一作业标识符，在激活作业时获得
errorCode - 将与错误捕获事件匹配的错误代码
errorMessage - （可选）提供其他上下文的错误消息
variables - （可选）JSON 文档，将在作业关联的任务的本地作用域实例化变量；它必须是 JSON 对象，因为变量将以键值方式映射。例如，{ “a”: 1, “b”: 2 } 将创建两个变量，分别命名为 “a” 和 “b”，并具有其关联值。[{ “a”: 1, “b”: 2 }] 将不是有效参数，因为 JSON 文档的根是数组而不是对象

响应

binding 不返回响应正文。

1.48 - Zeebe JobWorker 绑定规范

Zeebe JobWorker 绑定组件的详细文档

组件格式

要设置 Zeebe JobWorker 绑定，需创建一个类型为 bindings.zeebe.jobworker 的组件。请参阅此指南了解如何创建和应用绑定配置。

有关 Zeebe JobWorker 的文档，请参阅此文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.zeebe.jobworker
  version: v1
  metadata:
  - name: gatewayAddr
    value: "<host>:<port>"
  - name: gatewayKeepAlive
    value: "45s"
  - name: usePlainTextConnection
    value: "true"
  - name: caCertificatePath
    value: "/path/to/ca-cert"
  - name: workerName
    value: "products-worker"
  - name: workerTimeout
    value: "5m"
  - name: requestTimeout
    value: "15s"
  - name: jobType
    value: "fetch-products"
  - name: maxJobsActive
    value: "32"
  - name: concurrency
    value: "4"
  - name: pollInterval
    value: "100ms"
  - name: pollThreshold
    value: "0.3"
  - name: fetchVariables
    value: "productId, productName, productKey"
  - name: autocomplete
    value: "true"
  - name: retryBackOff
    value: "30s"
  - name: direction
    value: "input"

规范元数据字段

字段	必填	绑定支持	详情	示例
`gatewayAddr`	Y	Input	Zeebe 网关地址	`"localhost:26500"`
`gatewayKeepAlive`	N	Input	设置向网关发送保活消息的频率。默认为 45 秒	`"45s"`
`usePlainTextConnection`	N	Input	是否使用纯文本连接	`"true"`, `"false"`
`caCertificatePath`	N	Input	CA 证书的路径	`"/path/to/ca-cert"`
`workerName`	N	Input	激活任务的 worker 名称，主要用于日志记录目的	`"products-worker"`
`workerTimeout`	N	Input	在此调用后返回的任务在超时到达前不会被另一个调用激活；默认为 5 分钟	`"5m"`
`requestTimeout`	N	Input	当至少有一个任务被激活或在 requestTimeout 之后，请求将完成。如果 requestTimeout = 0，则使用默认超时。如果 requestTimeout < 0，则禁用长轮询，即使没有任务被激活，请求也会立即完成。默认为 10 秒	`"30s"`
`jobType`	Y	Input	任务类型，在 BPMN 流程中定义（例如 `<zeebe:taskDefinition type="fetch-products" />`)	`"fetch-products"`
`maxJobsActive`	N	Input	设置此 worker 同时激活的最大任务数量。默认为 32	`"32"`
`concurrency`	N	Input	完成任务的最大并发 spawned goroutine 数量。默认为 4	`"4"`
`pollInterval`	N	Input	设置轮询新任务的最大间隔。默认为 100 毫秒	`"100ms"`
`pollThreshold`	N	Input	设置轮询新任务前缓冲激活任务的阈值，即 threshold * maxJobsActive。默认为 0.3	`"0.3"`
`fetchVariables`	N	Input	要获取作为任务变量的变量列表；如果为空，则将返回激活时任务范围内所有可见的变量	`"productId"`, `"productName"`, `"productKey"`
`autocomplete`	N	Input	指示任务是否应自动完成。如果未设置，默认情况下所有任务都将自动完成。如果 worker 应通过业务错误或事件手动完成或使任务失败，则禁用它	`"true"`, `"false"`
`retryBackOff`	N	Input	任务失败时下次重试的退避超时时间	`15s`
`direction`	N	Input	绑定的方向	`"input"`

绑定支持

此组件支持输入绑定接口。

输入绑定

变量

Zeebe 流程引擎将流程状态以及流程变量作为可传递的内容处理，这些变量可以在流程实例化时传递，也可以在流程执行期间更新或创建。通过在 fetchVariables 元数据字段中将变量名称定义为逗号分隔的列表，这些变量可以传递给已注册的 job worker。然后，流程引擎会将这些变量及其当前值传递给 job worker 实现。

如果绑定注册了三个变量 productId、productName 和 productKey，则 worker 将使用以下 JSON 主体调用：

{
  "productId": "some-product-id",
  "productName": "some-product-name",
  "productKey": "some-product-key"
}

注意：如果不传递 fetchVariables 元数据字段，所有流程变量都将传递给 worker。

标头

Zeebe 流程引擎能够将自定义任务标头传递给 job worker。这些标头可以为每个服务任务定义。任务标头将由绑定作为元数据（HTTP 标头）传递给 job worker。

绑定还将传递以下与任务相关的变量作为元数据。值将作为字符串传递。该表还包含原始数据类型，以便可以将其转换回 worker 使用的编程语言中的等效数据类型。

元数据	数据类型	描述
X-Zeebe-Job-Key	int64	任务的键，是任务的唯一标识符
X-Zeebe-Job-Type	string	任务的类型（应与请求的类型匹配）
X-Zeebe-Process-Instance-Key	int64	任务的流程实例键
X-Zeebe-Bpmn-Process-Id	string	任务流程定义的 bpmn 流程 ID
X-Zeebe-Process-Definition-Version	int32	任务流程定义的版本
X-Zeebe-Process-Definition-Key	int64	任务流程定义的键
X-Zeebe-Element-Id	string	关联的任务元素 ID
X-Zeebe-Element-Instance-Key	int64	识别关联任务的唯一键，在流程实例范围内唯一
X-Zeebe-Worker	string	激活此任务的 worker 名称
X-Zeebe-Retries	int32	此任务剩余的重试次数（应始终为正数）
X-Zeebe-Deadline	int64	任务可以再次激活的时间，作为 UNIX epoch 时间戳发送
X-Zeebe-Autocomplete	bool	在绑定元数据中定义的自动完成状态

1.49 - 阿里云对象存储服务绑定规范

阿里云对象存储绑定组件的详细文档

组件格式

要设置阿里云对象存储绑定，需创建一个类型为 bindings.alicloud.oss 的组件。有关如何创建和应用 secretstore 配置，请参阅此指南。有关如何检索和使用 Dapr 组件的密钥，请参阅引用密钥指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: alicloudobjectstorage
spec:
  type: bindings.alicloud.oss
  version: v1
  metadata:
  - name: endpoint
    value: "[endpoint]"
  - name: accessKeyID
    value: "[key-id]"
  - name: accessKey
    value: "[access-key]"
  - name: bucket
    value: "[bucket]"

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体说明请参见此处。

规范元数据字段

字段	必填	绑定支持	详情	示例
`endpoint`	Y	Output	阿里云 OSS 端点。	https://oss-cn-hangzhou.aliyuncs.com
`accessKeyID`	Y	Output	访问密钥 ID 凭据。
`accessKey`	Y	Output	访问密钥凭据。
`bucket`	Y	Output	存储桶的名称。

绑定支持

此组件支持输出绑定，支持以下操作：

create：创建对象

Create object

要执行创建对象操作，请使用 POST 方法调用绑定，并传入以下 JSON 请求体：

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

注意

默认情况下，会自动生成一个随机 UUID 作为对象键。有关如何为对象设置键，请参阅下面的元数据支持说明。

示例

保存到随机生成的 UUID 文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

保存到指定文件

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"key\": \"my-key\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "key": "my-key" } }' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

注意

在 Windows CMD 中需要对 " 字符进行转义。

元数据信息

对象键

默认情况下，阿里云 OSS 输出绑定会自动生成一个 UUID 作为对象键。您可以使用以下元数据设置键：

{
    "data": "file content",
    "metadata": {
        "key": "my-key"
    },
    "operation": "create"
}

1.50 - 阿里云日志服务绑定规范

阿里云日志服务绑定组件的详细文档

组件格式

要设置阿里云 SLS 绑定，请创建类型为 bindings.alicloud.sls 的组件。有关如何创建和应用绑定配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: alicloud.sls
spec:
  type: bindings.alicloud.sls
  version: v1
  metadata:
  - name: AccessKeyID
    value: "[accessKey-id]"
  - name: AccessKeySecret
    value: "[accessKey-secret]"
  - name: Endpoint
    value: "[endpoint]"

规范元数据字段

字段	必填	绑定支持	详情
`AccessKeyID`	Y	Output	Access key ID 凭证。
`AccessKeySecret`	Y	Output	Access key 凭证密钥
`Endpoint`	Y	Output	阿里云 SLS 端点。

绑定支持

此组件支持输出绑定，具有以下操作：

create：创建对象

请求格式

要执行日志存储操作，请使用 POST 方法调用绑定并传入以下 JSON 请求体：

{
    "metadata":{
        "project":"your-sls-project-name",
        "logstore":"your-sls-logstore-name",
        "topic":"your-sls-topic-name",
        "source":"your-sls-source"
    },
    "data":{
        "custome-log-filed":"any other log info"
    },
    "operation":"create"
}

注意

注意，“project”、“logstore”、“topic” 和 “source” 属性的值应在元数据属性中提供。

示例

curl -X POST -H "Content-Type: application/json" -d "{\"metadata\":{\"project\":\"project-name\",\"logstore\":\"logstore-name\",\"topic\":\"topic-name\",\"source\":\"source-name\"},\"data\":{\"log-filed\":\"log info\"}" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -X POST -H "Content-Type: application/json" -d '{"metadata":{"project":"project-name","logstore":"logstore-name","topic":"topic-name","source":"source-name"},"data":{"log-filed":"log info"}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

响应格式

由于阿里云 SLS producer API 是异步的，此绑定没有响应（没有回调接口来接收成功或失败的响应，仅在控制台日志中记录任何原因的失败）。

2 - 配置存储组件规格

与 Dapr 对接的受支持的配置存储

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Status	Component version	Since runtime version
Kubernetes ConfigMap	Alpha	v1	1.18
PostgreSQL	Stable	v1	1.11
Redis	Stable	v1	1.11

Microsoft Azure

Component	Status	Component version	Since runtime version
Azure App Configuration	Alpha	v1	1.9

2.1 - Azure App Configuration

Azure App Configuration 配置存储组件的详细信息

组件格式

要设置 Azure App Configuration 配置存储，需创建一个类型为 configuration.azure.appconfig 的组件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: configuration.azure.appconfig
  version: v1
  metadata:
  - name: host # 当使用 Azure 身份验证机制时应使用 host。
    value: <HOST>
  - name: connectionString # 当使用 Azure 身份验证机制时不应使用 connectionString。
    value: <CONNECTIONSTRING>
  - name: maxRetries
    value: # 可选
  - name: retryDelay
    value: # 可选
  - name: maxRetryDelay
    value: # 可选
  - name: azureEnvironment # 可选，默认为 AZUREPUBLICCLOUD
    value: "AZUREPUBLICCLOUD"
  # 请参阅下方的身份验证部分以了解所有选项
  - name: azureTenantId # 可选
    value: "[your_service_principal_tenant_id]"
  - name: azureClientId # 可选
    value: "[your_service_principal_app_id]"
  - name: azureCertificateFile # 可选
    value : "[pfx_certificate_file_fully_qualified_local_path]"
  - name: subscribePollInterval # 可选
    value: #可选 [期望格式示例 - 24h]

Warning

上述示例使用纯文本字符串表示密钥。建议使用密钥存储来管理密钥，详见此处。

规范元数据字段

Field	Required	Details	Example
connectionString	Y*	Azure App Configuration 实例的连接字符串。无默认值。可以是 `secretKeyRef` 以使用密钥引用。与 host 字段互斥。使用 Azure 身份验证时不使用	`Endpoint=https://foo.azconfig.io;Id=osOX-l9-s0:sig;Secret=00000000000000000000000000000000000000000000`
host	N*	Azure App Configuration 实例的终端节点。无默认值。与 connectionString 字段互斥。使用 Azure 身份验证时使用	`https://dapr.azconfig.io`
maxRetries	N	放弃前的最大重试次数。默认为 `3`	`5`, `10`
retryDelay	N	重试延迟指定在重试操作前的初始延迟量。延迟随每次重试呈指数级增长，直到最大重试延迟指定的最大值。默认为 `4` 秒；`"-1"` 禁用重试间的延迟。	`4s`
maxRetryDelay	N	最大重试延迟指定重试操作前允许的最大延迟。该值通常应大于或等于重试延迟中指定的值。默认为 `120` 秒；`"-1"` 禁用该限制	`120s`
subscribePollInterval	N	订阅轮询间隔指定以纳秒为单位轮询订阅键是否有任何更改的轮询间隔。未来将更新为 Go Time 格式。默认轮询间隔为 `24` 小时。	`24h`

注意：必须指定 host 或 connectionString 其中之一。

使用连接字符串进行身份验证

使用连接字符串访问 App Configuration 实例，该字符串可在 Azure 门户中获取。由于连接字符串包含凭据信息，应将其视为密钥并使用密钥存储。

使用 Microsoft Entra ID 进行身份验证

Azure App Configuration 配置存储组件还支持通过 Microsoft Entra ID 进行身份验证。在启用此组件之前：

阅读向 Azure 进行身份验证文档。
创建 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为你的应用程序平台创建托管标识。

设置 Azure App Configuration

你需要一个 Azure 订阅来设置 Azure App Configuration。

启动 Azure App Configuration 创建流程。必要时登录。
点击创建开始部署你的 Azure App Configuration 实例。
实例创建完成后，获取主机（终端节点）或连接字符串：
- 对于主机：导航至资源的概览并复制终端节点。
- 对于连接字符串：导航至设置 > 访问密钥并复制你的连接字符串。
将你的主机或连接字符串添加到 Dapr 可应用的 azappconfig.yaml 文件中。
将 host 键设置为 [终端节点]或将 connectionString 键设置为你之前保存的值。
Note
在生产级应用程序中，遵循密钥管理说明以安全地管理你的密钥。

Azure App Configuration 请求元数据

在 Azure App Configuration 中，你可以使用标签为同一键定义不同的值。例如，你可以为开发环境和生产环境定义一个具有不同值的单个键。你可以指定在连接到 App Configuration 时加载哪个标签

Azure App Configuration 存储组件支持以下可选的 label 元数据属性：

label：要检索的配置的标签。如果不存在，配置存储将返回指定键和空标签的配置。

标签可以通过请求 URL 中的查询参数来填充：

GET curl http://localhost:<daprPort>/v1.0/configuration/<store-name>?key=<key name>&metadata.label=<label value>

2.2 - PostgreSQL

PostgreSQL 配置存储组件的详细信息

组件格式

要设置 PostgreSQL 配置存储，请创建类型为 configuration.postgresql 的组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: configuration.postgresql
  version: v1
  metadata:
    # Connection string
    - name: connectionString
      value: "host=localhost user=postgres password=example port=5432 connect_timeout=10 database=config"
    # Name of the table which holds configuration information
    - name: table
      value: "[your_configuration_table_name]" 
    # Individual connection parameters - can be used instead to override connectionString parameters
    #- name: host
    #  value: "localhost"
    #- name: hostaddr
    #  value: "127.0.0.1"
    #- name: port
    #  value: "5432"
    #- name: database
    #  value: "my_db"
    #- name: user
    #  value: "postgres"
    #- name: password
    #  value: "example"
    #- name: sslRootCert
    #  value: "/path/to/ca.crt"
    # Timeout for database operations, in seconds (optional)
    #- name: timeoutInSeconds
    #  value: 20
    # Name of the table where to store the state (optional)
    #- name: tableName
    #  value: "state"
    # Name of the table where to store metadata used by Dapr (optional)
    #- name: metadataTableName
    #  value: "dapr_metadata"
    # Cleanup interval in seconds, to remove expired rows (optional)
    #- name: cleanupIntervalInSeconds
    #  value: 3600
    # Maximum number of connections pooled by this component (optional)
    #- name: maxConns
    #  value: 0
    # Max idle time for connections before they're closed (optional)
    #- name: connectionMaxIdleTime
    #  value: 0
    # Controls the default mode for executing queries. (optional)
    #- name: queryExecMode
    #  value: ""
    # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional)
    #- name: actorStateStore
    #  value: "true"

警告

上述示例使用纯文本字符串作为密钥。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

使用连接字符串进行身份验证

使用 PostgreSQL 连接字符串进行身份验证时，以下元数据选项是必需的。

字段	必需	详情	示例
`connectionString`	Y	PostgreSQL 数据库的连接字符串。有关如何定义连接字符串的信息，请参阅 PostgreSQL 数据库连接文档。	`"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`

使用单独的连接参数进行身份验证

除了使用连接字符串外，您还可以选择指定单独的连接参数。这些参数等同于标准 PostgreSQL 连接参数。

字段	必需	详情	示例
`host`	Y	PostgreSQL 服务器的主机名或 IP 地址	`"localhost"`
`hostaddr`	N	PostgreSQL 服务器的 IP 地址（host 的替代选项）	`"127.0.0.1"`
`port`	Y	PostgreSQL 服务器的端口号	`"5432"`
`database`	Y	要连接的数据库名称	`"my_db"`
`user`	Y	用于连接的 PostgreSQL 用户	`"postgres"`
`password`	Y	PostgreSQL 用户的密码	`"example"`
`sslRootCert`	N	SSL 根证书文件的路径	`"/path/to/ca.crt"`

注意

使用单独的连接参数时，这些参数将覆盖 connectionString 中存在的参数。

使用 Microsoft Entra ID 进行身份验证

字段	必需	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以使组件能够从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含用户，该用户对应于在 PostgreSQL 内部创建的、映射到 Microsoft Entra ID 标识的用户名称；这通常是相应主体的名称（例如 Microsoft Entra ID 应用程序的名称）。此连接字符串不应包含任何密码。	`"host=mydb.postgres.database.azure.com user=myapplication port=5432 database=my_db sslmode=require"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-…"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-…"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

支持使用 AWS IAM 对所有版本的 PostgreSQL 类型组件进行身份验证。连接字符串中指定的用户必须是数据库中已存在的用户，并且是被授予 rds_iam 数据库角色的 AWS IAM 启用用户。身份验证基于 AWS 身份验证配置文件，或提供的 AccessKey/SecretKey。 AWS 身份验证令牌将在其过期时间之前通过 AWS 动态轮换。

字段	必需	详情	示例
`useAWSIAM`	Y	必须设置为 `true` 以使组件能够从 AWS IAM 获取访问令牌。此身份验证方法仅适用于 AWS Relational Database Service 的 PostgreSQL 数据库。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含已存在的用户，该用户对应于在 PostgreSQL 内部创建的、映射到 AWS IAM 策略的用户名称。此连接字符串不应包含任何密码。请注意，使用 AWS 时数据库名称字段由 dbname 表示。	`"host=mydb.postgres.database.aws.com user=myapplication port=5432 dbname=my_db sslmode=require"`
`awsRegion`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 版本中弃用。请改用 ‘region’。AWS Relational Database Service 部署所在的 AWS 区域。	`"us-east-1"`
`awsAccessKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 版本中弃用。请改用 ‘accessKey’。与 IAM 账户关联的 AWS 访问密钥	`"AKIAIOSFODNN7EXAMPLE"`
`awsSecretKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 版本中弃用。请改用 ‘secretKey’。与访问密钥关联的密钥	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`awsSessionToken`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 版本中弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅在使用临时安全凭证时才需要会话令牌。	`"TOKEN"`

其他元数据选项

字段	必需	详情	示例
`table`	Y	配置信息的表名，必须为小写。	`configtable`
`timeout`	N	数据库操作的超时时间，格式为 Go duration。整数被解释为秒数。默认为 `20s`	`"30s"`, `30`
`maxConns`	N	此组件池化的最大连接数。设置为 0 或更低以使用默认值，即 4 或 CPU 数量中的较大值。	`"4"`
`connectionMaxIdleTime`	N	在连接池中自动关闭未使用连接之前的最大空闲时间。默认情况下，没有值，这由数据库驱动程序选择。	`"5m"`
`queryExecMode`	N	控制执行查询的默认模式。默认情况下，Dapr 使用扩展协议并自动准备和缓存预备语句。但是，这可能与 PGBouncer 等代理不兼容。在这种情况下，最好使用 `exec` 或 `simple_protocol`。	`"simple_protocol"`

设置 PostgreSQL 作为配置存储

启动 PostgreSQL 数据库
连接到 PostgreSQL 数据库并按照以下架构设置配置表：
字段数据类型可为空详情
KEY VARCHAR N 保存配置属性的 "Key"
VALUE VARCHAR N 保存配置属性的 Value
VERSION VARCHAR N 保存配置属性的版本
METADATA JSON Y 将 Metadata 保存为 JSON
```
CREATE TABLE IF NOT EXISTS table_name (
  KEY VARCHAR NOT NULL,
  VALUE VARCHAR NOT NULL,
  VERSION VARCHAR NOT NULL,
  METADATA JSON
);
```

在配置表上创建 TRIGGER。创建 TRIGGER 的示例函数如下：

CREATE OR REPLACE FUNCTION notify_event() RETURNS TRIGGER AS $$
    DECLARE 
        data json;
        notification json;

    BEGIN

        IF (TG_OP = 'DELETE') THEN
            data = row_to_json(OLD);
        ELSE
            data = row_to_json(NEW);
        END IF;

        notification = json_build_object(
                          'table',TG_TABLE_NAME,
                          'action', TG_OP,
                          'data', data);
        PERFORM pg_notify('config',notification::text);
        RETURN NULL; 
    END;
$$ LANGUAGE plpgsql;

创建触发器，数据封装在标记为 data 的字段中：

notification = json_build_object(
  'table',TG_TABLE_NAME,
  'action', TG_OP,
  'data', data
);

订阅配置通知时，应使用作为 pg_notify 属性提及的通道

由于这是一个通用创建的触发器，请将此触发器映射到 配置表

CREATE TRIGGER config
AFTER INSERT OR UPDATE OR DELETE ON configtable
    FOR EACH ROW EXECUTE PROCEDURE notify_event();

在订阅请求中添加一个额外的元数据字段，键为 pgNotifyChannel，值应设置为 pg_notify 中提及的相同 通道名称。根据上面的示例，应将其设置为 config

注意

调用 subscribe API 时，应使用 metadata.pgNotifyChannel 来指定要监听来自 PostgreSQL 配置存储的通知的通道名称。

可以向订阅请求添加任意数量的键。每个订阅使用一个独占的数据库连接。强烈建议在单个订阅中订阅多个键。这有助于优化到数据库的连接数。

订阅 HTTP API 示例：

curl -l 'http://<host>:<dapr-http-port>/configuration/mypostgresql/subscribe?key=<keyname1>&key=<keyname2>&metadata.pgNotifyChannel=<channel name>'

2.3 - Redis

Redis 配置存储组件的详细信息

组件格式

要设置 Redis 配置存储，需创建一个类型为 configuration.redis 的组件。有关如何创建和应用配置存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: configuration.redis
  version: v1
  metadata:
  - name: redisHost
    value: <address>:6379
  - name: redisPassword
    value: **************
  - name: useEntraID
    value: "true"
  - name: enableTLS
    value: <bool>

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体操作请参阅此处。

规格元数据字段

字段	必填	详情	示例
redisHost	Y	Output	Redis 主机的连接字符串。如果 `"redisType"` 为 `"cluster"`，则可以是多个用逗号分隔的主机，也可以是单个主机。当使用 Redis Sentinel（`"failover"` 为 `"true"`）时，也可以提供多个 sentinel 地址，用逗号分隔。
redisPassword	N	Output	Redis 密码
redisUsername	N	Output	Redis 主机的用户名。默认为空。请确保你的 Redis 服务器版本为 6 或更高版本，并且已正确创建 acl 规则。
enableTLS	N	Output	如果 Redis 实例支持带有公共证书的 TLS，可以配置为启用或禁用 TLS。默认为 `"false"`
clientCert	N	Output	客户端证书的内容，用于需要客户端证书的 Redis 实例。必须与 `clientKey` 一起使用，且 `enableTLS` 必须设置为 true。建议使用密钥存储，具体操作请参阅此处
clientKey	N	Output	客户端私钥的内容，与 `clientCert` 配合用于身份验证。建议使用密钥存储，具体操作请参阅此处
failover	N	Output	启用故障转移配置的属性。需要设置 sentinelMasterName。启用后，redisHost 应包含 sentinel 地址。默认为 `"false"`
sentinelMasterName	N	Output	Sentinel 主节点名称。请参阅 Redis Sentinel 文档
sentinelUsername	N	Output	Redis Sentinel 的用户名。仅当 “failover” 为 true 且 Redis Sentinel 启用了身份验证时适用
sentinelPassword	N	Output	Redis Sentinel 的密码。仅当 “failover” 为 true 且 Redis Sentinel 启用了身份验证时适用
redisType	N	Output	Redis 的类型。有两个有效值，一个是 `"node"`，表示单节点模式；另一个是 `"cluster"`，表示 Redis 集群模式。默认为 `"node"`。
redisDB	N	Output	连接到 Redis 后选择的数据库。如果 `"redisType"` 为 `"cluster"`，则此选项将被忽略。默认为 `"0"`。
redisMaxRetries	N	Output	放弃前重试命令的最大次数。默认为不重试失败的命令。
redisMinRetryInterval	N	Output	每次重试之间 Redis 命令的最小退避时间。默认为 `"8ms"`； `"-1"` 禁用退避。
redisMaxRetryInterval	N	Output	每次重试之间 Redis 命令的最大退避时间。默认为 `"512ms"`；`"-1"` 禁用退避。
dialTimeout	N	Output	建立新连接的拨号超时时间。默认为 `"5s"`。
readTimeout	N	Output	套接字读取的超时时间。如果达到超时，Redis 命令将因超时而失败而不是阻塞。默认为 `"3s"`，`"-1"` 表示无超时。
writeTimeout	N	Output	套接字写入的超时时间。如果达到超时，Redis 命令将因超时而失败而不是阻塞。默认为 readTimeout。
poolSize	N	Output	套接字连接的最大数量。默认为 runtime.NumCPU 报告的每个 CPU 10 个连接。
poolTimeout	N	Output	当所有连接都忙时，客户端等待连接的时间，超时后返回错误。默认为 readTimeout + 1 秒。
maxConnAge	N	Output	连接的年龄，达到此年龄后客户端将关闭（退役）该连接。默认为不关闭旧连接。
minIdleConns	N	Output	保持打开的最小空闲连接数，以避免创建新连接导致的性能下降。默认为 `"0"`。
idleCheckFrequency	N	Output	空闲连接清理器执行空闲检查的频率。默认为 `"1m"`。`"-1"` 禁用空闲连接清理器。
idleTimeout	N	Output	客户端关闭空闲连接的时间长度。应小于服务器的超时时间。默认为 `"5m"`。`"-1"` 禁用空闲超时检查。

设置 Redis

Dapr 可以使用任何 Redis 实例：容器化的、在本地开发机器上运行的，或托管的云服务。

当你运行 dapr init 时，会自动创建一个 Redis 实例作为 Docker 容器

你可以使用 Helm 在我们的 Kubernetes 集群中快速创建 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到你的集群中。请注意，我们要显式设置一个镜像标签以获取大于 5 的版本，这是 Dapr 的发布订阅功能所要求的。如果你只打算将 Redis 用作状态存储（而不用于发布订阅），则不必设置镜像版本。
```
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis --set image.tag=6.2
```
运行 kubectl get pods 查看集群中现在运行的 Redis 容器。

将 redis-master:6379 作为 redisHost 添加到你的 redis.yaml 文件中。例如：

    metadata:
    - name: redisHost
      value: redis-master:6379

接下来，获取 Redis 密码，根据我们使用的操作系统，这略有不同：
- Windows：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" > encoded.b64，这将创建一个包含编码密码的文件。接下来，运行 certutil -decode encoded.b64 password.txt，这将把你的 redis 密码放入名为 password.txt 的文本文件中。复制密码并删除这两个文件。
- Linux/MacOS：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode 并复制输出的密码。
将此密码作为 redisPassword 值添加到你的 redis.yaml 文件中。例如：
```
    metadata:
    - name: redisPassword
      value: lhDOkwTlp0
```

AWS Redis

使用官方 Microsoft 文档创建 Azure Cache for Redis 实例。
实例创建完成后，从 Azure 门户获取主机名（FQDN）和访问密钥。
- 对于主机名：
  - 导航到资源的概览页面。
  - 复制主机名值。
- 对于访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存你的密钥。
将你的密钥和主机名添加到 Dapr 可应用于集群的 redis.yaml 文件中。
- 如果你在运行示例，请将主机和密钥添加到提供的 redis.yaml 中。
- 如果你从零开始创建项目，请按照组件格式部分中的说明创建 redis.yaml 文件。
将 redisHost 键设置为 [上一步的主机名]:6379，将 redisPassword 键设置为你之前保存的密钥。
注意： 在生产级应用程序中，请遵循密钥管理说明来安全地管理你的密钥。
启用 EntraID 支持：
- 在 Azure Redis 服务器上启用 Entra ID 身份验证。这可能需要几分钟时间。
- 将 useEntraID 设置为 "true" 以实现 Azure Cache for Redis 的 EntraID 支持。
将 enableTLS 设置为 "true" 以支持 TLS。

注意： useEntraID 假定你的 UserPrincipal（通过 AzureCLICredential）或 SystemAssigned 托管标识具有 RedisDataOwner 角色权限。如果使用用户分配的标识，你需要指定 azureClientID 属性。

GCP Cloud MemoryStore

Redis Sentinel 配置

当使用 Redis Sentinel 实现高可用时，将 redisType 设置为 "node"，使用 failover: "true" 启用故障转移模式，并提供 sentinel 主节点名称。可以在 redisHost 字段中指定多个 sentinel 地址，用逗号分隔，以实现冗余。

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: redis-pubsub
spec:
  type: pubsub.redis
  version: v1
  metadata:
  - name: redisHost
    value: "sentinel1:26379,sentinel2:26379,sentinel3:26379"
  - name: redisType
    value: "node"
  - name: failover
    value: "true"
  - name: sentinelMasterName
    value: "mymaster"
```

3 - Conversation 组件规格

与 Dapr 接口的受支持的 Conversation 组件

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Amazon Web Services (AWS)

Component	Status	Component version	Since runtime version
AWS Bedrock	Alpha	v1	1.15

Generic

Component	Status	Component version	Since runtime version
Anthropic	Alpha	v1	1.15
DeepSeek	Alpha	v1	1.15
GoogleAI	Alpha	v1	1.16
Huggingface	Alpha	v1	1.15
Local echo	Stable	v1	1.15
Mistral	Alpha	v1	1.15
Ollama	Alpha	v1	1.16
OpenAI	Alpha	v1	1.15

3.1 - Anthropic

Anthropic 对话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: anthropic
spec:
  type: conversation.anthropic
  metadata:
  - name: key
    value: "mykey"
  - name: model
    value: claude-3-5-sonnet-20240620
  - name: responseCacheTTL
    value: 10m

Warning

以上示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，如此处所述。

规范元数据字段

字段	必填	详情	示例
`key`	Y	Anthropic 的 API 密钥。	`"mykey"`
`model`	N	要使用的 Anthropic LLM。默认为 `claude-3-5-sonnet-20240620`	`claude-3-5-sonnet-20240620`
`responseCacheTTL`	N	内存响应缓存的生存时间。设置后，相同的请求将从缓存中提供，直到过期。	`10m`

3.2 - AWS Bedrock

关于 AWS Bedrock 会话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: awsbedrock
spec:
  type: conversation.aws.bedrock
  metadata:
  - name: endpoint
    value: "http://localhost:4566"
  - name: model
    value: amazon.titan-text-express-v1
  - name: responseCacheTTL
    value: 10m

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，如这里所述。

规格元数据字段

字段	必填	详情	示例
`region`	N	Bedrock 服务的 AWS 区域。	`us-east-1`
`endpoint`	N	组件用于连接模拟器的 AWS 端点。不推荐用于生产 AWS 环境。	`http://localhost:4566`
`accessKey`	N	用于身份验证的 AWS 访问密钥。建议使用密钥存储来存储此值。	`"AKIAIOSFODNN7EXAMPLE"`
`secretKey`	N	用于身份验证的 AWS 密钥。建议使用密钥存储来存储此值。	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`sessionToken`	N	用于临时凭证的 AWS 会话令牌。建议使用密钥存储来存储此值。	`"session-token-example"`
`model`	N	要使用的 LLM。默认为 Amazon 提供的 Bedrock 默认提供商模型。	`amazon.titan-text-express-v1`
`responseCacheTTL`	N	内存响应缓存的有效期。设置后，相同的请求将从缓存中提供服务，直到它们过期。	`10m`
`assumeRoleArn`	N	用于身份验证的要承担角色的 ARN。	`arn:aws:iam::123456789012:role/MyRole`
`trustAnchorArn`	N	用于身份验证的信任锚点的 ARN。	`arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/12345678-1234-1234-1234-123456789012`
`trustProfileArn`	N	用于身份验证的信任配置文件的 ARN。	`arn:aws:rolesanywhere:us-east-1:123456789012:profile/12345678-1234-1234-1234-123456789012`

身份验证 AWS

AWS Bedrock 不使用 key 参数，而是使用 Dapr 的标准 IAM 或静态凭证方法进行身份验证。了解更多关于 AWS 身份验证的信息。

3.3 - DeepSeek

DeepSeek 对话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: deepseek
spec:
  type: conversation.deepseek
  metadata:
  - name: key
    value: mykey
  - name: maxTokens
    value: 2048

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

规格元数据字段

Field	Required	Details	Example
`key`	Y	DeepSeek 的 API 密钥。	`mykey`
`maxTokens`	N	每次请求的最大令牌数。	`2048`

3.4 - 本地测试

用于本地测试的 echo conversation 组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: echo
spec:
  type: conversation.echo
  version: v1

Information

此组件仅用于 Conversation 组件实现的本地验证和测试。它实际上不会将数据发送到任何 LLM，而是直接回显输入。

3.5 - GoogleAI

GoogleAI 对话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: googleai
spec:
  type: conversation.googleai
  metadata:
  - name: key
    value: mykey
  - name: model
    value: gemini-1.5-flash
  - name: responseCacheTTL
    value: 10m

警告

以上示例将密钥以纯字符串形式使用。建议使用密钥存储来管理密钥，具体说明请参见此处。

规格元数据字段

字段	必填	详情	示例
`key`	Y	GoogleAI 的 API 密钥。	`mykey`
`model`	N	要使用的 GoogleAI 大语言模型。默认为 `gemini-1.5-flash`。	`gemini-2.0-flash`
`responseCacheTTL`	N	内存响应缓存的有效期。设置后，相同的请求将从缓存中提供响应，直到过期。	`10m`

3.6 - Huggingface

Huggingface 会话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: huggingface
spec:
  type: conversation.huggingface
  metadata:
  - name: key
    value: mykey
  - name: model
    value: meta-llama/Meta-Llama-3-8B
  - name: responseCacheTTL
    value: 10m

警告

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，具体说明请参见此处。

规范元数据字段

字段	必填	详情	示例
`key`	Y	Huggingface 的 API 密钥。	`mykey`
`model`	N	要使用的 Huggingface LLM。默认为 `meta-llama/Meta-Llama-3-8B`。	`meta-llama/Meta-Llama-3-8B`
`responseCacheTTL`	N	内存响应缓存的生存时间。设置后，相同的请求将从缓存中提供，直到过期。	`10m`

3.7 - Mistral

Mistral 对话组件的详细信息

组件格式

Dapr 的 conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mistral
spec:
  type: conversation.mistral
  metadata:
  - name: key
    value: mykey
  - name: model
    value: open-mistral-7b
  - name: responseCacheTTL
    value: 10m

Warning

上述示例使用纯文本字符串表示密钥。建议使用密钥存储来管理密钥，具体方法请参考此处。

规范元数据字段

字段	必需	说明	示例
`key`	Y	Mistral 的 API 密钥。	`mykey`
`model`	N	要使用的 Mistral LLM。默认为 `open-mistral-7b`。	`open-mistral-7b`
`responseCacheTTL`	N	内存响应缓存的生存时间。设置后，相同的请求将从缓存中返回，直到过期。	`10m`

3.8 - Ollama

Ollama 对话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: ollama
spec:
  type: conversation.ollama
  metadata:
  - name: model
    value: llama3.2:latest
  - name: responseCacheTTL
    value: 10m

警告

上面的示例使用明文字符串作为密钥。建议按照此处的说明使用密钥存储来管理密钥。

规格元数据字段

Field	Required	Details	Example
`model`	N	要使用的 Ollama LLM。默认为 `llama3.2:latest`。	`phi4:latest`
`responseCacheTTL`	N	内存响应缓存的生存时间。设置后，相同的请求将从缓存中提供，直到它们过期。	`10m`

OpenAI 兼容性

Ollama 与 OpenAI 的 API 兼容。你可以通过以下更改使用 OpenAI 组件与 Ollama 模型配合使用：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: ollama-openai
spec:
  type: conversation.openai # 使用 openai 组件类型
  metadata:
  - name: key
    value: 'ollama' # 任何非空字符串
  - name: model
    value: gpt-oss:20b  # 一个 ollama 模型（https://ollama.com/search），在这种情况下是 openai 开源模型。参见 https://ollama.com/library/gpt-oss
  - name: endpoint
    value: 'http://localhost:11434/v1' # ollama 端点

3.9 - OpenAI

OpenAI 对话组件的详细信息

组件格式

Dapr conversation.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: openai
spec:
  type: conversation.openai
  metadata:
  - name: key
    value: mykey
  - name: model
    value: gpt-4-turbo
  - name: endpoint
    value: 'https://api.openai.com/v1'
  - name: responseCacheTTL
    value: 10m
  # - name: apiType # Optional
  #   value: 'azure'
  # - name: apiVersion # Optional
  #   value: '2025-01-01-preview'

Warning

上述示例将密钥以纯文本字符串的形式使用。建议使用密钥存储来管理密钥，具体描述请参见此处。

规范元数据字段

字段	必填	详情	示例
`key`	Y	OpenAI 的 API 密钥。	`mykey`
`model`	N	要使用的 OpenAI 大语言模型。默认为 `gpt-4-turbo`。	`gpt-4-turbo`
`endpoint`	N	与 OpenAI API 兼容的自定义 API 端点 URL。如果未指定，则使用默认的 OpenAI API 端点。当 `apiType` 设置为 `azure` 时必填。	`https://api.openai.com/v1`、`https://example.openai.azure.com/`
`responseCacheTTL`	N	内存响应缓存的生存时间。设置后，相同的请求将从缓存中提供服务，直到过期。	`10m`
`apiType`	N	指定 API 提供商类型。当使用不遵循默认 OpenAI API 端点约定的提供商时必填。	`azure`
`apiVersion`	N	要使用的 API 版本。当 `apiType` 设置为 `azure` 时必填。	`2025-04-01-preview`

Azure OpenAI 配置

要配置 OpenAI 组件以连接到 Azure OpenAI，你需要设置以下元数据字段，这些字段对于 Azure 的 API 格式是必需的。

Azure OpenAI 的必填字段

连接到 Azure OpenAI 时，以下字段是必填的：

apiType：必须设置为 azure 以启用 Azure OpenAI 兼容性
endpoint：你的 Azure OpenAI 资源端点 URL（例如，https://your-resource.openai.azure.com/）
apiVersion：你的 Azure OpenAI 部署的 API 版本（例如，2025-01-01-preview）
key：你的 Azure OpenAI API 密钥

从以下网址获取你的配置值：https://ai.azure.com/

Azure OpenAI 组件示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azure-openai
spec:
  type: conversation.openai
  metadata:
  - name: key
    value: "your-azure-openai-api-key"
  - name: model
    value: "gpt-4.1-nano"  # Default: gpt-4.1-nano
  - name: endpoint
    value: "https://your-resource.openai.azure.com/"
  - name: apiType
    value: "azure"
  - name: apiVersion
    value: "2025-01-01-preview"

Note

使用 Azure OpenAI 时，endpoint 和 apiVersion 都是必填字段。当 apiType 设置为 azure 时，如果缺少任一字段，组件将返回错误。

4 - 加密组件规范

与 Dapr 交互的受支持的加密组件

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Using the Dapr cryptography engine

Component	Status	Component version	Since runtime version
JSON Web Key Sets (JWKS)	Alpha	v1	1.11
Kubernetes secrets	Alpha	v1	1.11
Local storage	Alpha	v1	1.11

Microsoft Azure

Component	Status	Component version	Since runtime version
Azure Key Vault	Alpha	v1	1.11

4.1 - Azure Key Vault

Azure Key Vault 加密组件的详细信息

组件格式

Dapr crypto.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: crypto.azure.keyvault
  metadata:
  - name: vaultName
    value: mykeyvault
  # See authentication section below for all options
  - name: azureTenantId
    value: ${{AzureKeyVaultTenantId}}
  - name: azureClientId
    value: ${{AzureKeyVaultServicePrincipalClientId}}
  - name: azureClientSecret
    value: ${{AzureKeyVaultServicePrincipalClientSecret}}

Warning

上面的示例使用纯文本字符串来存储密钥。建议使用密钥存储来管理密钥，如此处所述。

使用 Microsoft Entra ID 进行身份验证

Azure Key Vault 加密组件仅支持使用 Microsoft Entra ID 进行身份验证。在启用此组件之前：

阅读向 Azure 进行身份验证文档。
创建 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为您的应用程序平台创建托管标识。

规范元数据字段

Field	Required	Details	Example
`vaultName`	Y	Azure Key Vault 名称	`"mykeyvault"`
Auth metadata	Y	有关更多信息，请参阅向 Azure 进行身份验证

4.2 - JSON Web Key Sets (JWKS)

JWKS 加密组件的详细信息

组件格式

此组件的用途是从 JSON Web Key Set（RFC 7517）加载密钥。这些是包含 1 个或多个 JWK（JSON Web Key）密钥的 JSON 文档；它们可以是公钥、私钥或共享密钥。

此组件支持以下方式加载 JWKS：

从本地文件加载；在此情况下，Dapr 会监视磁盘上的文件变化并自动重新加载。
从 HTTP(S) URL 加载，该 URL 会定期刷新。
通过在 jwks 元数据属性中传入实际的 JWKS，作为字符串（可选择是否进行 base64 编码）。

注意

此组件使用 Dapr 中的加密引擎来执行操作。虽然密钥永远不会暴露给你的应用程序，但 Dapr 可以访问原始密钥材料。

Dapr crypto.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: jwks
spec:
  type: crypto.dapr.jwks
  version: v1
  metadata:
    # 示例 1：从文件加载 JWKS
    - name: "jwks"
      value: "fixtures/crypto/jwks/jwks.json"
    # 示例 2：从 HTTP(S) URL 加载 JWKS
    # 仅需要 "jwks"
    - name: "jwks"
      value: "https://example.com/.well-known/jwks.json"
    - name: "requestTimeout"
      value: "30s"
    - name: "minRefreshInterval"
      value: "10m"
    # 选项 3：包含实际的 JWKS
    - name: "jwks"
      value: |
        {
          "keys": [
            {
              "kty": "RSA",
              "use": "sig",
              "kid": "…",
              "n": "…",
              "e": "…",
              "issuer": "https://example.com"
            }
          ]
        }
    # 选项 3b：包含 base64 编码的 JWKS
    - name: "jwks"
      value: |
        eyJrZXlzIjpbeyJ…

警告

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，如此处所述。

规范元数据字段

字段	必填	详情	示例
`jwks`	Y	JWKS 文档的路径	本地文件：`"fixtures/crypto/jwks/jwks.json"` HTTP(S) URL：`"https://example.com/.well-known/jwks.json"` 嵌入的 JWKS：`{"keys": […]}`（可以是 base64 编码）
`requestTimeout`	N	从 HTTP(S) URL 获取 JWKS 文档时网络请求的超时时间，采用 Go duration 格式。默认值：“30s”	`"5s"`
`minRefreshInterval`	N	从 HTTP(S) 源后续刷新 JWKS 文档前等待的最小间隔，采用 Go duration 格式。默认值：“10m”	`"1h"`

4.3 - Kubernetes Secrets

有关 Kubernetes 密钥加密组件的详细信息

组件格式

此组件的目的是加载以密钥名称命名的 Kubernetes 密钥。

注意

此组件使用 Dapr 中的加密引擎执行操作。虽然密钥永远不会暴露给您的应用程序，但 Dapr 可以访问原始密钥材料。

Dapr crypto.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: crypto.dapr.kubernetes.secrets
  version: v1
  metadata:[]

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来存储密钥，如此处所述。

规范元数据字段

字段	必需	详细信息	示例
`defaultNamespace`	N	用于检索密钥的默认命名空间。如果未设置，则必须为每个密钥指定命名空间，格式为 `namespace/secretName/key`	`"default-ns"`
`kubeconfigPath`	N	kubeconfig 文件的路径。如果未指定，组件将使用群集内默认配置值	`"/path/to/kubeconfig"`

4.4 - Local storage

本地存储密码学组件的详细信息

组件格式

此组件的目的是从本地目录加载密钥。

该组件接受文件夹名称作为输入，并从该文件夹加载密钥。每个密钥都在其自己的文件中，当用户请求给定名称的密钥时，Dapr 将加载具有该名称的文件。

支持的文件格式：

PEM 格式的公钥和私钥（支持：PKCS#1、PKCS#8、PKIX）
JSON Web Key (JWK)，包含公钥、私钥或对称密钥
对称密钥的原始密钥数据

注意

此组件使用 Dapr 中的密码学引擎执行操作。尽管密钥永远不会暴露给您的应用程序，但 Dapr 可以访问原始密钥材料。

Dapr crypto.yaml 组件文件具有以下结构：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mycrypto
spec:
  type: crypto.dapr.localstorage
  version: v1
  metadata:
    - name: path
      value: /path/to/folder/

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体说明请参阅此处。

规范元数据字段

字段	必填	详情	示例
`path`	Y	包含要加载的密钥的文件夹。加载密钥时，密钥名称将用作该文件夹中的文件名。	`/path/to/folder`

示例

假设您已设置 path=/mnt/keys，其中包含以下文件：

/mnt/keys/mykey1.pem
/mnt/keys/mykey2

使用该组件时，您可以将密钥引用为 mykey1.pm 和 mykey2。

5 - Lock 组件规范

与 Dapr 交互的受支持的锁组件

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Status	Component version	Since runtime version
Redis	Alpha	v1	1.8

5.1 - Redis

Redis lock 组件的详细信息

组件格式

要设置 Redis lock，请创建一个类型为 lock.redis 的组件。请参阅此指南了解如何创建 lock。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: lock.redis
  version: v1
  metadata:
  - name: redisHost
    value: <HOST>
  - name: redisPassword #可选。
    value: <PASSWORD>
  - name: useEntraID
    value: <bool> # 可选。允许值：true, false。
  - name: enableTLS
    value: <bool> # 可选。允许值：true, false。
  - name: failover
    value: <bool> # 可选。允许值：true, false。
  - name: sentinelMasterName
    value: <string> # 可选
  - name: maxRetries
    value: # 可选
  - name: maxRetryBackoff
    value: # 可选
  - name: redeliverInterval
    value: # 可选
  - name: processingTimeout
    value: # 可选
  - name: redisType
    value: # 可选
  - name: redisDB
    value: # 可选
  - name: redisMaxRetries
    value: # 可选
  - name: redisMinRetryInterval
    value: # 可选
  - name: redisMaxRetryInterval
    value: # 可选
  - name: dialTimeout
    value: # 可选
  - name: readTimeout
    value: # 可选
  - name: writeTimeout
    value: # 可选
  - name: poolSize
    value: # 可选
  - name: poolTimeout
    value: # 可选
  - name: maxConnAge
    value: # 可选
  - name: minIdleConns
    value: # 可选
  - name: idleCheckFrequency
    value: # 可选
  - name: idleTimeout
    value: # 可选

警告

上面的示例将 secret 用作纯文本字符串。建议使用 secret store 来管理 secret，具体方法请参阅此处。

规范元数据字段

字段	必填	详情	示例
redisHost	Y	Redis 主机的连接字符串。如果 `"redisType"` 是 `"cluster"`，它可以是多个以逗号分隔的主机，也可以是单个主机。当使用 Redis Sentinel（`"failover"` 为 `"true"`）时，也可以提供多个 sentinel 地址，以逗号分隔的值的形式。	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379` 主机
redisPassword	N	Redis 主机的密码。默认无。可以是 `secretKeyRef` 以使用 secret 引用	`""`, `"KeFg23!"`
redisUsername	N	Redis 主机的用户名。默认为空。请确保您的 redis 服务器版本为 6 或更高版本，并且已正确创建 acl 规则。	`""`, `"default"`
useEntraID	N	为 Azure Cache for Redis 实现 EntraID 支持。在启用此功能之前： `redisHost` 名称必须以 `"server:port"` 的形式指定必须启用 TLS 在创建 Redis 实例 > Azure Cache for Redis下了解有关此设置的更多信息	`"true"`, `"false"`
enableTLS	N	如果 Redis 实例支持具有公共证书的 TLS，可以配置为启用或禁用。默认为 `"false"`	`"true"`, `"false"`
maxRetries	N	放弃前的最大重试次数。默认为 `3`	`5`, `10`
maxRetryBackoff	N	每次重试之间的最大退避时间。默认为 `2` 秒；`"-1"` 禁用退避。	`3000000000`
failover	N	用于启用故障转移配置的属性。需要设置 sentinelMasterName。启用后，redisHost 应包含 sentinel 地址。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	Sentinel 主节点名称。请参阅 Redis Sentinel 文档	`"mymaster"`
sentinelPassword	N	Redis Sentinel 的密码。默认无。仅当 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`""`, `"KeFg23!"`
redeliverInterval	N	检查待重新传递的消息之间的间隔。默认为 `"60s"`。`"0"` 禁用重新传递。	`"30s"`
processingTimeout	N	消息在尝试重新传递之前必须待处理的时间量。默认为 `"15s"`。`"0"` 禁用重新传递。	`"30s"`
redisType	N	Redis 的类型。有两个有效值，一个是 `"node"` 用于单节点模式，另一个是 `"cluster"` 用于 redis 集群模式。默认为 `"node"`。	`"cluster"`
redisDB	N	连接到 redis 后选择的数据库。如果 `"redisType"` 是 `"cluster"`，此选项将被忽略。默认为 `"0"`。	`"0"`
redisMaxRetries	N	`maxRetries` 的别名。如果设置了两个值，则忽略 `maxRetries`。	`"5"`
redisMinRetryInterval	N	每次重试之间 redis 命令的最小退避时间。默认为 `"8ms"`； `"-1"` 禁用退避。	`"8ms"`
redisMaxRetryInterval	N	`maxRetryBackoff` 的别名。如果设置了两个值，则忽略 `maxRetryBackoff`。	`"5s"`
dialTimeout	N	建立新连接的拨号超时时间。默认为 `"5s"`。	`"5s"`
readTimeout	N	套接字读取的超时时间。如果达到超时，redis 命令将因超时而失败，而不是阻塞。默认为 `"3s"`，`"-1"` 表示无超时。	`"3s"`
writeTimeout	N	套接字写入的超时时间。如果达到超时，redis 命令将因超时而失败，而不是阻塞。默认为 readTimeout。	`"3s"`
poolSize	N	套接字连接的最大数量。默认为运行时报告的每个 CPU 10 个连接（NumCPU）	`“20”
poolTimeout	N	如果所有连接都忙，客户端等待连接的时间，然后返回错误。默认为 readTimeout + 1 秒。	`"5s"`
maxConnAge	N	客户端停用（关闭）连接的连接年龄。默认是不关闭旧连接。	`"30m"`
minIdleConns	N	保持打开的空闲连接的最小数量，以避免与创建新连接相关的性能下降。默认为 `"0"`。	`"2"`
idleCheckFrequency	N	空闲连接清理器执行的空闲检查频率。默认为 `"1m"`。`"-1"` 禁用空闲连接清理器。	`"-1"`
idleTimeout	N	客户端关闭空闲连接之后的时间量。应小于服务器的超时时间。默认为 `"5m"`。`"-1"` 禁用空闲超时检查。	`"10m"`

设置 Redis

Dapr 可以使用任何 Redis 实例：容器化的、在本地开发机器上运行的，或托管的云服务。

当您运行 dapr init 时，会自动创建一个 Redis 实例作为 Docker 容器

您可以使用 Helm 在我们的 Kubernetes 集群中快速创建 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。请注意，我们显式地设置了一个镜像标签以获得大于 5 的版本，这是 Dapr 的发布/订阅功能所要求的。如果您打算仅将 Redis 用作状态存储（而不用于发布/订阅），则不必设置镜像版本。
```
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis --set image.tag=6.2
```
运行 kubectl get pods 以查看 Redis 容器现在在您的集群中运行。

在您的 redis.yaml 文件中添加 redis-master:6379 作为 redisHost。例如：

    metadata:
    - name: redisHost
      value: redis-master:6379

接下来，获取 Redis 密码，这根据我们使用的操作系统略有不同：
- Windows：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" > encoded.b64，这将创建一个包含编码密码的文件。接下来，运行 certutil -decode encoded.b64 password.txt，这会将您的 redis 密码放入名为 password.txt 的文本文件中。复制密码并删除这两个文件。
- Linux/MacOS：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode 并复制输出的密码。
将此密码作为 redisPassword 值添加到您的 redis.yaml 文件中。例如：
```
    metadata:
    - name: redisPassword
      value: lhDOkwTlp0
```

AWS Redis

使用官方 Microsoft 文档创建 Azure Cache for Redis 实例。
创建实例后，从 Azure 门户获取主机名（FQDN）和您的访问密钥。
- 对于主机名：
  - 导航到资源的概览页面。
  - 复制主机名值。
- 对于您的访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存您的密钥。
将您的密钥和主机名添加到 Dapr 可以应用于您的集群的 redis.yaml 文件中。
- 如果您正在运行示例，请将主机和密钥添加到提供的 redis.yaml 中。
- 如果您是从头开始创建项目，请按照组件格式部分中的说明创建 redis.yaml 文件。
将 redisHost 键设置为 [上一步中的主机名]:6379，将 redisPassword 键设置为之前保存的密钥。
注意： 在生产级应用程序中，请遵循 secret 管理说明来安全管理您的 secret。
启用 EntraID 支持：
- 在您的 Azure Redis 服务器上启用 Entra ID 身份验证。这可能需要几分钟时间。
- 将 useEntraID 设置为 "true" 以为 Azure Cache for Redis 实现 EntraID 支持。
将 enableTLS 设置为 "true" 以支持 TLS。

注意：useEntraID 假定您的 UserPrincipal（通过 AzureCLICredential）或 SystemAssigned 托管标识具有 RedisDataOwner 角色权限。如果使用用户分配的标识，您需要指定 azureClientID 属性。

GCP Cloud MemoryStore

Redis Sentinel 行为

连接到 Redis Sentinel 时，请使用 redisType: "node"。此外，将 failover 设置为 "true"，并将 sentinelMasterName 设置为主节点的名称。可以在 redisHost 字段中以逗号分隔的列表形式指定多个 sentinel 地址以实现冗余。

故障转移特征：

故障转移期间的锁丢失：如果锁在原始主节点故障之前未复制到提升的副本，则在主节点故障转移期间可能会丢失锁
故障转移窗口：自动主节点提升期间服务器短暂不可用（通常为几秒）
一致性：所有操作都路由到当前主节点，保持锁一致性

警告

请考虑运行 Redis 的高可用性和故障转移与故障转移事件期间可能丢失的锁之间的权衡。您的应用程序应能容忍故障转移场景期间的短暂锁丢失。

6 - 中间件组件规格

可注入 Dapr 处理管道的所有受支持的中间件组件列表。

下表列出了 Dapr 支持的中间件组件。了解如何自定义处理管道和设置中间件组件。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

HTTP

Component	Description	Status	Component version
OAuth2 Authorization Grant flow	Enables the OAuth2 Authorization Grant flow on a Web API	Alpha	v1
OAuth2 Client Credentials Grant flow	Enables the OAuth2 Client Credentials Grant flow on a Web API	Alpha	v1
OpenID Connect	Verifies a Bearer Token using OpenID Connect on a Web API	Stable	v1
Rate limit	Restricts the maximum number of allowed HTTP requests per second	Stable	v1
Rego/OPA Policies	Applies Rego/OPA Policies to incoming Dapr HTTP requests	Alpha	v1
Router Alias	Use Router Alias to map arbitrary HTTP routes to valid Dapr API endpoints	Alpha	v1
RouterChecker	Use RouterChecker middleware to block invalid http request routing	Alpha	v1
Sentinel	Use Sentinel middleware to guarantee the reliability and resiliency of your application	Alpha	v1
Uppercase	Converts the body of the request to uppercase letters (demo)	Stable	v1
Wasm	Use Wasm middleware in your HTTP pipeline	Alpha	v1

6.1 - Bearer

使用 bearer 中间件通过验证 bearer 令牌来保护 HTTP 端点

bearer HTTP 中间件在 Web API 上使用 OpenID Connect 验证 Bearer 令牌，而无需修改应用程序。此设计将身份验证/授权关注点与应用程序分离，使应用程序操作员能够采用和配置身份验证/授权提供程序，而不会影响应用程序代码。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: bearer-token
spec:
  type: middleware.http.bearer
  version: v1
  metadata:
    - name: audience
      value: "<your token audience; i.e. the application's client ID>"
    - name: issuer
      value: "<your token issuer, e.g. 'https://accounts.google.com'>"

    # Optional values
    - name: jwksURL
      value: "<JWKS URL, e.g. 'https://accounts.google.com/.well-known/openid-configuration'>"

规格元数据字段

字段	必填	详情	示例
`audience`	Y	令牌中期望的受众。通常，这对应于在 OpenID Connect 平台托管的凭据下创建的应用程序的客户端 ID。
`issuer`	Y	颁发者机构，即令牌中颁发者声明的期望值。	`"https://accounts.google.com"`
`jwksURL`	N	JWKS（包含用于验证令牌的公钥的 JWK 集）的地址。如果为空，将尝试从 OpenID 配置文档 `<issuer>/.well-known/openid-configuration` 中获取 URL。	`"https://accounts.google.com/.well-known/openid-configuration"`

issuer 的常见值包括：

Auth0：https://{domain}，其中 {domain} 是您的 Auth0 应用程序的域
Microsoft Entra ID：https://login.microsoftonline.com/{tenant}/v2.0，其中 {tenant} 应替换为您应用程序的租户 ID，格式为 UUID
Google：https://accounts.google.com
Salesforce (Force.com)：https://login.salesforce.com

Dapr 配置

要应用中间件，必须在配置中引用该中间件。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: bearer-token
      type: middleware.http.bearer

6.2 - OAuth2

使用 OAuth2 中间件来保护 HTTP 端点

OAuth2 HTTP 中间件可在无需修改应用程序的情况下，为 Web API 启用 OAuth2 授权码流程。这种设计将身份验证/授权的关注点与应用程序分离，使应用程序运维人员可以采用和配置身份验证/授权提供程序，而不会影响应用程序代码。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2
spec:
  type: middleware.http.oauth2
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "https://www.googleapis.com/auth/userinfo.email"
  - name: authURL
    value: "https://accounts.google.com/o/oauth2/v2/auth"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: redirectURL
    value: "http://dummy.com"
  - name: authHeaderName
    value: "authorization"
  - name: forceHTTPS
    value: "false"
  - name: pathFilter
    value: ".*/users/.*"

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，如这里所述。

规范元数据字段

字段	详细信息	示例
clientId	您的应用程序的客户端 ID，它是作为由支持 OAuth 的平台托管的凭据的一部分创建的
clientSecret	您的应用程序的客户端密钥，它是作为由支持 OAuth 的平台托管的凭据的一部分创建的
scopes	以空格分隔、区分大小写的 scope 字符串列表，通常用于应用程序中的授权	`"https://www.googleapis.com/auth/userinfo.email"`
authURL	OAuth2 授权服务器的端点	`"https://accounts.google.com/o/oauth2/v2/auth"`
tokenURL	客户端用于通过出示其授权授权或刷新令牌来获取访问令牌的端点	`"https://accounts.google.com/o/oauth2/token"`
redirectURL	授权服务器应在用户完成身份验证后重定向到的 Web 应用程序 URL	`"https://myapp.com"`
authHeaderName	要转发到您的应用程序的授权标头名称	`"authorization"`
forceHTTPS	如果为 true，则强制使用 TLS/SSL	`"true"`,`"false"`
pathFilter	仅将中间件应用于与给定路径模式匹配的请求	`"./users/."`

Dapr 配置

要应用中间件，必须在配置中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: oauth2
      type: middleware.http.oauth2

请求路径过滤

pathFilter 字段允许您使用正则表达式模式根据 HTTP 请求路径有选择地应用 OAuth2 身份验证。这支持以下场景：例如为不同的 API 端点配置具有不同 scope 的多个 OAuth2 中间件，通过确保用户仅获得其预期操作所需的最小权限，来实现最小权限原则。

示例：分离只读和管理员用户访问

在以下配置中：

对 /api/users/* 端点的请求获得具有只读用户 scope 的令牌
对 /api/admin/* 端点的请求获得具有完整管理员 scope 的令牌

这通过防止不必要的权限访问并限制受损令牌的影响范围来降低安全风险。

# 具有只读访问权限的用户
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2-users
spec:
  type: middleware.http.oauth2
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "user:read profile:read"
  - name: authURL
    value: "https://accounts.google.com/o/oauth2/v2/auth"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: redirectURL
    value: "http://myapp.com/callback"
  - name: pathFilter
    value: "^/api/users/.*"
---
# 具有完整管理员访问权限的用户
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2-admin
spec:
  type: middleware.http.oauth2
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "admin:read admin:write user:read user:write"
  - name: authURL
    value: "https://accounts.google.com/o/oauth2/v2/auth"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: redirectURL
    value: "http://myapp.com/callback"
  - name: pathFilter
    value: "^/api/admin/.*"

6.3 - OAuth2 客户端凭据

使用 OAuth2 客户端凭据中间件保护 HTTP 端点

OAuth2 客户端凭据 HTTP 中间件可在无需修改应用程序的情况下，为 Web API 启用 OAuth2 客户端凭据流。这种设计将身份验证/授权的关注点与应用程序分离，使得应用程序运维人员可以采用和配置身份验证/授权提供方，而不会影响应用程序代码。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2clientcredentials
spec:
  type: middleware.http.oauth2clientcredentials
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "https://www.googleapis.com/auth/userinfo.email"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: headerName
    value: "authorization"
  - name: pathFilter
    value: ".*/users/.*"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	详情	示例
clientId	在支持 OAuth 的平台上托管作为凭据的一部分而创建的应用程序客户端 ID
clientSecret	在支持 OAuth 的平台上托管作为凭据的一部分而创建的应用程序客户端密钥
scopes	以空格分隔的、区分大小写的范围字符串列表，通常用于应用程序中的授权	`"https://www.googleapis.com/auth/userinfo.email"`
tokenURL	客户端通过呈现其授权授予或刷新令牌来获取访问令牌的端点	`"https://accounts.google.com/o/oauth2/token"`
headerName	转发到应用程序的授权标头名称	`"authorization"`
endpointParamsQuery	指定对令牌端点的请求的附加参数	`true`
authStyle	可选地指定端点希望如何发送客户端 ID 和客户端密钥。请参阅下表中的可能值	`0`
pathFilter	仅将中间件应用于匹配给定路径模式的请求	`"./users/."`

`authStyle` 的可能值

值	含义
`1`	在 POST 正文中发送 “client_id” 和 “client_secret” 作为 application/x-www-form-urlencoded 参数。
`2`	使用 HTTP 基本认证发送 “client_id” 和 “client_secret”。这是 OAuth2 RFC 6749 第 2.3.1 节中描述的一种可选样式。
`0`	表示通过尝试两种方式并缓存成功的方式来自动检测提供方想要的认证样式。

Dapr 配置

要应用中间件，必须在配置中引用该中间件。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: oauth2clientcredentials
      type: middleware.http.oauth2clientcredentials

请求路径过滤

pathFilter 字段允许您使用正则表达式模式，基于 HTTP 请求路径有选择地应用 OAuth2 身份验证。这支持诸如配置多个具有不同范围的 OAuth2 中间件用于不同 API 端点、通过确保用户仅获得其预期操作所需的最小权限来实现最小权限原则等场景。

示例：区分只读用户和管理员用户访问

在以下配置中：

对 /api/users/* 端点的请求接收带有只读用户范围的令牌
对 /api/admin/* 端点的请求接收带有完整管理员范围的令牌这通过防止不必要的特权访问和限制受损令牌的影响范围来降低安全风险。

# 具有只读访问范围的用户
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2clientcredentials-users
spec:
  type: middleware.http.oauth2clientcredentials
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "user:read profile:read"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: headerName
    value: "authorization"
  - name: pathFilter
    value: "^/api/users/.*"
---
# 具有完整管理员访问范围的用户
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2clientcredentials-admin
spec:
  type: middleware.http.oauth2clientcredentials
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "admin:read admin:write user:read user:write"
  - name: tokenURL
    value: "https://accounts.google.com/o/oauth2/token"
  - name: headerName
    value: "authorization"
  - name: pathFilter
    value: "^/api/admin/.*"

6.4 - 应用 Open Policy Agent (OPA) 策略

使用中间件对传入请求应用 Open Policy Agent (OPA) 策略

Open Policy Agent (OPA) HTTP 中间件将 OPA 策略应用于传入的 Dapr HTTP 请求。这可用于对应用端点应用可重用的授权策略。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: my-policy
spec:
  type: middleware.http.opa
  version: v1
  metadata:
    # `includedHeaders` 是以逗号分隔的、不区分大小写的请求头集合，
    # 这些请求头将被包含在请求输入中。
    # 默认情况下，请求头不会传递给策略。若要在输入中接收传入请求头，
    # 请包含此配置
    - name: includedHeaders
      value: "x-my-custom-header, x-jwt-header"

    # `defaultStatus` 是拒绝响应时返回的状态码
    - name: defaultStatus
      value: 403

    # `readBody` 控制中间件是否在内存中读取完整的请求体，
    # 以便用于策略决策。
    - name: readBody
      value: "false"

    # `rego` 是要评估的 open policy agent 策略。必填
    # 策略包必须是 http，且策略必须设置 data.http.allow
    - name: rego
      value: |
        package http

        default allow = true

        # Allow 也可以是一个对象，并包含其他属性

        # 例如，如果你想在策略失败时重定向，可以设置状态码为 301，
        # 并在响应上设置 location 请求头：
        allow = {
            "status_code": 301,
            "additional_headers": {
                "location": "https://my.site/authorize"
            }
        } {
            not jwt.payload["my-claim"]
        }

        # 你也可以允许请求并为其添加额外的请求头：
        allow = {
            "allow": true,
            "additional_headers": {
                "x-my-claim": my_claim
            }
        } {
            my_claim := jwt.payload["my-claim"]
        }
        jwt = { "payload": payload } {
            auth_header := input.request.headers["Authorization"]
            [_, jwt] := split(auth_header, " ")
            [_, payload, _] := io.jwt.decode(jwt)
        }

你可以使用官方 OPA playground 原型和实验策略。例如，可以在这里找到上述示例策略。

规范元数据字段

字段	详情	示例
`rego`	Rego 策略语言	见上文
`defaultStatus`	拒绝响应时返回的状态码	`"403"`
`readBody`	如果设置为 `true`（默认值），则会完整读取每个请求的请求体到内存中，并可用于策略决策。如果你的策略不依赖于检查请求体，考虑将其禁用（设置为 `false`）以获得显著的性能提升。	`"false"`
`includedHeaders`	以逗号分隔的、不区分大小写的请求头集合，这些请求头将被包含在请求输入中。默认情况下，请求头不会传递给策略。若要在输入中接收传入请求头，请包含此配置	`"x-my-custom-header, x-jwt-header"`

Dapr 配置

要应用中间件，必须在配置中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: my-policy
      type: middleware.http.opa

输入

此中间件提供 HTTPRequest 作为输入。

HTTPRequest

HTTPRequest 输入包含关于传入 HTTP 请求的所有相关信息。

type Input struct {
  request HTTPRequest
}

type HTTPRequest struct {
  // 请求方法（例如 GET、POST 等...）
  method string
  // 原始请求路径（例如 "/v2/my-path/"）
  path string
  // 将路径分解为多个部分以便于使用（例如 ["v2", "my-path"]）
  path_parts string[]
  // 原始查询字符串（例如 "?a=1&b=2"）
  raw_query string
  // 将查询分解为键及其值
  query map[string][]string
  // 请求头
  // 注意：默认情况下，不包含任何请求头。你必须通过
  // `spec.metadata.includedHeaders` 指定想要接收的请求头（见上文）
  headers map[string]string
  // 请求方案（例如 http、https）
  scheme string
  // 请求体（例如 http、https）
  body string
}

结果

策略必须设置 data.http.allow，其值为 boolean 类型，或带有 allow 布尔属性的 object 类型。allow 为 true 将允许请求，而 false 值将拒绝请求，并返回由 defaultStatus 指定的状态码。以下策略使用默认值，演示了对所有请求返回 403 - Forbidden：

package http

default allow = false

这等同于：

package http

default allow = {
  "allow": false
}

更改拒绝响应的状态码

拒绝请求时，你可以覆盖返回的状态码。例如，如果你想返回 401 而不是 403，可以执行以下操作：

package http

default allow = {
  "allow": false,
  "status_code": 401
}

添加响应头

要重定向，请添加请求头并将 status_code 设置为返回结果：

package http

default allow = {
  "allow": false,
  "status_code": 301,
  "additional_headers": {
    "Location": "https://my.redirect.site"
  }
}

添加请求头

你还可以在允许的请求上设置额外的请求头：

package http

default allow = false

allow = { "allow": true, "additional_headers": { "X-JWT-Payload": payload } } {
  not input.path[0] == "forbidden"
  // 其中 `jwt` 是另一个规则的结果
  payload := base64.encode(json.marshal(jwt.payload))
}

结果结构

type Result bool
// 或
type Result struct {
  // 是否允许或拒绝传入请求
  allow bool
  // 覆盖拒绝响应的状态码；可选
  status_code int
  // 在允许的请求或拒绝响应上设置请求头；可选
  additional_headers map[string]string
}

6.5 - Router alias http request routing

使用 router alias 中间件将任意 HTTP 路由别名为 Dapr 端点

Router alias HTTP 中间件组件允许您将传入 Dapr 的任意 HTTP 路由转换为有效的 Dapr API 端点。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: routeralias 
spec:
  type: middleware.http.routeralias
  version: v1
  metadata:
    # String containing a JSON-encoded or YAML-encoded dictionary
    # Each key in the dictionary is the incoming path, and the value is the path it's converted to
    - name: "routes"
      value: |
        {
          "/mall/activity/info": "/v1.0/invoke/srv.default/method/mall/activity/info",
          "/hello/activity/{id}/info": "/v1.0/invoke/srv.default/method/hello/activity/info",
          "/hello/activity/{id}/user": "/v1.0/invoke/srv.default/method/hello/activity/user"
        }

在上面的示例中，传入的 HTTP 请求 /mall/activity/info?id=123 会被转换为 /v1.0/invoke/srv.default/method/mall/activity/info?id=123。

规范元数据字段

字段	详情	示例
`routes`	包含 JSON 编码或 YAML 编码字典的字符串。字典中的每个键是传入路径，值是其要转换到的路径。	见上面的示例

Dapr 配置

要应用中间件，必须在配置中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: routeralias 
      type: middleware.http.routeralias

6.6 - RouterChecker HTTP 请求路由

使用 routerchecker 中间件阻止无效的 HTTP 请求路由

RouterChecker HTTP [中间件]（https://docs.dapr.io/zh-hans/operations/components/middleware/）组件利用正则表达式来检查 HTTP 请求路由的有效性，防止无效路由进入 Dapr 集群。RouterChecker 组件会过滤掉错误请求，从而减少遥测和日志数据中的噪音。

组件格式

RouterChecker 将一组规则应用于传入的 HTTP 请求。你可以使用正则表达式在组件元数据中定义这些规则。在以下示例中，HTTP 请求 RouterChecker 被设置为根据 ^[A-Za-z0-9/._-]+$ 正则表达式验证所有请求消息。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: routerchecker 
spec:
  type: middleware.http.routerchecker
  version: v1
  metadata:
  - name: rule
    value: "^[A-Za-z0-9/._-]+$"

在此示例中，上述定义将产生以下通过/失败案例：

PASS /v1.0/invoke/demo/method/method
PASS /v1.0/invoke/demo.default/method/method
PASS /v1.0/invoke/demo.default/method/01
PASS /v1.0/invoke/demo.default/method/METHOD
PASS /v1.0/invoke/demo.default/method/user/info
PASS /v1.0/invoke/demo.default/method/user_info
PASS /v1.0/invoke/demo.default/method/user-info

FAIL /v1.0/invoke/demo.default/method/cat password
FAIL /v1.0/invoke/demo.default/method/" AND 4210=4210 limit 1
FAIL /v1.0/invoke/demo.default/method/"$(curl

规范元数据字段

字段	详情	示例
rule	HTTP 请求 RouterChecker 使用的正则表达式	`^[A-Za-z0-9/._-]+$`

Dapr 配置

要应用该中间件，必须在[配置]（https://docs.dapr.io/zh-hans/concepts/configuration-concept/）中引用它。请参阅[中间件管道]（https://docs.dapr.io/zh-hans/operations/components/middleware/#customize-processing-pipeline）。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: routerchecker 
      type: middleware.http.routerchecker

6.7 - Sentinel 容错中间件组件

使用 Sentinel 中间件来保障应用的可靠性和弹性

Sentinel 是一个强大的容错组件，以"流量"为切入点，涵盖了流量控制、流量整形、并发限制、熔断降级和自适应系统保护等多个领域，从而保障微服务的可靠性和弹性。

Sentinel HTTP 中间件使 Dapr 能够利用 Sentinel 的强大能力来保护你的应用程序。有关 Sentinel 的更多细节，你可以参考 Sentinel Wiki。

组件格式

在以下定义中，每秒最大请求数设置为 10：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: sentinel
spec:
  type: middleware.http.sentinel
  version: v1
  metadata:
  - name: appName
    value: "nodeapp"
  - name: logDir
    value: "/var/tmp"
  - name: flowRules
    value: >-
      [
        {
          "resource": "POST:/v1.0/invoke/nodeapp/method/neworder",
          "threshold": 10,
          "tokenCalculateStrategy": 0,
          "controlBehavior": 0
        }
      ]

规格元数据字段

字段	详情	示例
appName	当前运行服务的名称	`nodeapp`
logDir	日志目录路径	`/var/tmp/sentinel`
flowRules	Sentinel 流量控制规则的 JSON 数组	流量控制规则
circuitBreakerRules	Sentinel 熔断规则的 JSON 数组	熔断规则
hotSpotParamRules	Sentinel 热点参数流量控制规则的 JSON 数组	热点规则
isolationRules	Sentinel 隔离规则的 JSON 数组	隔离规则
systemRules	Sentinel 系统规则的 JSON 数组	系统规则

一旦达到限制，请求将返回 HTTP 状态码 429：请求过多。

每个规则定义中的 resource 字段需特别注意。在 Dapr 中，它遵循以下格式：

POST/GET/PUT/DELETE:Dapr HTTP API 请求路径

所有具体的 HTTP API 信息可以在 Dapr API 参考中找到。在上述示例配置中，resource 字段设置为 POST:/v1.0/invoke/nodeapp/method/neworder。

Dapr 配置

要使中间件生效，必须在配置中引用该中间件。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: daprConfig
spec:
  httpPipeline:
    handlers:
      - name: sentinel
        type: middleware.http.sentinel

6.8 - 将请求体转换为大写

使用 uppercase 中间件测试您的 HTTP 管道是否正常工作

uppercase HTTP 中间件将请求体转换为大写字母，用于测试管道是否正常工作。它仅应用于本地开发。

组件格式

在以下定义中，它将请求体的内容转换为大写：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: uppercase
spec:
  type: middleware.http.uppercase
  version: v1

此组件没有需要配置的 metadata。

Dapr 配置

要应用中间件，必须在配置中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: uppercase
      type: middleware.http.uppercase

6.9 - Wasm

在 HTTP 管道中使用 Wasm 中间件

WebAssembly 是一种安全执行跨语言编译代码的机制。运行时负责加载并运行 WebAssembly 模块（Wasm），这些模块通常以 .wasm 为扩展名的二进制文件形式存在。

通过 Wasm HTTP 中间件，你可以使用自定义逻辑处理传入请求或构造响应，这些逻辑会被编译成 Wasm 二进制文件。换句话说，你可以使用外部文件扩展 Dapr，而无需将代码预编译到 daprd 二进制文件中。Dapr 内嵌了 wazero 来实现这一能力，且无需 CGO 依赖。

Wasm 二进制文件通过 URL 加载。例如，file://rewrite.wasm 会从进程当前目录加载 rewrite.wasm。在 Kubernetes 环境中，请参考如何：将 Pod 卷挂载到 Dapr 边车来配置包含 Wasm 模块的文件系统挂载。

也支持从远程 URL 获取 Wasm 二进制文件。这种情况下，URL 必须严格指向单个 Wasm 二进制文件。例如：

http://example.com/rewrite.wasm，或
https://example.com/rewrite.wasm。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: wasm
spec:
  type: middleware.http.wasm
  version: v1
  metadata:
  - name: url
    value: "file://router.wasm"
  - name: guestConfig
    value: {"environment":"production"}

规格元数据字段

用户至少需要提供一个实现 http-handler 接口的 Wasm 二进制文件。具体编译方法将在后续说明。

字段	说明	是否必填	示例
url	用于实例化的 Wasm 二进制资源 URL。支持的协议方案包括 `file://`、`http://` 和 `https://`。`file://` URL 的路径是相对于 Dapr 进程的，除非以 `/` 开头表示绝对路径。	是	`file://hello.wasm`, `https://example.com/hello.wasm`
guestConfig	传递给 Wasm 客户端的可选配置。用户可以传入任意字符串，由客户端代码自行解析。	否	`environment=production`,`{"environment":"production"}`

Dapr 配置

要使中间件生效，必须在 configuration 中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: wasm
      type: middleware.http.wasm

注意：与原生中间件相比，WebAssembly 中间件会消耗更多资源。这会导致资源约束比原生代码实现的相同逻辑更快出现。生产环境使用时应该控制最大并发。

生成 Wasm

此组件允许你使用自定义逻辑处理传入请求或生成响应，这些逻辑通过 http-handler 应用二进制接口（ABI）编译而成。handle_request 函数接收传入请求，可以根据需要操作该请求或生成响应。

要编译 Wasm，必须使用符合 http-handler 规范的客户端 SDK，例如 TinyGo。

以下是一个 TinyGo 示例：

package main

import (
	"strings"

	"github.com/http-wasm/http-wasm-guest-tinygo/handler"
	"github.com/http-wasm/http-wasm-guest-tinygo/handler/api"
)

func main() {
	handler.HandleRequestFn = handleRequest
}

// handleRequest 实现了一个简单的 HTTP 路由器。
func handleRequest(req api.Request, resp api.Response) (next bool, reqCtx uint32) {
	// 如果 URI 以 /host 开头，则去掉该前缀并分发给下一个处理器。
	if uri := req.GetURI(); strings.HasPrefix(uri, "/host") {
		req.SetURI(uri[5:])
		next = true // 继续执行宿主机上的下一个处理器。
		return
	}

	// 返回静态响应
	resp.Headers().Set("Content-Type", "text/plain")
	resp.Body().WriteString("hello")
	return // 跳过下一个处理器，因为我们已经写入了响应。
}

如果使用 TinyGo，请按以下方式编译，并将 spec 元数据字段中的 url 设置为输出文件的位置（例如 file://router.wasm）：

tinygo build -o router.wasm -scheduler=none --no-debug -target=wasi router.go`

Wasm `guestConfig` 示例

以下是如何使用 guestConfig 向 Wasm 传递配置的示例。在 Wasm 代码中，可以使用客户端 SDK 中定义的 handler.Host.GetConfig 函数来获取配置。在下面的示例中，Wasm 中间件解析了组件中定义的 JSON 配置里的 environment 字段。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: wasm
spec:
  type: middleware.http.wasm
  version: v1
  metadata:
  - name: url
    value: "file://router.wasm"
  - guestConfig
    value: {"environment":"production"}

下面是 TinyGo 的示例：

package main

import (
	"encoding/json"
	"github.com/http-wasm/http-wasm-guest-tinygo/handler"
	"github.com/http-wasm/http-wasm-guest-tinygo/handler/api"
)

type Config struct {
	Environment string `json:"environment"`
}

func main() {
	// 获取配置字节，即组件中定义的 guestConfig 值。
	configBytes := handler.Host.GetConfig()
	
	config := Config{}
	json.Unmarshal(configBytes, &config)
	handler.Host.Log(api.LogLevelInfo, "Config environment: "+config.Environment)
}

6.10 - 速率限制

使用速率限制中间件来限制每秒请求数

速率限制 HTTP 中间件允许限制每秒允许的最大 HTTP 请求数。速率限制可以保护您的应用程序免受拒绝服务（DoS）攻击。DoS 攻击可能由恶意的第三方发起，也可能由您软件中的错误引起（即"友军误伤"式 DoS 攻击）。

组件格式

在以下定义中，每秒最大请求数设置为 10：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: ratelimit
spec:
  type: middleware.http.ratelimit
  version: v1
  metadata:
  - name: maxRequestsPerSecond
    value: 10

规范元数据字段

字段	详情	示例
`maxRequestsPerSecond`	按远程 IP 计算的每秒最大请求数。组件会查看 `X-Forwarded-For` 和 `X-Real-IP` 请求头来确定调用者的 IP。	`10`

一旦达到限制，请求将失败并返回 HTTP 状态码 429: Too Many Requests。

重要

速率限制在每个 Dapr 边车中独立执行，而不是集群范围的。

或者，可以使用最大并发设置来对应用程序进行速率限制，该设置适用于所有流量，无论远程 IP、协议或路径如何。

Dapr 配置

要应用中间件，必须在配置中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: ratelimit
      type: middleware.http.ratelimit

7 - 名称解析提供程序组件规范

支持的名称解析提供程序以启用 Dapr 服务调用

以下组件为服务调用构建块提供名称解析。

名称解析组件通过配置进行配置。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Status	Component version	Since runtime version
HashiCorp Consul	Alpha	v1	1.2
NameFormat	Alpha	v1	1.16
SQLite	Alpha	v1	1.13

Kubernetes

Component	Status	Component version	Since runtime version
Kubernetes	Stable	v1	1.0

Self-Hosted

Component	Status	Component version	Since runtime version
mDNS	Stable	v1	1.0

7.1 - AWS Cloudmap

AWS Cloudmap 名称解析组件的详细信息

该组件使用 AWS Cloud Map 在 Dapr 中进行服务发现。它支持 HTTP 和 DNS 命名空间，允许服务使用 AWS Cloud Map 的服务发现能力来发现并连接到其他服务。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在配置 YAML 中，将 spec.nameResolution.component 属性设置为 "aws.cloudmap"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    version: "v1"
    configuration:
      # Required: AWS CloudMap namespace configuration (one of these is required)
      namespaceName: "my-namespace"  # The name of your CloudMap namespace
      # namespaceId: "ns-xxxxxx"    # Alternative: Use namespace ID instead of name

      # Optional: AWS authentication (choose one authentication method)
      # Option 1: Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
      # Option 2: IAM roles for Amazon EKS
      # Option 3: Explicit credentials (not recommended for production)
      accessKey: "****"
      secretKey: "****"
      sessionToken: "****"  # Optional

      # Optional: AWS region and endpoint configuration
      region: "us-west-2"
      endpoint: "http://localhost:4566"  # Optional: Custom endpoint for testing

      # Optional: Dapr configuration
      defaultDaprPort: 50002  # Default port for Dapr sidecar if not specified in instance attributes

规范说明

AWS 身份验证

该组件支持多种身份验证方法：

环境变量：
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN（可选）
IAM 角色：
- 在 AWS（EKS、EC2 等）上运行时，组件可以使用 IAM 角色
显式凭证：
- 在组件元数据中提供（不推荐在生产环境中使用）

所需权限

AWS 凭证必须具有以下权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "servicediscovery:DiscoverInstances",
                "servicediscovery:GetNamespace",
                "servicediscovery:ListNamespaces"
            ],
            "Resource": "*"
        }
    ]
}

规范配置字段

字段	是否必需	类型	默认值	描述
namespaceName	namespaceName 或 namespaceId 其中之一	string	""	AWS CloudMap 命名空间的名称
namespaceId	namespaceName 或 namespaceId 其中之一	string	""	AWS CloudMap 命名空间的 ID
region	N	string	""	AWS 区域。如果未提供，将从环境或实例元数据中确定
endpoint	N	string	""	AWS Cloud Map API 的自定义端点。适用于使用 LocalStack 进行测试
defaultDaprPort	N	number	3500	如果在实例属性中未指定，则为 Dapr 边车的默认端口

服务注册

要使用此名称解析器，您的服务必须在 AWS Cloud Map 中注册。注册实例时，确保它们具有以下属性：

必需：以下地址属性之一：
- AWS_INSTANCE_IPV4：实例的 IPv4 地址
- AWS_INSTANCE_IPV6：实例的 IPv6 地址
- AWS_INSTANCE_CNAME：实例的主机名
可选：Dapr 边车端口属性：
- DAPR_PORT：Dapr 边车正在监听的端口
- 如果未指定，组件将使用配置中的 defaultDaprPort（默认为 3500）

解析器仅返回健康的实例（具有 HEALTHY 状态的实例）以确保可靠的服务通信。

示例实例属性：

{
    "AWS_INSTANCE_IPV4": "10.0.0.1",
    "DAPR_PORT": "50002"
}

使用示例

名称解析通过 Dapr Configuration 进行配置。以下是一些使用示例。

最小配置

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    configuration:
      namespaceName: "mynamespace.dev"
      defaultDaprPort: 50002

使用 LocalStack 进行本地开发

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    configuration:
      namespaceName: "my-namespace"
      region: "us-east-1"
      endpoint: "http://localhost:4566"
      accessKey: "test"
      secretKey: "test"

7.2 - HashiCorp Consul

HashiCorp Consul 名称解析组件的详细信息

配置格式

HashiCorp Consul 在 Dapr 配置中进行设置。

在配置中，添加 nameResolution 规范并将 component 字段设置为 "consul"。

如果您使用 Dapr 边车将服务注册到 Consul，则需要以下配置：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      selfRegister: true

如果 Consul 服务注册由 Dapr 外部管理，您需要确保 Dapr 到 Dapr 的内部 gRPC 端口已添加到服务元数据中的 DAPR_PORT 下（此键可配置），并且 Consul 服务 ID 与 Dapr 应用 ID 匹配。然后您可以省略上述配置中的 selfRegister。

行为

在 init 时，Consul 组件会验证与已配置（或默认）代理的连接，或者如果配置为注册服务则注册服务。名称解析接口不支持"关闭时"模式，因此在使用 Dapr 将服务注册到 Consul 时请考虑这一点，因为它不会注销服务。

该组件通过过滤健康服务来解析目标应用，并在元数据中查找 DAPR_PORT（键可配置）以获取 Dapr 边车端口。使用 Consul service.meta 而不是 service.port，以免干扰现有的 Consul 环境。

规范配置字段

配置规范固定为 Consul API 的 v1.3.0 版本

字段	必填	类型	详情	示例
Client	N	*api.Config	配置与 Consul 代理的客户端连接。如果为空，它将使用 sdk 默认值，在这种情况下只是地址 `127.0.0.1:8500`	`10.0.4.4:8500`
QueryOptions	N	*api.QueryOptions	配置用于解析健康服务的查询，如果为空，它将默认为 `UseCache:true`	`UseCache: false`, `Datacenter: "myDC"`
Checks	N	[]*api.AgentServiceCheck	配置注册时的健康检查。如果为空，它将默认为对 Dapr 边车健康端点的单个健康检查	参见示例配置
Tags	N	`[]string`	配置注册服务时要包含的任何标签	`- "dapr"`
Meta	N	`map[string]string`	配置注册服务时要包含的任何其他元数据	`DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"`
DaprPortMetaKey	N	`string`	用于在服务解析期间从 Consul 服务元数据获取 Dapr 边车端口的键，它也将在注册期间用于在元数据中设置 Dapr 边车端口。如果为空，它将默认为 `DAPR_PORT`	`"DAPR_TO_DAPR_PORT"`
SelfRegister	N	`bool`	控制 Dapr 是否将服务注册到 Consul。名称解析接口不支持"关闭时"模式，因此如果使用 Dapr 将服务注册到 Consul，请考虑这一点，因为它不会注销服务。如果为空，它将默认为 `false`	`true`
AdvancedRegistration	N	*api.AgentServiceRegistration	通过配置完全控制服务注册。如果配置了该组件，它将忽略任何 Checks、Tags、Meta 和 SelfRegister 的配置。	参见示例配置

示例配置

基本配置

所需的最小配置如下：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"

带有其他自定义的注册

启用 SelfRegister 后，可以自定义检查、标签和元数据

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      client:
        address: "127.0.0.1:8500"
      selfRegister: true
      checks:
        - name: "Dapr Health Status"
          checkID: "daprHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
        - name: "Service Health Status"
          checkID: "serviceHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${APP_PORT}/health"
      tags:
        - "dapr"
        - "v1"
        - "${OTHER_ENV_VARIABLE}"
      meta:
        DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
        DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
      daprPortMetaKey: "DAPR_PORT"
      queryOptions:
        useCache: true
        filter: "Checks.ServiceTags contains dapr"

高级注册

配置高级注册使您能够完全控制在注册时设置所有可能的 Consul 属性。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      client:
          address: "127.0.0.1:8500"
      selfRegister: false
      queryOptions:
        useCache: true
      daprPortMetaKey: "DAPR_PORT"
      advancedRegistration:
        name: "${APP_ID}"
        port: ${APP_PORT}
        address: "${HOST_ADDRESS}"
        check:
          name: "Dapr Health Status"
          checkID: "daprHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
        meta:
          DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
          DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
        tags:
          - "dapr"

设置 HashiCorp Consul

HashiCorp 提供了有关如何为不同托管模型设置 Consul 的深入指南。查看自托管指南

HashiCorp 提供了有关如何为不同托管模型设置 Consul 的深入指南。查看 Kubernetes 指南

7.3 - Kubernetes DNS

Kubernetes DNS 名称解析组件的详细信息

配置格式

通常，Dapr 会在 Kubernetes 模式下自动配置 Kubernetes DNS 名称解析。除非需要对 Kubernetes 名称解析组件进行某些覆盖，否则无需额外配置即可将 Kubernetes DNS 用作名称解析提供程序。

如果需要覆盖，可以在 Dapr 配置 CRD 中添加 nameResolution 规范，并将 component 字段设置为 "kubernetes"。其他配置字段可以在 configuration 映射中按需设置，如下所示。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "kubernetes"
    configuration:
      clusterDomain: "cluster.local"  # 与 template 字段互斥
      template: "{{.ID}}-{{.Data.region}}.internal:{{.Port}}" # 与 clusterDomain 字段互斥

行为

该组件使用 Kubernetes 集群的 DNS 提供程序来解析目标应用程序。你可以在 Kubernetes 文档中了解更多信息。

规范配置字段

配置规范固定为 Consul API 的 v1.3.0 版本

字段	必填	类型	详情	示例
clusterDomain	N	`string`	用于解析地址的集群域。此字段与 `template` 字段互斥。	`cluster.local`
template	N	`string`	使用 text/template 解析地址时要解析的模板字符串。该模板将由 ResolveRequest 结构体中的字段填充。此字段与 `clusterDomain` 字段互斥。	`{{.ID}}-{{.Data.region}}.{{.Namespace}}.internal:{{.Port}}`

7.4 - mDNS

关于 mDNS 名称解析组件的详细信息

配置格式

组播 DNS（mDNS）在自托管模式中由 Dapr 自动配置。无需配置即可使用 mDNS 作为您的名称解析提供程序。

行为

该组件通过使用主机系统的 mDNS 服务来解析目标应用程序。您可以在此处了解更多关于 mDNS 的信息。

故障排除

在某些云提供商的虚拟网络中，例如 Microsoft Azure，mDNS 不可用。请改用其他提供程序，例如 HashiCorp Consul。

在某些企业管理的系统上，如果配置了网络过滤器/代理，macOS 上的 mDNS 可能会被禁用。如果 mDNS 被禁用且您无法在本地使用服务调用，请联系您的 IT 部门。

规范配置字段

不适用，因为在自托管模式下运行时，mDNS 由 Dapr 配置。

7.5 - Nameformat

NameFormat 名称解析组件的详细信息

名称格式名称解析器提供了一种使用带有占位符的可配置格式字符串来解析服务名称的灵活方式。这在需要将服务名称映射为遵循特定模式的可预测 DNS 名称的场景中非常有用。

如果您的服务注册表没有专用的名称解析器，但可以通过可预测的命名约定通过内部 DNS 名称公开服务，请考虑使用此名称解析器。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在配置 YAML 中，将 spec.nameResolution.component 属性设置为 "nameformat"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "nameformat"
    configuration:
      format: "service-{appid}.default.svc.cluster.local"  # 替换为所需的格式模式

规格配置字段

字段	必填	详情	示例
format	Y	用于名称解析的格式字符串。必须包含 `{appid}` 占位符，该占位符将被替换为实际的服务名称。	`"service-{appid}.default.svc.cluster.local"`

示例

配置为 format: "service-{appid}.default.svc.cluster.local" 时，解析器会将服务名称转换如下：

服务 ID “myapp” → “service-myapp.default.svc.cluster.local”
服务 ID “frontend” → “service-frontend.default.svc.cluster.local”

注意事项

不允许使用空服务 ID，否则会导致错误。
必须在配置中提供格式字符串
格式字符串必须至少包含一个 {appid} 占位符

7.6 - SQLite

SQLite 名称解析组件的详细信息

作为 mDNS 的替代方案，SQLite 名称解析组件可用于在单节点环境和本地开发场景中运行 Dapr。属于集群一部分的 Dapr 边车将其信息存储在本地机器上的 SQLite 数据库中。

注意

此组件已针对所有 Dapr 实例在同一台物理机上运行的场景进行了优化，数据库通过同一本地挂载磁盘访问。在通过网络（包括 SMB/NFS）访问的数据库文件上使用 SQLite nameresolver 可能会导致数据损坏等问题，并且不受支持。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在 Configuration YAML 中，将 spec.nameResolution.component 属性设置为 "sqlite"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

这是 Configuration 资源的基本示例：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "sqlite"
    version: "v1"
    configuration:
      connectionString: "/home/user/.dapr/nr.db"

Spec 配置字段

使用 SQLite 名称解析器组件时，spec.nameResolution.configuration 字典包含以下选项：

字段	必填	类型	详情	示例
`connectionString`	Y	`string`	SQLite 数据库的连接字符串。通常，这是磁盘上文件的路径，相对于当前工作目录，或绝对路径。	`"nr.db"`（相对于工作目录），`"/home/user/.dapr/nr.db"`
`updateInterval`	N	Go duration（作为 `string`）	活跃的 Dapr 边车更新其在数据库中的状态的间隔，该状态用作健康检查。较小的间隔可降低应用程序离线时返回陈旧数据的可能性，但会增加数据库的负载。必须至少比 `timeout` 大 1s。带小数秒的值会被截断（例如，`1500ms` 变为 `1s`）。默认值：`5s`	`"2s"`
`timeout`	N	Go duration（作为 `string`）。必须至少为 1s。	数据库操作的超时时间。整数被解释为秒数。默认值为 `1s`	`"2s"`，`2`
`tableName`	N	`string`	存储数据的表的名称。如果表不存在，则由 Dapr 创建该表。默认值为 `hosts`。	`"hosts"`
`metadataTableName`	N	`string`	Dapr 用于存储组件元数据的表的名称。如果表不存在，则由 Dapr 创建该表。默认值为 `metadata`。	`"metadata"`
`cleanupInterval`	N	Go duration（作为 `string`）	从数据库中删除陈旧记录的间隔。默认值：`1h`（1 小时）	`"10m"`
`busyTimeout`	N	Go duration（作为 `string`）	在 SQLite 数据库当前正忙于服务另一个请求时，在返回"数据库繁忙"错误之前等待的间隔。这是一个高级设置。 `busyTimeout` 控制锁定在 SQLite 中如何工作。对于 SQLite，写入是独占的，因此每次任何应用程序写入时数据库都会被锁定。如果另一个应用程序尝试写入，它会等待最多 `busyTimeout`，然后返回"数据库繁忙"错误。但是 `timeout` 设置控制整个操作的超时时间。例如，如果查询在数据库获取锁定后"挂起"（因此繁忙超时被清除），那么 `timeout` 生效。默认值：`800ms`（800 毫秒）	`"100ms"`
`disableWAL`	N	`bool`	如果设置为 true，则禁用 SQLite 数据库日志记录的预写日志记录。这仅适用于高级场景	`true`，`false`

8 - 发布订阅代理组件规范

与 Dapr 接口的受支持的发布订阅代理

下表列出了 Dapr 发布订阅构建块支持的发布和订阅代理。了解如何为 Dapr 发布和订阅设置不同的代理。

发布订阅组件重试与入站弹性

每个发布订阅组件都有自己的内置重试行为，这是消息代理解决方案特有的，与 Dapr 无关。在显式应用 Dapr 弹性策略之前，请确保您了解所使用的发布订阅组件的隐式重试策略。Dapr 弹性不会覆盖这些内置重试，而是对其进行增强，这可能会导致消息的重复聚类。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Status	Component version	Since runtime version
Apache Kafka	Stable	v1	1.5
In-memory	Stable	v1	1.7
JetStream	Beta	v1	1.10
KubeMQ	Beta	v1	1.10
MQTT3	Stable	v1	1.7
Pulsar	Stable	v1	1.10
RabbitMQ	Stable	v1	1.7
Redis Streams	Stable	v1	1.0
RocketMQ	Alpha	v1	1.8
Solace-AMQP	Beta	v1	1.10

Amazon Web Services (AWS)

Component	Status	Component version	Since runtime version
AWS SNS/SQS	Stable	v1	1.10

Google Cloud Platform (GCP)

Component	Status	Component version	Since runtime version
GCP Pub/Sub	Stable	v1	1.11

Microsoft Azure

Component	Status	Component version	Since runtime version
Azure Event Hubs	Stable	v1	1.8
Azure Service Bus Queues	Beta	v1	1.10
Azure Service Bus Topics	Stable	v1	1.0

8.1 - Apache Kafka

Apache Kafka 发布订阅组件的详细文档

组件格式

要设置 Apache Kafka 发布订阅，请创建类型为 pubsub.kafka 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。请阅读操作指南：发布与订阅指南以了解如何创建和应用发布订阅配置。

所有组件元数据字段值都可以携带模板化元数据值，这些值在 Dapr 边车启动时解析。例如，您可以选择使用 {namespace} 作为 consumerGroup，以支持在不同的命名空间中使用相同的 appId 和相同的主题，如本文中所述。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "{namespace}"
  - name: consumerID # 可选。如果未提供，运行时将创建一个。
    value: "channel1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "password"
  - name: saslUsername # 如果 authType 为 `password` 则必需。
    value: "adminuser"
  - name: saslPassword # 如果 authType 为 `password` 则必需。
    secretKeyRef:
      name: kafka-secrets
      key: saslPasswordSecret
  - name: saslMechanism
    value: "SHA-512"
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 2.0.0
  - name: disableTls # 可选。禁用 TLS。这对生产环境不安全！！您应该阅读 `Mutual TLS` 部分以了解如何使用 TLS。
    value: "true"
  - name: consumerFetchMin # 可选。高级设置。单个请求中获取的最小消息字节数 - 代理将等待直到至少有这么多数据可用。
    value: 1
  - name: consumerFetchDefault # 可选。高级设置。每个请求从代理获取的默认消息字节数。
    value: 2097152
  - name: channelBufferSize # 可选。高级设置。内部和外部通道中要缓冲的事件数量。
    value: 512
  - name: consumerGroupRebalanceStrategy # 可选。高级设置。用于消费者组重新平衡的策略。
    value: sticky
  - name: schemaRegistryURL # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry URL。
    value: http://localhost:8081
  - name: schemaRegistryAPIKey # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry API 密钥。
    value: XYAXXAZ
  - name: schemaRegistryAPISecret # 可选。使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API 密钥。
    value: "ABCDEFGMEADFF"
  - name: schemaCachingEnabled # 可选。使用 Schema Registry Avro 序列化/反序列化时。启用 schema 缓存。
    value: true
  - name: schemaLatestVersionCacheTTL # 可选。使用 Schema Registry Avro 序列化/反序列化时。使用最新可用 schema 发布消息时的 schema 缓存 TTL。
    value: 5m
  - name: useAvroJson # 可选。启用 Avro JSON schema 进行序列化，而不是默认的 Standard JSON。仅当订阅使用 valueSchemaType=Avro 时适用
    value: "true"
  - name: escapeHeaders # 可选。
    value: false

有关使用 secretKeyRef 的详细信息，请参阅如何在组件中引用密钥指南。

规格元数据字段

字段	必需	详细信息	示例
brokers	Y	以逗号分隔的 Kafka 代理列表。	`"localhost:9092,dapr-kafka.myapp.svc.cluster.local:9093"`
consumerGroup	N	要监听的 Kafka 消费者组。发布到主题的每条记录都会传递给订阅该主题的每个消费者组中的一个消费者。如果提供了 `consumerGroup` 的值，任何 `consumerID` 的值都将被忽略 - 取而代之的是，将设置消费者组和随机唯一标识符的组合作为 `consumerID`。	`"group1"`
consumerID	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息只由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）值。如果提供了 `consumerGroup` 的值，任何 `consumerID` 的值都将被忽略 - 取而代之的是，将设置消费者组和随机唯一标识符的组合作为 `consumerID`。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式的值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
clientID	N	用户提供的字符串，随每个请求发送到 Kafka 代理，用于日志记录、调试和审计目的。默认为 Kubernetes 模式的 `"namespace.appID"` 或自托管模式的 `"appID"`。	`"my-namespace.my-dapr-app"`, `"my-dapr-app"`
authRequired	N	已弃用使用 SASL 与 Kafka 代理进行身份验证。	`"true"`, `"false"`
authType	Y	配置或禁用身份验证。支持的值：`none`、`password`、`mtls`、`oidc`、`oidc_private_key_jwt` 或 `awsiam`	`"password"`, `"none"`
saslUsername	N	用于身份验证的 SASL 用户名。仅当 `authType` 设置为 `"password"` 时才需要。	`"adminuser"`
saslPassword	N	用于身份验证的 SASL 密码。可以是 `secretKeyRef` 以使用密钥引用。仅当 `authType` 设置为 `"password"` 时才需要。	`""`, `"KeFg23!"`
saslMechanism	N	您希望使用的 SASL 身份验证机制。仅当 `authType` 设置为 `"password"` 时才需要。默认为 `PLAINTEXT`	`"SHA-512", "SHA-256", "PLAINTEXT"`
initialOffset	N	如果之前未提交偏移量，则使用的初始偏移量。应该是 “newest” 或 “oldest”。默认为 “newest”。	`"oldest"`
maxMessageBytes	N	单个 Kafka 消息允许的最大字节大小。默认为 1024。	`2048`
consumeRetryInterval	N	尝试使用主题时重试之间的间隔。将没有后缀的数字视为毫秒。默认为 100ms。	`200ms`
consumeRetryEnabled	N	通过设置 `"false"` 来禁用消费重试	`"true"`, `"false"`
version	N	Kafka 集群版本。默认为 2.0.0。请注意，如果您使用的是 Azure EventHubs with Kafka，则必须将其设置为 `1.0.0`。	`0.10.2.0`
caCert	N	证书颁发机构证书，使用 TLS 所需。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	N	客户端证书，`authType` `mtls` 所需。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	N	客户端密钥，`authType` `mtls` 所需。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`
skipVerify	N	跳过 TLS 验证，不建议在生产环境中使用。默认为 `"false"`	`"true"`, `"false"`
disableTls	N	禁用传输安全性的 TLS。要禁用，您需要将值设置为 `"true"`。不建议在生产环境中使用。默认为 `"false"`。	`"true"`, `"false"`
oidcTokenEndpoint	N	OAuth2 身份提供者访问令牌端点的完整 URL。当 `authType` 设置为 `oidc` 时需要	“https://identity.example.com/v1/token"
oidcClientID	N	在身份提供者中配置的 OAuth2 客户端 ID。当 `authType` 设置为 `oidc` 时需要	`dapr-kafka`
oidcClientSecret	N	在身份提供者中配置的 OAuth2 客户端密钥。当 `authType` 设置为 `oidc` 时需要	`"KeFg23!"`
oidcScopes	N	使用访问令牌请求的 OAuth2/OIDC 范围的逗号分隔列表。当 `authType` 设置为 `oidc` 或 `oidc_private_key_jwt` 时建议使用。默认为 `"openid"`	`"openid,kafka-prod"`
oidcClientAssertionCert	N	用于身份验证的 OAuth2 客户端断言证书。当 `authType` 设置为 `oidc_private_key_jwt` 时需要。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"`
oidcClientAssertionKey	N	用于身份验证的 OAuth2 客户端断言密钥。当 `authType` 设置为 `oidc_private_key_jwt` 时需要。可以是 `secretKeyRef` 以使用密钥引用	`"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"`
oidcResource	N	使用访问令牌请求的 OAuth2 资源。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"api://kafka"`
oidcAudience	N	使用访问令牌请求的 OAuth2 受众。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"http://<idp-host>/realms/local"`
oidcKid	N	使用访问令牌请求的 OAuth2 密钥 ID（kid）。当 `authType` 设置为 `oidc_private_key_jwt` 时建议使用。	`"1234567890"`
oidcExtensions	N	包含使用访问令牌请求的 OAuth2/OIDC 扩展的 JSON 编码字典的字符串	`{"cluster":"kafka","poolid":"kafkapool"}`
awsRegion	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘region’。部署 Kafka 集群的 AWS 区域。当 `authType` 设置为 `awsiam` 时需要	`us-west-1`
awsAccessKey	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘accessKey’。与 IAM 账户关联的 AWS 访问密钥。	`"accessKey"`
awsSecretKey	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘secretKey’。与访问密钥关联的密钥。	`"secretKey"`
awsSessionToken	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅当您使用临时安全凭证时才需要会话令牌。	`"sessionToken"`
awsIamRoleArn	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘assumeRoleArn’。有权访问 AWS Managed Streaming for Apache Kafka (MSK) 的 IAM 角色。这是使用 AWS 凭证对 MSK 进行身份验证的另一种选择。	`"arn:aws:iam::123456789:role/mskRole"`
awsStsSessionName	N	这保持与现有字段的向后兼容性。它将从 Dapr 1.17 开始弃用。请改用 ‘sessionName’。表示承担角色的会话名称。	`"DaprDefaultSession"`
schemaRegistryURL	N	使用 Schema Registry Avro 序列化/反序列化时需要。Schema Registry URL。	`http://localhost:8081`
schemaRegistryAPIKey	N	使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API 密钥。	`XYAXXAZ`
schemaRegistryAPISecret	N	使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API 密钥。	`ABCDEFGMEADFF`
schemaCachingEnabled	N	使用 Schema Registry Avro 序列化/反序列化时。启用 schema 缓存。默认为 `true`	`true`
schemaLatestVersionCacheTTL	N	使用 Schema Registry Avro 序列化/反序列化时。使用最新可用 schema 发布消息时的 schema 缓存 TTL。默认为 5 分钟	`5m`
useAvroJson	N	启用 Avro JSON schema 进行序列化，而不是默认的 Standard JSON。仅当订阅使用 valueSchemaType=Avro 时适用。默认为 `"false"`	`"true"`
clientConnectionTopicMetadataRefreshInterval	N	客户端连接的主题元数据与代理刷新的间隔，以 Go 持续时间表示。默认为 `9m`。	`"4m"`
clientConnectionKeepAliveInterval	N	客户端连接在与代理保持活动状态的最大时间（以 Go 持续时间表示），然后关闭连接。零值（默认）表示无限期保持活动。	`"4m"`
consumerFetchMin	N	单个请求中获取的最小消息字节数 - 代理将等待直到至少有这么多数据可用。默认为 `1`，因为 `0` 会导致在没有可用消息时消费者空转。等效于 JVM 的 `fetch.min.bytes`。	`"2"`
consumerFetchDefault	N	每个请求从代理获取的默认消息字节数。默认为 `"1048576"` 字节。	`"2097152"`
channelBufferSize	N	在内部和外部通道中缓冲的事件数量。这允许生产者和消费者在用户代码工作时在后台继续处理某些消息，从而大大提高吞吐量。默认为 `256`。	`"512"`
heartbeatInterval	N	向消费者协调器发送心跳之间的间隔。该值最多应设置为 `sessionTimeout` 值的 1/3。默认为 “3s”。	`"5s"`
sessionTimeout	N	使用 Kafka 的组管理功能时用于检测客户端故障的超时时间。如果代理在此会话超时到期前未能收到消费者的任何心跳，则消费者将被移除并启动重新平衡。默认为 “10s”。	`"20s"`
consumerGroupRebalanceStrategy	N	用于消费者组重新平衡的策略。支持的值：`range`、`sticky`、`roundrobin`。默认为 `range`	`"sticky"`
escapeHeaders	N	启用消费者接收的消息头值的 URL 转义。允许接收通常在 HTTP 头中不允许的特殊字符的内容。默认为 `false`。	`true`
excludeHeaderMetaRegex	N	一个正则表达式，用于在消费消息时排除将某些键从头转换为元数据，以及在发布消息时从元数据转换为头。此功能避免了主题消费者的意外下游副作用。	‘"^valueSchemaType$”’

上述的 secretKeyRef 引用了 kubernetes secrets store 来访问 tls 信息。访问这里以了解更多有关如何配置密钥存储组件的信息。

注意

当使用 Azure EventHubs with Kafka 时，元数据 version 必须设置为 1.0.0。

身份验证

Kafka 支持多种身份验证方案，Dapr 支持其中几种：SASL 密码、mTLS、OIDC/OAuth2。随着新增的身份验证方法，authRequired 字段已从 v1.6 版本开始弃用，而应使用 authType 字段。如果 authRequired 设置为 true，Dapr 将尝试根据 saslPassword 的值正确配置 authType。authType 的有效值为：

none
password
certificate
mtls
oidc
oidc_private_key_jwt
awsiam

注意

authType 仅用于身份验证。授权仍在 Kafka 中配置，但 awsiam 除外，它还可以驱动在 AWS IAM 中配置的授权决策。

无身份验证

将 authType 设置为 none 将禁用任何身份验证。这在生产环境中不推荐。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-noauth
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "none"
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0
  - name: disableTls
    value: "true"

SASL 密码

将 authType 设置为 password 可启用 SASL 身份验证。这需要设置 saslUsername 和 saslPassword 字段。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-sasl
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "password"
  - name: saslUsername # 如果 authType 为 `password` 则必需。
    value: "adminuser"
  - name: saslPassword # 如果 authType 为 `password` 则必需。
    secretKeyRef:
      name: kafka-secrets
      key: saslPasswordSecret
  - name: saslMechanism
    value: "SHA-512"
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0
  - name: caCert
    secretKeyRef:
      name: kafka-tls
      key: caCert

双向 TLS

将 authType 设置为 mtls 使用 x509 客户端证书（clientCert 字段）和密钥（clientKey 字段）进行身份验证。请注意，mTLS 作为一种身份验证机制与使用 TLS 通过加密保护传输层是不同的。mTLS 需要 TLS 传输（意味着 disableTls 必须为 false），但保护传输层不需要使用 mTLS。有关配置底层 TLS 传输的信息，请参阅使用 TLS 通信。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-mtls
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "mtls"
  - name: caCert
    secretKeyRef:
      name: kafka-tls
      key: caCert
  - name: clientCert
    secretKeyRef:
      name: kafka-tls
      key: clientCert
  - name: clientKey
    secretKeyRef:
      name: kafka-tls
      key: clientKey
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0

OAuth2 或 OpenID Connect

将 authType 设置为 oidc 可通过 OAUTHBEARER 机制启用 SASL 身份验证。这支持从外部 OAuth2 或 OIDC 身份提供者指定不记名令牌。目前，仅支持 client_credentials 授权。

将 oidcTokenEndpoint 配置为身份提供者访问令牌端点的完整 URL。

将 oidcClientID 和 oidcClientSecret 设置为在身份提供者中配置的客户端凭证。

如果在组件配置中指定了 caCert，该证书将附加到系统 CA 信任中以验证身份提供者证书。同样，如果在组件配置中指定了 skipVerify，则在访问身份提供者时也将跳过验证。

默认情况下，为令牌请求的唯一范围是 openid；强烈建议通过 oidcScopes 以逗号分隔的列表指定其他范围，并由 Kafka 代理进行验证。如果不使用其他范围来缩小访问令牌的有效性，受损的 Kafka 代理可能会重放令牌以 Dapr clientID 的身份访问其他服务。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "oidc"
  - name: oidcTokenEndpoint # 如果 authType 为 `oidc` 则必需。
    value: "https://identity.example.com/v1/token"
  - name: oidcClientID      # 如果 authType 为 `oidc` 则必需。
    value: "dapr-myapp"
  - name: oidcClientSecret  # 如果 authType 为 `oidc` 则必需。
    secretKeyRef:
      name: kafka-secrets
      key: oidcClientSecret
  - name: oidcScopes        # 如果 authType 为 `oidc` 则建议使用。
    value: "openid,kafka-dev"
  - name: caCert            # 也应用于验证 OIDC 提供者证书
    secretKeyRef:
      name: kafka-tls
      key: caCert
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0

OAuth2 私钥 JWT

将 authType 设置为 oidc_private_key_jwt 可通过 OAUTHBEARER 机制启用 SASL 身份验证。这支持从外部 OAuth2 或 OIDC 身份提供者指定私钥 JWT。目前，仅支持 client_credentials 授权。

将 oidcTokenEndpoint 配置为身份提供者访问令牌端点的完整 URL。

将 oidcClientID 设置为客户端 ID，oidcClientAssertionCert 设置为客户端断言证书，oidcClientAssertionKey 设置为在身份提供者中配置的客户端断言密钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "oidc_private_key_jwt"
  - name: oidcTokenEndpoint # 如果 authType 为 `oidc_private_key_jwt` 则必需。
    value: "https://identity.example.com/v1/token"
  - name: oidcClientID      # 如果 authType 为 `oidc_private_key_jwt` 则必需。
    value: "dapr-myapp"
  - name: oidcClientAssertionCert # 如果 authType 为 `oidc_private_key_jwt` 则必需。
    secretKeyRef:
      name: kafka-tls
      key: oidcClientAssertionCert
  - name: oidcClientAssertionKey # 如果 authType 为 `oidc_private_key_jwt` 则必需。
    secretKeyRef:
      name: kafka-tls
      key: oidcClientAssertionKey
  - name: oidcScopes        # 如果 authType 为 `oidc_private_key_jwt` 则建议使用。
    value: "openid,kafka-dev"
  - name: oidcResource # 可选。
    value: "api://kafka"
  - name: oidcAudience # 可选。
    value: "http://<idp-host>/realms/local"
  - name: oidcKid # 可选。
    value: "1234567890"
  - name: caCert # 可选。
    secretKeyRef:
      name: kafka-tls
      key: caCert
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0

AWS IAM

支持使用 AWS IAM 与 MSK 进行身份验证。将 authType 设置为 awsiam 使用 AWS SDK 生成身份验证令牌进行身份验证。

注意

唯一必需的元数据字段是 region。如果未提供 accessKey 和 secretKey，您可以使用 AWS IAM 服务账户角色对 Kafka 集群进行无密码身份验证。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-awsiam
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "awsiam"
  - name: region # 必需。
    value: "us-west-1"
  - name: accessKey # 可选。
    value: <AWS_ACCESS_KEY>
  - name: secretKey # 可选。
    value: <AWS_SECRET_KEY>
  - name: sessionToken # 可选。
    value: <AWS_SESSION_KEY>
  - name: assumeRoleArn # 可选。
    value: "arn:aws:iam::123456789:role/mskRole"
  - name: sessionName # 可选。
    value: "DaprDefaultSession"

使用 TLS 通信

默认情况下，启用 TLS 以保护到 Kafka 的传输层。要禁用 TLS，请将 disableTls 设置为 true。启用 TLS 后，您可以使用 skipVerify 禁用验证（在生产环境中不推荐）并使用 caCert 指定受信任的 TLS 证书颁发机构（CA）来控制服务器证书验证。如果未指定 caCert，将使用系统 CA 信任。要配置 mTLS 身份验证，请参阅_身份验证_下的部分。以下是配置为使用传输层 TLS 的 Kafka 发布订阅组件的示例：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "certificate"
  - name: consumeRetryInterval # 可选。
    value: 200ms
  - name: heartbeatInterval # 可选。
    value: 5s
  - name: sessionTimeout # 可选。
    value: 15s
  - name: version # 可选。
    value: 0.10.2.0
  - name: maxMessageBytes # 可选。
    value: 1024
  - name: caCert # 证书颁发机构证书。
    secretKeyRef:
      name: kafka-tls
      key: caCert
auth:
  secretStore: <SECRET_STORE_NAME>

从多个主题消费

当使用单个发布/订阅组件从多个主题消费时，无法保证消费者组中的消费者如何在主题分区之间进行平衡。

例如，假设您订阅了两个主题，每个主题有 10 个分区，并且您有 20 个服务副本从这两个主题消费。无法保证 10 个会被分配给第一个主题，10 个会被分配给第二个主题。相反，分区可能会不均匀地划分，第一个主题分配超过 10 个，其余的分配给第二个主题。

这可能导致监听第一个主题的消费者空闲，而第二个主题的消费者过度扩展，反之亦然。当使用自动伸缩器（如 HPA 或 KEDA）时，也会观察到相同的行为。

如果您遇到此特定问题，建议您为主题配置单个发布/订阅组件，并为每个组件唯一定义消费者组。这可以确保您的服务的所有副本都完全分配给唯一的消费者组，其中每个消费者组针对一个特定主题。

例如，您可以使用以下配置定义两个 Dapr 组件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-topic-one
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: consumerGroup
    value: "{appID}-topic-one"

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-topic-two
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: consumerGroup
    value: "{appID}-topic-two"

发送和接收多条消息

Apache Kafka 组件支持使用批量发布/订阅 API 在单个操作中发送和接收多条消息。

配置批量订阅

订阅主题时，您可以配置 bulkSubscribe 选项。有关更多详细信息，请参阅批量订阅消息。了解更多有关批量订阅 API的信息。

Apache Kafka 支持以下批量元数据选项：

配置	默认值
`maxAwaitDurationMs`	`10000` (10s)
`maxMessagesCount`	`80`

每次调用的元数据字段

分区键

调用 Kafka 发布/订阅时，可以通过在请求 URL 中使用 metadata 查询参数来提供可选的分区键。

参数名称可以是 partitionKey 或 __key

示例：

curl -X POST http://localhost:3500/v1.0/publish/myKafka/myTopic?metadata.partitionKey=key1 \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

消息头

所有其他元数据键/值对（不是 partitionKey 或 __key）都作为 Kafka 消息的头设置。以下是设置消息的 correlationId 的示例。

curl -X POST http://localhost:3500/v1.0/publish/myKafka/myTopic?metadata.correlationId=myCorrelationID&metadata.partitionKey=key1 \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

消费者端接收的 Kafka 发布订阅特殊消息头

消费消息时，特殊消息元数据会作为头自动传递。这些包括：

__key：消息键（如果有）
__topic：消息的主题
__partition：消息的分区号
__offset：消息在分区中的偏移量
__timestamp：消息的时间戳

您可以在消费者端点中按如下方式访问它们：

from fastapi import APIRouter, Body, Response, status
import json
import sys

app = FastAPI()

router = APIRouter()


@router.get('/dapr/subscribe')
def subscribe():
    subscriptions = [{'pubsubname': 'pubsub',
                      'topic': 'my-topic',
                      'route': 'my_topic_subscriber',
                      }]
    return subscriptions

@router.post('/my_topic_subscriber')
def my_topic_subscriber(
      key: Annotated[str, Header(alias="__key")],
      offset: Annotated[int, Header(alias="__offset")],
      event_data=Body()):
    print(f"key={key} - offset={offset} - data={event_data}", flush=True)
      return Response(status_code=status.HTTP_200_OK)

app.include_router(router)

接收带有特殊字符的消息头

消费者应用程序可能需要接收包含特殊字符的消息头，这可能导致 HTTP 协议验证错误。 HTTP 头值必须遵循规范，因此不允许某些字符。了解更多有关协议的信息。在这种情况下，您可以启用 escapeHeaders 配置设置，该设置使用 URL 转义在消费者端对头值进行编码。

注意

使用此设置时，接收到的消息头是 URL 转义的，您需要 URL “un-escape”（转义）它以获取原始值。

将 escapeHeaders 设置为 true 以进行 URL 转义。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-escape-headers
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选。用于输入绑定。
    value: "group1"
  - name: clientID # 可选。被 Kafka 代理用作客户端追踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需。
    value: "none"
  - name: escapeHeaders
    value: "true"

Avro Schema Registry 序列化/反序列化

您可以配置发布/订阅以使用 Avro 二进制序列化发布或消费编码的数据，利用 Apache Schema Registry（例如，Confluent Schema Registry、Apicurio）。

配置

重要

目前，仅支持消息值序列化/反序列化。由于不支持 Cloud Events，因此在发布 Avro 消息时必须传递 rawPayload=true 元数据。

请注意，消费者不应设置 rawPayload=true，因为消息值将被包装到 CloudEvent 中并进行 base64 编码。将 rawPayload 保留为默认值（即 false）会将 Avro 解码的消息作为 JSON 负载发送到应用程序。

当将 useAvroJson 组件元数据设置为 true 时，入站/出站 Avro 二进制会被转换为/从 Avro JSON 编码。当需要准确的类型映射时，这可能更可取。默认是标准 JSON，通常更容易绑定到应用程序中的本机类型。

配置 Kafka 发布/订阅组件元数据时，您必须定义：

Schema registry URL
API 密钥/密钥（如果适用）

Schema 主题使用标准命名约定从主题名称自动派生。例如，对于名为 my-topic 的主题，schema 主题将是 my-topic-value。在服务内与消息负载交互时，它采用 JSON 格式。负载在 Dapr 组件内透明地序列化/反序列化。日期/日期时间字段必须作为其 Epoch Unix 时间戳等效值传递（而不是典型的 Iso8601）。例如：

2024-01-10T04:36:05.986Z 应作为 1704861365986 传递（自 1970 年 1 月 1 日以来的毫秒数）
2024-01-10 应作为 19732 传递（自 1970 年 1 月 1 日以来的天数）

发布 Avro 消息

为了向 Kafka 发布/订阅组件指示消息应使用 Avro 序列化，必须将 valueSchemaType 元数据设置为 Avro。

curl -X "POST" http://localhost:3500/v1.0/publish/pubsub/my-topic?metadata.rawPayload=true&metadata.valueSchemaType=Avro -H "Content-Type: application/json" -d '{"order_number": "345", "created_date": 1704861365986}'

from dapr.clients import DaprClient

with DaprClient() as d:
    req_data = {
        'order_number': '345',
        'created_date': 1704861365986
    }
    # Create a typed message with content type and body
    resp = d.publish_event(
        pubsub_name='pubsub',
        topic_name='my-topic',
        data=json.dumps(req_data),
        publish_metadata={'rawPayload': 'true', 'valueSchemaType': 'Avro'}
    )
    # Print the request
    print(req_data, flush=True)

订阅 Avro 主题

为了向 Kafka 发布/订阅组件指示消息应使用 Avro 反序列化，必须在订阅元数据中将 valueSchemaType 元数据设置为 Avro。

from fastapi import APIRouter, Body, Response, status
import json
import sys

app = FastAPI()

router = APIRouter()


@router.get('/dapr/subscribe')
def subscribe():
    subscriptions = [{'pubsubname': 'pubsub',
                      'topic': 'my-topic',
                      'route': 'my_topic_subscriber',
                      'metadata': {
                          'valueSchemaType': 'Avro',
                      } }]
    return subscriptions

@router.post('/my_topic_subscriber')
def my_topic_subscriber(event_data=Body()):
    print(event_data, flush=True)
      return Response(status_code=status.HTTP_200_OK)

app.include_router(router)

发布需要自定义元数据的消息时避免下游副作用

Dapr 允许通过设置自定义发布元数据来自定义发布行为。

例如，要以 avro 格式发布，需要设置 valueSchemaType=Avro 元数据。

然而，默认情况下，这些元数据项会被转换为 Kafka 头并随消息一起发布。这种默认行为对于在发布者/消费者链中转发追踪头非常有用。

但在某些情况下，它会产生不必要的副作用。假设您使用 Dapr 使用上述头消费 Avro 消息。如果此消息无法成功消费并配置为发送到死信主题，则在发布到死信主题时会自动转发 valueSchemaType=Avro，需要设置与此主题关联的 schema。在许多情况下，最好仅以 JSON 格式发布死信消息，因为无法遵守确定的 schema。

要避免此行为，可以配置 kafka-pubsub 组件以排除某些元数据键被转换为/从头。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-exclude-metadata
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需。Kafka 代理连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: authType # 必需。
    value: "none"
  - name: excludeMetaHeaderRegex
    value: "^valueSchemaType$" # 可选。排除 `valueSchemaType` 头被发布到头并转换为元数据

覆盖默认消费者组重新平衡

在 Kafka 中，重新平衡策略确定如何在消费者组内将分区分配给消费者。默认策略是 “range”，但也可以使用 “roundrobin” 和 “sticky”。

Range：分区根据其字典顺序分配给消费者。如果您有三个分区（0、1、2）和两个消费者（A、B），消费者 A 可能会获得分区 0 和 1，而消费者 B 获得分区 2。
RoundRobin：分区以循环方式分配给消费者。在上面的相同示例中，消费者 A 可能会获得分区 0 和 2，而消费者 B 获得分区 1。
Sticky：此策略旨在尽可能保留以前的分配，同时仍保持平衡的分配。如果消费者离开或加入组，只会重新分配受影响的分区，从而最大限度地减少中断。

选择策略：

Range：简单易懂且易于实现，但如果分区大小差异很大，可能会导致分布不均匀。
RoundRobin：在许多情况下提供了良好的平衡，但如果消息键分布不均匀，可能不是最佳选择。
Sticky：通常首选，因为它能够在重新平衡期间最大限度地减少中断，尤其是在处理大量分区或频繁的消费者组更改时。

创建 Kafka 实例

您可以使用这个 Docker 镜像在本地运行 Kafka。要在不使用 Docker 的情况下运行，请参阅这里的入门指南。

要在 Kubernetes 上运行 Kafka，您可以使用任何 Kafka 运算符，例如 Strimzi。

8.2 - AWS SNS/SQS

AWS SNS/SQS 发布订阅组件的详细文档

组件格式

要设置 AWS SNS/SQS 发布订阅，请创建类型为 pubsub.aws.snssqs 的组件。

默认情况下，AWS SNS/SQS 组件：

生成 SNS 主题
预配 SQS 队列
配置队列到主题的订阅

注意

如果你只有发布者而没有订阅者，则仅创建 SNS 主题。

但是，如果你有订阅者，则会生成 SNS、SQS 及其动态或静态订阅。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: snssqs-pubsub
spec:
  type: pubsub.aws.snssqs
  version: v1
  metadata:
    - name: accessKey
      value: "AKIAIOSFODNN7EXAMPLE"
    - name: secretKey
      value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    - name: region
      value: "us-east-1"
    # - name: consumerID # 可选。如果未提供，运行时将创建一个。
    #   value: "channel1"
    # - name: endpoint # 可选。 
    #   value: "http://localhost:4566"
    # - name: sessionToken  # 可选（如果使用 AssignedRole 则为必需；例如，临时 accessKey 和 secretKey）
    #   value: "TOKEN"
    # - name: messageVisibilityTimeout # 可选
    #   value: 10
    # - name: messageRetryLimit # 可选
    #   value: 10
    # - name: messageReceiveLimit # 可选
    #   value: 10
    # - name: sqsDeadLettersQueueName # 可选
    # - value: "myapp-dlq"
    # - name: messageWaitTimeSeconds # 可选
    #   value: 1
    # - name: messageMaxNumber # 可选
    #   value: 10
    # - name: fifo # 可选
    #   value: "true"
    # - name: fifoMessageGroupID # 可选
    #   value: "app1-mgi"
    # - name: disableEntityManagement # 可选
    #   value: "false"
    # - name: disableDeleteOnRetryLimit # 可选
    #   value: "false"
    # - name: assetsManagementTimeoutSeconds # 可选
    #   value: 5
    # - name: concurrencyMode # 可选
    #   value: "single"
    # - name: concurrencyLimit # 可选
    #   value: "0"

警告

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
accessKey	Y	具有对 SNS 和 SQS 适当权限的 AWS 账户/角色的 ID（见下文）	`"AKIAIOSFODNN7EXAMPLE"`
secretKey	Y	AWS 用户/角色的密钥。如果使用 `AssumeRole` 访问，你还需要提供 `sessionToken`	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
region	Y	SNS/SQS 资源所在或将要创建的 AWS 区域。有关有效区域，请参阅此页面。确保 SNS 和 SQS 在该区域可用	`"us-east-1"`
consumerID	N	消费者 ID（消费者标签）将一个或多个消费者组织到一个组中。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）的值。请参阅发布订阅代理组件文件以了解 ConsumerID 如何自动生成。	可以设置为字符串值（如上面示例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看你可以在组件元数据中使用的所有模板标签。
endpoint	N	组件要使用的 AWS 端点。仅用于本地开发，例如使用 localstack。当针对生产环境 AWS 运行时，不需要 `endpoint`	`"http://localhost:4566"`
sessionToken	N	要使用的 AWS 会话令牌。仅当你使用临时安全凭证时才需要会话令牌	`"TOKEN"`
messageReceiveLimit	N	在处理消息失败后，接收消息的次数，达到该次数后，会将该消息从队列中移除。如果指定了 `sqsDeadLettersQueueName`，`messageReceiveLimit` 是在处理消息失败后接收消息的次数，达到该次数后，会将该消息移动到 SQS 死信队列。默认值：`10`	`10`
sqsDeadLettersQueueName	N	此应用程序的死信队列名称	`"myapp-dlq"`
messageVisibilityTimeout	N	消息发送给订阅者后，从接收请求中隐藏的时间（秒）。默认值：`10`	`10`
messageRetryLimit	N	在处理消息失败后，从队列中移除该消息之前，重新发送该消息的次数。默认值：`10`	`10`
messageWaitTimeSeconds	N	调用在返回之前等待消息到达队列的持续时间（秒）。如果有消息可用，则调用会早于 `messageWaitTimeSeconds` 返回。如果没有可用的消息且等待时间到期，则调用成功返回并返回空消息列表。默认值：`1`	`1`
messageMaxNumber	N	一次从队列接收的最大消息数。默认值：`10`，最大值：`10`	`10`
fifo	N	使用 SQS FIFO 队列提供消息排序和去重。默认值：`"false"`。有关 SQS FIFO 的更多详情	`"true"`, `"false"`
fifoMessageGroupID	N	如果启用了 `fifo`，指示 Dapr 为发布订阅部署使用自定义消息组 ID。这不是必需的，因为 Dapr 会为每个生产者创建自定义消息组 ID，从而确保每个 Dapr 生产者的消息排序。默认值：`""`	`"app1-mgi"`
disableEntityManagement	N	当设置为 true 时，SNS 主题、SQS 队列以及 SNS 的 SQS 订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
disableDeleteOnRetryLimit	N	当设置为 true 时，在重试和处理消息失败 `messageRetryLimit` 次后，重置消息可见性超时，以便其他消费者可以尝试处理，而不是从 SQS 中删除该消息（默认行为）。默认值：`"false"`	`"true"`, `"false"`
assetsManagementTimeoutSeconds	N	AWS 资源管理操作的超时时间（秒），超时后将取消操作。资源管理操作是在 STS、SNS 和 SQS 上执行的任何操作，除了实现默认 Dapr 组件重试行为的消息发布和消费操作。该值可以设置为任何非负浮点数/整数。默认值：`5`	`0.5`, `10`
concurrencyMode	N	当从 SQS 批量接收消息时，按顺序（一次"单条"消息）或并发（“并行”）调用订阅者。默认值：`"parallel"`	`"single"`, `"parallel"`
concurrencyLimit	N	定义处理消息的最大并发工作线程数。当 concurrencyMode 设置为 `"single"` 时，将忽略此值。要避免限制并发工作线程数，请将其设置为 `0`。默认值：`0`	`100`

附加信息

符合 AWS 规范

Dapr 创建的 SNS 主题和 SQS 队列名称符合 AWS 规范。默认情况下，Dapr 根据消费者的 app-id 创建 SQS 队列名称，因此 Dapr 可能会执行名称标准化以符合 AWS 规范。

SNS/SQS 组件行为

当发布订阅 SNS/SQS 组件预配 SNS 主题时，SQS 队列和订阅在组件代表消息生产者（未部署订阅者应用程序）运行的情况下的行为，与存在订阅者应用程序（未部署发布者）的情况下的行为不同。

由于 SNS 在仅发布者设置中没有 SQS 订阅的工作方式，SQS 队列和订阅的行为类似于依赖于监听主题消息的订阅者的"经典"发布订阅系统。如果没有这些订阅者，消息：

无法继续传递并会被有效丢弃
对于未来的订阅者不可用（订阅者最终订阅时不会重放消息）

SQS FIFO

根据 AWS 规范，使用 SQS FIFO（fifo 元数据字段设置为 "true"）提供消息排序和去重，但会降低 SQS 处理吞吐量，以及其他限制。

指定 fifoMessageGroupID 将所使用的 FIFO 队列的并发消费者数量限制为仅一个，但保证应用程序 Dapr 边车发布的消息的全局排序。请参阅此 AWS 博客文章以更好地了解消息组 ID 和 FIFO 队列的主题。

为避免丢失传递给消费者的消息顺序，SQS 组件的 FIFO 配置需要将 concurrencyMode 元数据字段设置为 "single"。

默认并行 `concurrencyMode`

自 v1.8.0 起，该组件支持 "parallel" concurrencyMode 作为其默认模式。在以前的版本中，组件的默认行为是一次调用订阅者一条消息并等待其响应。

SQS 死信队列

在使用 SQS 死信队列配置发布订阅组件时，元数据字段 messageReceiveLimit 和 sqsDeadLettersQueueName 必须同时设置为某个值。对于 messageReceiveLimit，该值必须大于 0，并且 sqsDeadLettersQueueName 不能为空字符串。

重要

当在 EKS (AWS Kubernetes) 节点/Pod 上运行 Dapr 边车（daprd）与你的应用程序，并且已附加定义对 AWS 资源访问权限的 IAM 策略时，你不得在组件规范定义中提供 AWS access-key、secret-key 和令牌。

SNS/SQS 与 Dapr 的争用

从根本上说，SNS 通过创建对这些主题的 SQS 订阅，将来自多个发布者主题的消息聚合到单个 SQS 队列中。作为订阅者，SNS/SQS 发布订阅组件从该唯一的 SQS 队列消费消息。

然而，像任何 SQS 消费者一样，该组件无法有选择地检索发布到其特定订阅的 SNS 主题的消息。这可能导致组件接收来自没有关联处理程序的主题的消息。通常，这发生在：

组件初始化： 如果基础设施订阅在组件订阅处理程序之前准备就绪，或
关闭： 如果组件处理程序在基础设施订阅之前被移除。

由于此问题会影响多个 SNS 主题的任何 SQS 消费者，因此该组件无法防止消费来自缺少处理程序的主题的消息。当发生这种情况时，组件会记录一条错误，指示此类消息被错误地检索。

在这些情况下，未处理的消息将在每次拉取后在其接收计数递减的情况下重新出现在 SQS 中。因此，存在未处理的消息可能超过其 messageReceiveLimit 并丢失的风险。

重要

在将 SNS/SQS 与 Dapr 一起使用时，请考虑潜在的争用情况，并适当配置 messageReceiveLimit。强烈建议通过设置 sqsDeadLettersQueueName 来使用 SQS 死信队列，以防止消息丢失。

创建 SNS/SQS 实例

对于本地开发，localstack 项目用于集成 AWS SNS/SQS。按照这些说明运行 localstack。

要使用 Docker 在本地从命令行运行 localstack，请应用以下命令：

docker run --rm -it -p 4566:4566 -p 4571:4571 -e SERVICES="sts,sns,sqs" -e AWS_DEFAULT_REGION="us-east-1" localstack/localstack

为了将 localstack 与你的发布订阅绑定一起使用，你需要在组件元数据中提供 endpoint 配置。当针对生产环境 AWS 运行时，不需要 endpoint。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: snssqs-pubsub
spec:
  type: pubsub.aws.snssqs
  version: v1
  metadata:
    - name: accessKey
      value: "anyString"
    - name: secretKey
      value: "anyString"
    - name: endpoint
      value: http://localhost:4566
    # 如果提供给了 localstack，则使用 us-east-1 或任何其他区域，如 "AWS_DEFAULT_REGION" 环境变量所定义
    - name: region
      value: us-east-1

要在 Kubernetes 上运行 localstack，你可以应用以下配置。然后可以通过 DNS 名称 http://localstack.default.svc.cluster.local:4566 访问 Localstack（假设此配置应用于默认命名空间），该名称应作为 endpoint 使用。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: localstack
spec:
  # 使用选择器，我们将暴露正在运行的部署
  # Kubernetes 知道给定的服务属于某个部署
  selector:
    matchLabels:
      app: localstack
  replicas: 1
  template:
    metadata:
      labels:
        app: localstack
    spec:
      containers:
      - name: localstack
        image: localstack/localstack:latest
        ports:
          # 暴露边缘端点
          - containerPort: 4566
---
kind: Service
apiVersion: v1
metadata:
  name: localstack
  labels:
    app: localstack
spec:
  selector:
    app: localstack
  ports:
  - protocol: TCP
    port: 4566
    targetPort: 4566
  type: LoadBalancer

为了在 AWS 中运行，请创建或分配具有对 SNS 和 SQS 服务权限的 IAM 用户，并使用类似以下的策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "YOUR_POLICY_NAME",
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:GetTopicAttributes",
        "sns:ListSubscriptionsByTopic",
        "sns:Publish",
        "sns:Subscribe",
        "sns:TagResource",
        "sqs:ChangeMessageVisibility",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes",
        "sqs:GetQueueUrl",
        "sqs:ReceiveMessage",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue"
      ],
      "Resource": [
        "arn:aws:sns:AWS_REGION:AWS_ACCOUNT_ID:*",
        "arn:aws:sqs:AWS_REGION:AWS_ACCOUNT_ID:*"
      ]
    }
  ]
}

使用 Kubernetes 密钥和 secretKeyRef 将 AWS 账户 ID 和 AWS 账户密钥插入组件元数据中的 accessKey 和 secretKey。

或者，假设你想使用自己选择的工具（例如 Terraform）预配 SNS 和 SQS 资源，同时防止 Dapr 动态执行此操作。你需要启用 disableEntityManagement 并为你的使用 Dapr 的应用程序分配一个 IAM 角色，并使用类似以下的策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "YOUR_POLICY_NAME",
      "Effect": "Allow",
      "Action": [
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:ChangeMessageVisibility",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sns:Publish",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes"

      ],
      "Resource": [
        "arn:aws:sns:AWS_REGION:AWS_ACCOUNT_ID:APP_TOPIC_NAME",
        "arn:aws:sqs:AWS_REGION:AWS_ACCOUNT_ID:APP_ID"
      ]
    }
  ]
}

在上面的示例中，你在 EKS 集群上运行应用程序，并启用了动态资源创建（默认的 Dapr 行为）。

8.3 - Azure Event Hubs

Azure Event Hubs 发布订阅组件的详细文档

组件格式

要设置 Azure Event Hubs 发布订阅，请创建类型为 pubsub.azure.eventhubs 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅以了解如何创建和应用发布订阅配置。

除了下面显示的配置元数据字段外，Azure Event Hubs 还支持 Azure 身份验证机制。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: eventhubs-pubsub
spec:
  type: pubsub.azure.eventhubs
  version: v1
  metadata:
    # connectionString 或 eventHubNamespace 是必需的
    # 当*不*使用 Microsoft Entra ID 时使用 connectionString
    - name: connectionString
      value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"
    # 使用 Microsoft Entra ID 时使用 eventHubNamespace
    - name: eventHubNamespace
      value: "namespace"
    - name: consumerID # 可选。如果未提供，运行时将创建一个。
      value: "channel1"
    - name: enableEntityManagement
      value: "false"
    - name: enableInOrderMessageDelivery
      value: "false"
    # 仅当 enableEntityManagement 设置为 true 时才需要以下四个属性
    - name: resourceGroupName
      value: "test-rg"
    - name: subscriptionID
      value: "Azure 订阅 ID 的值"
    - name: partitionCount
      value: "1"
    - name: messageRetentionInDays
      value: "3"
    # 检查点存储属性
    - name: storageAccountName
      value: "myeventhubstorage"
    - name: storageAccountKey
      value: "112233445566778899"
    - name: storageContainerName
      value: "myeventhubstoragecontainer"
    # 传递 storageAccountKey 的替代方案
    - name: storageConnectionString
      value: "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<account-key>"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y*	Event Hub 或 Event Hub 命名空间的连接字符串。 * 与 `eventHubNamespace` 字段互斥。 * 在不使用 Microsoft Entra ID 身份验证时必需。	`"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` 或 `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}"`
`eventHubNamespace`	Y*	Event Hub 命名空间名称。 * 与 `connectionString` 字段互斥。 * 在使用 Microsoft Entra ID 身份验证时必需。	`"namespace"`
`consumerID`	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息只由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）的值。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式的值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
`enableEntityManagement`	N	布尔值，允许管理 EventHub 命名空间和存储账户。默认值：`false`	`"true", "false"`
`enableInOrderMessageDelivery`	N	输入/输出	布尔值，允许按照消息发布的顺序传递消息。这假设在发布或发布时设置了 `partitionKey` 以确保跨分区的顺序。默认值：`false`
`storageAccountName`	Y	用于检查点存储的存储账户名称。	`"myeventhubstorage"`
`storageAccountKey`	Y*	检查点存储账户的存储账户密钥。 * 使用 Microsoft Entra ID 时，如果服务主体也有权访问存储账户，则可以省略此项。	`"112233445566778899"`
`storageConnectionString`	Y*	检查点存储的连接字符串，指定 `storageAccountKey` 的替代方案	`"DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>"`
`storageContainerName`	Y	存储账户名称的存储容器名称。	`"myeventhubstoragecontainer"`
`resourceGroupName`	N	Event Hub 命名空间所属的资源组名称。在启用实体管理时必需	`"test-rg"`
`subscriptionID`	N	Azure 订阅 ID 值。在启用实体管理时必需	`"azure subscription id"`
`partitionCount`	N	新 Event Hub 命名空间的分区数量。仅在启用实体管理时使用。默认值：`"1"`	`"2"`
`messageRetentionInDays`	N	在新创建的 Event Hub 命名空间中保留消息的天数。仅在启用实体管理时使用。默认值：`"1"`	`"90"`

Microsoft Entra ID 身份验证

Azure Event Hubs 发布订阅组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据所选的 Microsoft Entra ID 身份验证机制需要提供的组件元数据字段，请参阅Azure 身份验证文档。

配置示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: eventhubs-pubsub
spec:
  type: pubsub.azure.eventhubs
  version: v1
  metadata:
    # 使用的 Azure 身份验证
    - name: azureTenantId
      value: "***"
    - name: azureClientId
      value: "***"
    - name: azureClientSecret
      value: "***"
    - name: eventHubNamespace 
      value: "namespace"
    - name: enableEntityManagement
      value: "false"
    # 仅当 enableEntityManagement 设置为 true 时才需要以下四个属性
    - name: resourceGroupName
      value: "test-rg"
    - name: subscriptionID
      value: "Azure 订阅 ID 的值"
    - name: partitionCount
      value: "1"
    - name: messageRetentionInDays
    # 检查点存储属性
    # 在此情况下，我们也使用 Microsoft Entra ID 访问存储账户
    - name: storageAccountName
      value: "myeventhubstorage"
    - name: storageContainerName
      value: "myeventhubstoragecontainer"

发送和接收多条消息

Azure Event Hubs 支持使用批量发布订阅 API 在单个操作中发送和接收多条消息。

配置批量发布

要设置批量发布操作的元数据，请在 HTTP 请求或 gRPC 元数据上设置查询参数，如 API 参考中所述。

元数据	默认值
`metadata.maxBulkPubBytes`	`1000000`

配置批量订阅

订阅主题时，您可以配置 bulkSubscribe 选项。有关更多详细信息，请参阅批量订阅消息并了解批量订阅 API。

配置	默认值
`maxMessagesCount`	`100`
`maxAwaitDurationMs`	`10000`

配置检查点频率

订阅主题时，您可以在 HTTP 或 gRPC 订阅请求中设置元数据来配置分区中的检查点频率。此元数据在分区事件序列中达到配置数量的事件后启用检查点。通过将频率设置为 0 来禁用检查点。

了解有关检查点的更多信息。

元数据	默认值
`metadata.checkPointFrequencyPerPartition`	`1`

以下示例显示了使用 checkPointFrequencyPerPartition 元数据的声明式订阅的示例订阅文件。同样，您也可以在程序化订阅中传递元数据。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: order-pub-sub
spec:
  topic: orders
  routes: 
    default: /checkout
  pubsubname: order-pub-sub
  metadata:
    checkPointFrequencyPerPartition: 1
scopes:
- orderprocessing
- checkout

注意

使用 BulkSubscribe 订阅主题时，您将检查点配置为在指定数量的_批次_之后发生，而不是事件，其中_批次_是指在单个请求中接收到的事件集合。

创建 Azure Event Hub

按照文档中的说明设置 Azure Event Hubs。

由于此组件使用 Azure Storage 作为检查点存储，您还需要一个 Azure Storage 账户。按照文档中的说明管理存储账户访问密钥。

请参阅文档了解如何获取 Event Hubs 连接字符串（注意这不是 Event Hubs 命名空间的连接字符串）。

为每个订阅者创建消费者组

对于每个想要订阅事件的 Dapr 应用程序，请创建一个以 Dapr 应用程序 ID 命名的 Event Hubs 消费者组。例如，一个在 Kubernetes 上运行且 dapr.io/app-id: "myapp" 的 Dapr 应用程序将需要一个名为 myapp 的 Event Hubs 消费者组。

注意：Dapr 将消费者组的名称传递给 Event Hub，因此不需要在元数据中提供。

实体管理

当在元数据中启用实体管理时，只要应用程序具有操作 Event Hub 命名空间的正确角色和权限，Dapr 就可以自动为您创建 Event Hub 和消费者组。

Event Hub 名称是发布或订阅的传入请求中的 topic 字段，而消费者组名称是订阅给定 Event Hub 的 Dapr 应用程序的名称。例如，一个在 Kubernetes 上运行且名称为 dapr.io/app-id: "myapp" 的 Dapr 应用程序需要一个名为 myapp 的 Event Hubs 消费者组。

实体管理仅在使用 Microsoft Entra ID 身份验证时才可用，而不使用连接字符串。

Dapr 将消费者组的名称传递给 Event Hub，因此不需要在元数据中提供。

接收自定义属性

默认情况下，Dapr 不会转发自定义属性。但是，通过将订阅元数据 requireAllProperties 设置为 "true"，您可以接收自定义属性作为 HTTP 头。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: order-pub-sub
spec:
  topic: orders
  routes: 
    default: /checkout
  pubsubname: order-pub-sub
  metadata:
    requireAllProperties: "true"

可以使用 Dapr SDK 实现相同的效果：

[Topic("order-pub-sub", "orders")]
[TopicMetadata("requireAllProperties", "true")]
[HttpPost("checkout")]
public ActionResult Checkout(Order order, [FromHeader] int priority)
{
    return Ok();
}

订阅 Azure IoT Hub 事件

Azure IoT Hub 提供了一个与 Event Hubs 兼容的端点，因此 Azure Event Hubs 发布订阅组件也可用于订阅 Azure IoT Hub 事件。

由 Azure IoT Hub 设备创建的设备到云事件将包含额外的 IoT Hub 系统属性，Dapr 的 Azure Event Hubs 发布订阅组件将把以下内容作为响应元数据的一部分返回：

系统属性名称	描述和路由查询关键字
`iothub-connection-auth-generation-id`	发送消息的设备的 connectionDeviceGenerationId。请参阅 IoT Hub 设备身份属性。
`iothub-connection-auth-method`	用于对发送消息的设备进行身份验证的 connectionAuthMethod。
`iothub-connection-device-id`	发送消息的设备的 deviceId。请参阅 IoT Hub 设备身份属性。
`iothub-connection-module-id`	发送消息的设备的 moduleId。请参阅 IoT Hub 设备身份属性。
`iothub-enqueuedtime`	IoT Hub 接收到设备到云消息的 RFC3339 格式的 enqueuedTime。
`message-id`	用户可设置的 AMQP messageId。

例如，传递的 HTTP 订阅消息的头将包含：

{
  'user-agent': 'fasthttp',
  'host': '127.0.0.1:3000',
  'content-type': 'application/json',
  'content-length': '120',
  'iothub-connection-device-id': 'my-test-device',
  'iothub-connection-auth-generation-id': '637618061680407492',
  'iothub-connection-auth-method': '{"scope":"module","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}',
  'iothub-connection-module-id': 'my-test-module-a',
  'iothub-enqueuedtime': '2021-07-13T22:08:09Z',
  'message-id': 'my-custom-message-id',
  'x-opt-sequence-number': '35',
  'x-opt-enqueued-time': '2021-07-13T22:08:09Z',
  'x-opt-offset': '21560',
  'traceparent': '00-4655608164bc48b985b42d39865f3834-ed6cf3697c86e7bd-01'
}

8.4 - Azure Service Bus 队列

Azure Service Bus 队列发布订阅组件的详细文档

组件格式

要设置 Azure Service Bus 队列发布订阅，需创建类型为 pubsub.azure.servicebus.queues 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅了解如何创建和应用发布订阅配置。

此组件使用 Azure Service Bus 上的队列；有关主题和队列之间差异的说明，请参阅官方文档。若要使用主题，请参阅 Azure Service Bus Topics 发布订阅组件。

连接字符串身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.queues
  version: v1
  metadata:
  # 未使用 Microsoft Entra ID 身份验证时必需
  - name: connectionString
    value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}"
  # - name: consumerID # 可选
  #   value: channel1
  # - name: timeoutInSec # 可选
  #   value: 60
  # - name: handlerTimeoutInSec # 可选
  #   value: 60
  # - name: disableEntityManagement # 可选
  #   value: "false"
  # - name: maxDeliveryCount # 可选
  #   value: 3
  # - name: lockDurationInSec # 可选
  #   value: 60
  # - name: lockRenewalInSec # 可选
  #   value: 20
  # - name: maxActiveMessages # 可选
  #   value: 10000
  # - name: maxConcurrentHandlers # 可选
  #   value: 10
  # - name: defaultMessageTimeToLiveInSec # 可选
  #   value: 10
  # - name: autoDeleteOnIdleInSec # 可选
  #   value: 3600
  # - name: minConnectionRecoveryInSec # 可选
  #   value: 2
  # - name: maxConnectionRecoveryInSec # 可选
  #   value: 300
  # - name: maxRetriableErrorsPerSec # 可选
  #   value: 10
  # - name: publishMaxRetries # 可选
  #   value: 5
  # - name: publishInitialRetryIntervalInMs # 可选
  #   value: 500

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	Service Bus 的共享访问策略连接字符串。除非使用 Microsoft Entra ID 身份验证，否则为必填。	见上方示例
`consumerID`	N	消费者 ID（consumer tag）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）的值。	可以设置为字符串值（如上方示例中的 `"channel1"`）或字符串格式的值（如 `"{podName}"` 等）。请参阅您可以在组件元数据中使用的所有模板标签。
`namespaceName`	N	用于设置 Service Bus 命名空间地址的参数，为完全限定域名。如果使用 Microsoft Entra ID 身份验证，则为必填。	`"namespace.servicebus.windows.net"`
`timeoutInSec`	N	发送消息和管理操作的超时时间。默认值：`60`	`30`
`handlerTimeoutInSec`	N	调用应用程序处理器的超时时间。默认值：`60`	`30`
`lockRenewalInSec`	N	定义缓冲消息锁的续订频率。默认值：`20`。	`20`
`maxActiveMessages`	N	定义一次处理或缓冲的最大消息数。此值应至少与最大并发处理器数一样大。默认值：`1000`	`2000`
`maxConcurrentHandlers`	N	定义最大并发消息处理器数。默认值：`0`（无限制）	`10`
`disableEntityManagement`	N	当设置为 true 时，队列和订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
`defaultMessageTimeToLiveInSec`	N	默认消息存活时间，以秒为单位。仅在创建订阅时使用。	`10`
`autoDeleteOnIdleInSec`	N	在自动删除空闲订阅之前等待的时间（秒）。仅在创建订阅时使用。必须为 300 秒或更长。默认值：`0`（禁用）	`3600`
`maxDeliveryCount`	N	定义服务器尝试传递消息的次数。仅在创建订阅时使用。默认值由服务器设置。	`10`
`lockDurationInSec`	N	定义消息在过期前被锁定的时长（秒）。仅在创建订阅时使用。默认值由服务器设置。	`30`
`minConnectionRecoveryInSec`	N	在连接失败后重新连接到 Azure Service Bus 之前等待的最小间隔（秒）。默认值：`2`	`5`
`maxConnectionRecoveryInSec`	N	在连接失败后重新连接到 Azure Service Bus 之前等待的最大间隔（秒）。每次尝试后，组件会在最小值和最大值之间等待一个随机秒数，每次都在增加。默认值：`300`（5 分钟）	`600`
`maxRetriableErrorsPerSec`	N	每秒处理的最大可重试错误数。如果消息因可重试错误而处理失败，组件会在开始处理另一条消息之前添加延迟，以避免立即重新处理失败的消息。默认值：`10`	`10`
`publishMaxRetries`	N	当 Azure Service Bus 响应"太忙"以限制消息时的最大重试次数。默认值：`5`	`5`
`publishInitialRetryIntervalInMs`	N	当 Azure Service Bus 限制消息时初始指数退避的时间（毫秒）。默认值：`500`	`500`

Microsoft Entra ID 身份验证

Azure Service Bus 队列发布订阅组件支持使用所有 Microsoft Entra ID 机制进行身份验证，包括托管标识。有关更多信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的相关组件元数据字段，请参阅向 Azure 进行身份验证的文档。

示例配置

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.queues
  version: v1
  metadata:
  - name: namespaceName
    # 使用 Azure 身份验证时必需。
    # 必须是完全限定域名
    value: "servicebusnamespace.servicebus.windows.net"
  - name: azureTenantId
    value: "***"
  - name: azureClientId
    value: "***"
  - name: azureClientSecret
    value: "***"

消息元数据

Azure Service Bus 消息使用其他上下文元数据扩展了 Dapr 消息格式。一些元数据字段由 Azure Service Bus 本身设置（只读），其他字段可以在发布消息时由客户端设置。

发送带有元数据的消息

要在发送消息时设置 Azure Service Bus 元数据，请在 HTTP 请求上设置查询参数或 gRPC 元数据，如此处所述。

metadata.MessageId
metadata.CorrelationId
metadata.SessionId
metadata.Label
metadata.ReplyTo
metadata.PartitionKey
metadata.To
metadata.ContentType
metadata.ScheduledEnqueueTimeUtc
metadata.ReplyToSessionId

注意

metadata.MessageId 属性不会设置 Dapr 返回的 Cloud Event 的 id 属性，应单独处理。
metadata.ScheduledEnqueueTimeUtc 属性支持 RFC1123 和 RFC3339 时间戳格式。

接收带有元数据的消息

当 Dapr 调用您的应用程序时，它使用 HTTP 标头或 gRPC 元数据将 Azure Service Bus 消息元数据附加到请求中。除了上面列出的可设置元数据之外，您还可以访问以下只读消息元数据。

metadata.DeliveryCount
metadata.LockedUntilUtc
metadata.LockToken
metadata.EnqueuedTimeUtc
metadata.SequenceNumber

要了解这些元数据属性的用途的更多详细信息，请参阅官方 Azure Service Bus 文档。

此外，原始 Azure Service Bus 消息的所有 ApplicationProperties 条目都会作为 metadata.<application property's name> 附加。

注意

所有时间都由服务器填充，不会针对时钟偏差进行调整。

发送和接收多条消息

Azure Service Bus 支持使用批量发布订阅 API 在单个操作中发送和接收多条消息。

配置批量发布

要设置批量发布操作的元数据，请在 HTTP 请求上设置查询参数或 gRPC 元数据，如此处所述

元数据	默认值
`metadata.maxBulkPubBytes`	`131072` (128 KiB)

配置批量订阅

订阅主题时，您可以配置 bulkSubscribe 选项。有关更多详细信息，请参阅批量订阅消息。了解有关批量订阅 API的更多信息。

配置	默认值
`maxMessagesCount`	`100`

为队列创建 Azure Service Bus 代理

按照此处的说明设置 Azure Service Bus 队列。

注意

您的队列必须与您使用 Dapr 发布到的主题同名。例如，如果您在主题 "orders" 上发布到发布订阅 "myPubsub"，您的队列必须命名为 "orders"。如果您使用共享访问策略连接到队列，该策略必须能够"管理"队列。要使用死信队列，该策略必须位于包含主队列和死信队列的 Service Bus 命名空间上。

重试策略和死信队列

默认情况下，Azure Service Bus 队列有一个死信队列。消息会重试 maxDeliveryCount 给定的次数。默认的 maxDeliveryCount 值默认为 10，但可以设置为最高 2000。这些重试发生得非常快，如果没有返回成功，消息将被放入死信队列。

Dapr 发布订阅提供了自己的死信队列概念，允许您控制重试策略并通过 Dapr 订阅死信队列。

在 Azure Service Bus 命名空间中设置一个单独的队列作为死信队列，以及一个定义如何重试的弹性策略。
订阅主题以获取失败的消息并处理它们。

例如，在订阅中设置死信队列 orders-dlq 和弹性策略可以让您订阅主题 orders-dlq 来处理失败的消息。

有关设置死信队列的更多详细信息，请参阅死信文章。

8.5 - Azure Service Bus 主题

Azure Service Bus 主题发布订阅组件的详细文档

组件格式

要设置 Azure Service Bus 主题发布订阅，请创建类型为 pubsub.azure.servicebus.topics 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南以了解如何创建和应用发布订阅配置。

此组件使用 Azure Service Bus 上的主题；有关主题和队列之间差异，请参阅官方文档。
若要使用队列，请参阅 Azure Service Bus 队列发布订阅组件。

连接字符串身份验证

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  # 不使用 Microsoft Entra ID 身份验证时必需
  - name: connectionString
    value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}"
  # - name: consumerID # 可选：默认为应用自身的 ID
  #   value: channel1 
  # - name: timeoutInSec # 可选
  #   value: 60
  # - name: handlerTimeoutInSec # 可选
  #   value: 60
  # - name: disableEntityManagement # 可选
  #   value: "false"
  # - name: maxDeliveryCount # 可选
  #   value: 3
  # - name: lockDurationInSec # 可选
  #   value: 60
  # - name: lockRenewalInSec # 可选
  #   value: 20
  # - name: maxActiveMessages # 可选
  #   value: 10000
  # - name: maxConcurrentHandlers # 可选
  #   value: 10
  # - name: defaultMessageTimeToLiveInSec # 可选
  #   value: 10
  # - name: autoDeleteOnIdleInSec # 可选
  #   value: 3600
  # - name: minConnectionRecoveryInSec # 可选
  #   value: 2
  # - name: maxConnectionRecoveryInSec # 可选
  #   value: 300
  # - name: maxRetriableErrorsPerSec # 可选
  #   value: 10
  # - name: publishMaxRetries # 可选
  #   value: 5
  # - name: publishInitialRetryIntervalInMs # 可选
  #   value: 500

注意： 上述设置在使用此组件的所有主题之间共享。

警告

上述示例使用纯文本字符串作为密钥。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	Service Bus 的共享访问策略连接字符串。除非使用 Microsoft Entra ID 身份验证，否则必需。	参见上面的示例
`namespaceName`	N	用于设置 Service Bus 命名空间地址的参数，为完全限定域名。如果使用 Microsoft Entra ID 身份验证，则为必需。	`"namespace.servicebus.windows.net"`
`consumerID`	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息只由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID（`appID`）值。(`appID`) 值。	可以设置为字符串值（例如上面示例中的 `"channel1"`）或字符串格式值（例如 `"{podName}"` 等）。请参阅您可以在组件元数据中使用的所有模板标签。
`timeoutInSec`	N	发送消息和管理操作的超时时间。默认值：`60`	`30`
`handlerTimeoutInSec`	N	调用应用程序处理程序的超时时间。默认值：`60`	`30`
`lockRenewalInSec`	N	定义缓冲消息锁的续订频率。默认值：`20`。	`20`
`maxActiveMessages`	N	定义一次处理或缓冲的最大消息数。此值应至少等于最大并发处理程序数。默认值：`1000`	`2000`
`maxConcurrentHandlers`	N	定义并发消息处理程序的最大数量。默认值：`0`（无限制）	`10`
`disableEntityManagement`	N	当设置为 true 时，队列和订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
`defaultMessageTimeToLiveInSec`	N	默认消息生存时间（秒）。仅在订阅创建期间使用。	`10`
`autoDeleteOnIdleInSec`	N	自动删除空闲订阅前等待的时间（秒）。仅在订阅创建期间使用。必须为 300 秒或更长。默认值：`0`（禁用）	`3600`
`maxDeliveryCount`	N	定义服务器尝试传递消息的次数。仅在订阅创建期间使用。默认值由服务器设置。	`10`
`lockDurationInSec`	N	定义消息在过期前被锁定的秒数。仅在订阅创建期间使用。默认值由服务器设置。	`30`
`minConnectionRecoveryInSec`	N	在连接失败后尝试重新连接到 Azure Service Bus 之前等待的最小间隔（秒）。默认值：`2`	`5`
`maxConnectionRecoveryInSec`	N	在连接失败后尝试重新连接到 Azure Service Bus 之前等待的最大间隔（秒）。在每次尝试之后，组件在最小值和最大值之间等待一个随机秒数，每次都会增加。默认值：`300`（5 分钟）	`600`
`maxRetriableErrorsPerSec`	N	每秒处理的可重试错误的最大数量。如果消息因可重试错误而处理失败，组件会在开始处理另一条消息之前添加延迟，以避免立即重新处理失败的消息。默认值：`10`	`10`
`publishMaxRetries`	N	当 Azure Service Bus 响应"太忙"以限制消息时的最大重试次数。默认值：`5`	`5`
`publishInitialRetryIntervalInMs`	N	当 Azure Service Bus 限制消息时，初始指数退避的时间（毫秒）。默认值：`500`	`500`

Microsoft Entra ID 身份验证

Azure Service Bus 主题发布订阅组件支持使用所有 Microsoft Entra ID 机制进行身份验证，包括托管标识。有关详细信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的相关组件元数据字段，请参阅Azure 身份验证文档。

配置示例

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  - name: namespaceName
    # 使用 Azure 身份验证时必需。
    # 必须是完全限定域名
    value: "servicebusnamespace.servicebus.windows.net"
  - name: azureTenantId
    value: "***"
  - name: azureClientId
    value: "***"
  - name: azureClientSecret
    value: "***"

消息元数据

Azure Service Bus 消息使用额外的上下文元数据扩展了 Dapr 消息格式。一些元数据字段由 Azure Service Bus 本身设置（只读），其他字段可以在发布消息时由客户端设置。

发送带有元数据的消息

要在发送消息时设置 Azure Service Bus 元数据，请按照此处的文档在 HTTP 请求上设置查询参数或在 gRPC 元数据中设置。

metadata.MessageId
metadata.CorrelationId
metadata.SessionId
metadata.Label
metadata.ReplyTo
metadata.PartitionKey
metadata.To
metadata.ContentType
metadata.ScheduledEnqueueTimeUtc
metadata.ReplyToSessionId

注意： metadata.MessageId 属性不会设置 Dapr 返回的 cloud event 的 id 属性，应单独处理。

注意： 如果未设置 metadata.SessionId 属性但主题需要会话，则将使用空的会话 ID。

注意： metadata.ScheduledEnqueueTimeUtc 属性支持 RFC1123 和 RFC3339 时间戳格式。

接收带有元数据的消息

当 Dapr 调用您的应用程序时，它会使用 HTTP 头或 gRPC 元数据将 Azure Service Bus 消息元数据附加到请求中。除了上面列出的可设置元数据之外，您还可以访问以下只读消息元数据。

metadata.DeliveryCount
metadata.LockedUntilUtc
metadata.LockToken
metadata.EnqueuedTimeUtc
metadata.SequenceNumber

要了解有关这些元数据属性用途的更多详细信息，请参阅官方 Azure Service Bus 文档。

此外，原始 Azure Service Bus 消息的所有 ApplicationProperties 条目都将作为 metadata.<application property's name> 附加。

注意：所有时间都由服务器填充，不会针对时钟偏差进行调整。

订阅启用会话的主题

要订阅已启用会话的主题，您可以在订阅元数据中提供以下属性。

requireSessions（默认：false）
sessionIdleTimeoutInSec（默认：60）
maxConcurrentSessions（默认：8）

为主题创建 Azure Service Bus 代理

按照此处的说明设置 Azure Service Bus 主题。

8.6 - GCP

GCP Pub/Sub 组件的详细文档

创建 Dapr 组件

要设置 GCP 发布订阅，需创建类型为 pubsub.gcp.pubsub 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 如何自动生成。阅读操作指南：发布和订阅指南了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: gcp-pubsub
spec:
  type: pubsub.gcp.pubsub
  version: v1
  metadata:
  - name: type
    value: service_account
  - name: projectId
    value: <PROJECT_ID> # replace
  - name: endpoint # Optional.
    value: "http://localhost:8085"
  - name: consumerID # Optional - defaults to the app's own ID
    value: <CONSUMER_ID>
  - name: identityProjectId
    value: <IDENTITY_PROJECT_ID> # replace
  - name: privateKeyId
    value: <PRIVATE_KEY_ID> #replace
  - name: clientEmail
    value: <CLIENT_EMAIL> #replace
  - name: clientId
    value: <CLIENT_ID> # replace
  - name: authUri
    value: https://accounts.google.com/o/oauth2/auth
  - name: tokenUri
    value: https://oauth2.googleapis.com/token
  - name: authProviderX509CertUrl
    value: https://www.googleapis.com/oauth2/v1/certs
  - name: clientX509CertUrl
    value: https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com #replace PROJECT_NAME
  - name: privateKey
    value: <PRIVATE_KEY> # replace x509 cert
  - name: disableEntityManagement
    value: "false"
  - name: enableMessageOrdering
    value: "false"
  - name: orderingKey # Optional
    value: <ORDERING_KEY>
  - name: maxReconnectionAttempts # Optional
    value: 30
  - name: connectionRecoveryInSec # Optional
    value: 2
  - name: deadLetterTopic # Optional
    value: <EXISTING_PUBSUB_TOPIC>
  - name: maxDeliveryAttempts # Optional
    value: 5
  - name: maxOutstandingMessages # Optional
    value: 1000
  - name: maxOutstandingBytes # Optional
    value: 1000000000
  - name: maxConcurrentConnections # Optional
    value: 10

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储，如此处所述。

规范元数据字段

字段	必填	详情	示例
projectId	Y	GCP 项目 ID	`myproject-123`
endpoint	N	组件使用的 GCP 端点。仅用于本地开发（例如）与 GCP Pub/Sub 模拟器配合使用。当针对 GCP 生产 API 运行时，不需要 `endpoint`。	`"http://localhost:8085"`
`consumerID`	N	Consumer ID 将一个或多个消费者组织成一个组。具有相同 consumer ID 的消费者作为一个虚拟消费者工作；例如，一条消息仅被组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID (`appID`) 值。`consumerID` 与请求的一部分提供的 `topic` 一起用于构建发布订阅订阅 ID	可以设置为字符串值（如 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。请参阅您可以在组件元数据中使用的所有模板标签。
identityProjectId	N	如果 GCP 发布订阅项目与身份项目不同，请使用此属性指定身份项目	`"myproject-123"`
privateKeyId	N	如果使用显式凭据，此字段应包含服务账户 json 文档中的 `private_key_id` 字段	`"my-private-key"`
privateKey	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `private_key` 字段	`-----BEGIN PRIVATE KEY-----MIIBVgIBADANBgkqhkiG9w0B`
clientEmail	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `client_email` 字段	`"myservice@myproject-123.iam.gserviceaccount.com"`
clientId	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `client_id` 字段	`106234234234`
authUri	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `auth_uri` 字段	`https://accounts.google.com/o/oauth2/auth`
tokenUri	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `token_uri` 字段	`https://oauth2.googleapis.com/token`
authProviderX509CertUrl	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `auth_provider_x509_cert_url` 字段	`https://www.googleapis.com/oauth2/v1/certs`
clientX509CertUrl	N	如果使用显式凭据，此字段应包含服务账户 json 中的 `client_x509_cert_url` 字段	`https://www.googleapis.com/robot/v1/metadata/x509/myserviceaccount%40myproject.iam.gserviceaccount.com`
disableEntityManagement	N	当设置为 `"true"` 时，主题和订阅不会自动创建。默认值：`"false"`	`"true"`, `"false"`
enableMessageOrdering	N	当设置为 `"true"` 时，订阅的消息将按顺序接收，具体取决于发布和权限配置。	`"true"`, `"false"`
orderingKey	N	请求中提供的键。当 `enableMessageOrdering` 设置为 `true` 时使用，用于根据该键对消息进行排序。	“my-orderingkey”
maxReconnectionAttempts	N	定义最大重连尝试次数。默认值：`30`	`30`
connectionRecoveryInSec	N	连接恢复尝试之间等待的秒数。默认值：`2`	`2`
deadLetterTopic	N	GCP Pub/Sub 主题的名称。使用此组件前，此主题必须存在。	`"myapp-dlq"`
maxDeliveryAttempts	N	尝试传递消息的最大次数。如果指定了 `deadLetterTopic`，`maxDeliveryAttempts` 是消息处理失败的最大尝试次数。达到该次数后，消息将被移动到死信主题。默认值：`5`	`5`
type	N	已弃用 GCP 凭据类型。仅支持 `service_account`。默认值为 `service_account`	`service_account`
maxOutstandingMessages	N	给定流式拉取连接可以拥有的最大未完成消息数。默认值：`1000`	`50`
maxOutstandingBytes	N	给定流式拉取连接可以拥有的最大未完成字节数。默认值：`1000000000`	`1000000000`
maxConcurrentConnections	N	要维护的最大并发流式拉取连接数。默认值：`10`	`2`
ackDeadline	N	消息确认持续时间截止时间。默认值：`20s`	`1m`

警告

如果 enableMessageOrdering 设置为 “true”，则服务账户需要 roles/viewer 或 roles/pubsub.viewer 角色，以便在消息中未嵌入顺序令牌的情况下保证顺序。如果未授予此角色，或由于任何其他原因对 Subscription.Config() 的调用失败，按嵌入顺序令牌排序仍将正常工作。

GCP 凭据

由于 GCP Pub/Sub 组件使用 GCP Go 客户端库，默认情况下它使用应用程序默认凭据进行身份验证。这在使用客户端库向 GCP Cloud 服务进行身份验证指南中有进一步说明。

创建 GCP Pub/Sub

对于本地开发，使用 GCP Pub/Sub 模拟器来测试 GCP Pub/Sub 组件。按照这些说明运行 GCP Pub/Sub 模拟器。

要使用 Docker 在本地运行 GCP Pub/Sub 模拟器，请使用以下 docker-compose.yaml：

version: '3'
services:
  pubsub:
    image: gcr.io/google.com/cloudsdktool/cloud-sdk:422.0.0-emulators
    ports:
      - "8085:8085"
    container_name: gcp-pubsub
    entrypoint: gcloud beta emulators pubsub start --project local-test-prj --host-port 0.0.0.0:8085

为了将 GCP Pub/Sub 模拟器与您的发布订阅绑定一起使用，您需要在组件元数据中提供 endpoint 配置。当针对 GCP 生产 API 运行时，不需要 endpoint。

projectId 属性必须与 docker-compose.yaml 或 Docker 命令中使用的 --project 匹配。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: gcp-pubsub
spec:
  type: pubsub.gcp.pubsub
  version: v1
  metadata:
  - name: projectId
    value: "local-test-prj"
  - name: consumerID
    value: "testConsumer"
  - name: endpoint
    value: "localhost:8085"

您可以使用"显式"或"隐式"凭据来配置对 GCP 发布订阅实例的访问。如果使用显式凭据，大多数字段都是必填的。隐式凭据依赖于在 Kubernetes 服务账户（KSA）下运行的 dapr，该账户映射到具有访问发布订阅所需权限的 Google 服务账户（GSA）。在隐式模式下，只需要 projectId 属性，所有其他属性都是可选的。

按照此处的说明设置 Google Cloud Pub/Sub 系统。

8.7 - In-memory

In Memory 发布订阅组件的详细文档

内存中的发布订阅组件在单个 Dapr 边车内运行。这主要用于开发目的。状态不会在多个边车之间复制，当 Dapr 边车重启时，状态会丢失。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: pubsub
spec:
  type: pubsub.in-memory
  version: v1
  metadata: []

注意：内存中不需要任何特定的元数据即可使组件工作，但是 spec.metadata 是必填字段。

8.8 - JetStream

NATS JetStream 组件的详细文档

组件格式

要设置 JetStream 发布订阅，请创建类型为 pubsub.jetstream 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南以了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: jetstream-pubsub
spec:
  type: pubsub.jetstream
  version: v1
  metadata:
  - name: natsURL
    value: "nats://localhost:4222"
  - name: jwt # 可选。用于去中心化 JWT 认证。
    value: "eyJhbGciOiJ...6yJV_adQssw5c"
  - name: seedKey # 可选。用于去中心化 JWT 认证。
    value: "SUACS34K232O...5Z3POU7BNIL4Y"
  - name: tls_client_cert # 可选。用于 TLS 客户端认证。
    value: "/path/to/tls.crt"
  - name: tls_client_key # 可选。用于 TLS 客户端认证。
    value: "/path/to/tls.key"
  - name: token # 可选。用于基于 Token 的认证。
    value: "my-token"
  - name: name
    value: "my-conn-name"
  - name: streamName
    value: "my-stream"
  - name: durableName 
    value: "my-durable-subscription"
  - name: queueGroupName
    value: "my-queue-group"
  - name: startSequence
    value: 1
  - name: startTime # Unix 格式
    value: 1630349391
  - name: flowControl
    value: false
  - name: ackWait
    value: 10s
  - name: maxDeliver
    value: 5
  - name: backOff
    value: "50ms, 1s, 10s"
  - name: maxAckPending
    value: 5000
  - name: replicas
    value: 1
  - name: memoryStorage
    value: false
  - name: rateLimit
    value: 1024
  - name: heartbeat
    value: 15s
  - name: ackPolicy
    value: explicit
  - name: deliverPolicy
    value: all
  - name: domain
    value: hub
  - name: apiPrefix
    value: PREFIX

规范元数据字段

字段	必填	详情	示例
natsURL	Y	NATS 服务器地址 URL	`"nats://localhost:4222"`
jwt	N	NATS 去中心化认证 JWT	`"eyJhbGciOiJ...6yJV_adQssw5c"`
seedKey	N	NATS 去中心化认证 Seed Key	`"SUACS34K232O...5Z3POU7BNIL4Y"`
tls_client_cert	N	NATS TLS 客户端认证证书	`"/path/to/tls.crt"`
tls_client_key	N	NATS TLS 客户端认证密钥	`"/path/to/tls.key"`
token	N	[NATS 基于 Token 的认证]	`"my-token"`
name	N	NATS 连接名称	`"my-conn-name"`
streamName	N	要绑定的 JetStream Stream 名称	`"my-stream"`
durableName	N	Durable name	`"my-durable"`
queueGroupName	N	队列组名称	`"my-queue"`
startSequence	N	Start Sequence	`1`
startTime	N	Unix 格式的[开始时间]	`1630349391`
flowControl	N	[流控]	`true`
ackWait	N	Ack Wait	`10s`
maxDeliver	N	[最大投递次数]	`15`
backOff	N	[退避策略]	`"50ms, 1s, 5s, 10s"`
maxAckPending	N	[最大待确认消息数]	`5000`
replicas	N	[副本数]	`3`
memoryStorage	N	[内存存储]	`false`
rateLimit	N	[速率限制]	`1024`
heartbeat	N	[心跳]	`10s`
ackPolicy	N	[确认策略]	`explicit`
deliverPolicy	N	可选值：all、last、new、sequence、time	`all`
domain	N	[JetStream Leafondes]	`HUB`
apiPrefix	N	[JetStream Leafnodes]	`PREFIX`

创建 NATS 服务器

你可以使用 Docker 在本地运行启用了 JetStream 的 NATS 服务器：

docker run -d -p 4222:4222 nats:latest -js

然后你可以使用客户端端口与服务器交互：localhost:4222。

在 Kubernetes 上安装 NATS JetStream，使用 helm：

helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install --set nats.jetstream.enabled=true my-nats nats/nats

这将在 default 命名空间中安装单个 NATS 服务器。要查找与 NATS 交互的服务，请使用：

kubectl get svc my-nats

有关 helm chart 设置的更多信息，请参阅 Helm chart 文档。

创建 JetStream

为特定的主题创建 NATS JetStream 是必不可少的。例如，对于本地运行的 NATS 服务器，使用：

nats -s localhost:4222 stream add myStream --subjects mySubject

示例：竞争消费者模式

假设你希望每条消息仅由一个具有相同 app-id 的应用程序或 Pod 处理。通常，consumerID 元数据规范可以帮助你定义竞争消费者。

由于 NATS JetStream 不支持 consumerID，你需要指定 durableName 和 queueGroupName 来实现竞争消费者模式。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: pubsub
spec:
  type: pubsub.jetstream
  version: v1
  metadata:
  - name: name
    value: "my-conn-name"
  - name: streamName
    value: "my-stream"
  - name: durableName 
    value: "my-durable-subscription"
  - name: queueGroupName
    value: "my-queue-group"

8.9 - KubeMQ

KubeMQ 发布订阅组件的详细文档

组件格式

要设置 KubeMQ 发布订阅，需创建类型为 pubsub.kubemq 的组件。参阅发布订阅代理组件文件以了解如何自动生成 ConsumerID。阅读操作指南：发布与订阅以了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kubemq-pubsub
spec:
  type: pubsub.kubemq
  version: v1
  metadata:
    - name: address
      value: localhost:50000
    - name: store
      value: false
    - name: consumerID
      value: channel1

规范元数据字段

字段	必填	详情	示例
address	Y	KubeMQ 服务器的地址	`"localhost:50000"`
store	N	发布订阅类型，true：发布订阅持久化（EventsStore），false：发布订阅内存（Events）	`true` 或 `false`（默认为 `false`）
consumerID	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息仅由该组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID（`appID`）值。	可设置为字符串值（例如上面示例中的 `"channel1"`）或字符串格式值（例如 `"{podName}"` 等）。查看您可在组件元数据中使用的所有模板标签。
clientID	N	客户端 ID 连接的名称	`sub-client-12345`
authToken	N	用于连接的身份验证 JWT 令牌查看 KubeMQ Authentication	`ew...`
group	N	用于负载均衡的订阅者组	`g1`
disableReDelivery	N	设置在来自应用程序发生错误的情况下是否应重新传递消息	`true` 或 `false`（默认为 `false`）

创建 KubeMQ 代理

获取 KubeMQ 密钥。
等待带有您的密钥的电子邮件确认

您可以使用 Docker 运行 KubeMQ 代理：

docker run -d -p 8080:8080 -p 50000:50000 -p 9090:9090 -e KUBEMQ_TOKEN=<your-key> kubemq/kubemq

然后，您可以使用客户端端口与服务器交互：localhost:50000

获取 KubeMQ 密钥。
等待带有您的密钥的电子邮件确认

然后运行以下 kubectl 命令：

kubectl apply -f https://deploy.kubemq.io/init

kubectl apply -f https://deploy.kubemq.io/key/<your-key>

安装 KubeMQ CLI

前往 KubeMQ CLI 并下载最新版本的 CLI。

浏览 KubeMQ 仪表板

打开浏览器并导航至 http://localhost:8080

安装了 KubeMQCTL 后，运行以下命令：

kubemqctl get dashboard

或者，安装了 kubectl 后，运行 port-forward 命令：

kubectl port-forward svc/kubemq-cluster-api -n kubemq 8080:8080

KubeMQ 文档

访问 KubeMQ 文档以获取更多信息。

8.10 - MQTT

MQTT 发布订阅组件的详细文档

组件格式

要设置 MQTT 发布订阅，请创建类型为 pubsub.mqtt 的组件。请参阅发布订阅代理组件文件以了解如何自动生成 ConsumerID。阅读操作指南：发布和订阅了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt
  version: v1
  metadata:
  - name: url
    value: "tcp://[username][:password]@host.domain[:port]"
  - name: qos
    value: 1
  - name: retain
    value: "false"
  - name: cleanSession
    value: "false"
  - name: consumerID
    value: "channel1"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
url	是	MQTT 代理的地址。可以是 `secretKeyRef` 以使用密钥引用。对于非 TLS 通信，使用 `tcp://` URI 方案。对于 TLS 通信，使用 `ssl://` URI 方案。	`"tcp://[username][:password]@host.domain[:port]"`
consumerID	否	用于连接到 MQTT 代理的客户端 ID（用于消费者连接）。默认为 Dapr 应用 ID。注意：如果未设置 `producerID`，则会在此值后追加 `-consumer` 作为消费者连接的 ID	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式的值（如 `"{podName}"` 等）。请参阅您可以在组件元数据中使用的所有模板标签。
producerID	否	用于连接到 MQTT 代理的客户端 ID（用于生产者连接）。默认为 `{consumerID}-producer`。	`"myMqttProducerApp"`
qos	否	指示消息的服务质量级别（QoS）（更多信息）。默认为 `1`。	`0`、`1`、`2`
retain	否	定义代理是否将消息保存为指定主题的最后一个已知良好值。默认为 `"false"`。	`"true"`、`"false"`
cleanSession	否	如果为 `"true"`，则在发送到 MQTT 代理的连接消息中设置 `clean_session` 标志（更多信息）。默认为 `"false"`。	`"true"`、`"false"`
caCert	使用 TLS 时必填	用于验证服务器 TLS 证书的 PEM 格式证书颁发机构（CA）证书。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	使用 TLS 时必填	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	使用 TLS 时必填	PEM 格式的 TLS 客户端密钥。必须与 `clientCert` 一起使用。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`

启用消息传递重试

MQTT 发布订阅组件没有内置重试策略支持。这意味着边车只会向服务发送一次消息。如果服务将消息标记为未处理，消息将不会被确认回代理。只有当代理重新发送消息时，才会重试。

要使 Dapr 使用更复杂的重试策略，您可以将重试弹性策略应用于 MQTT 发布订阅组件。

这两种重试方式之间存在关键区别：

未确认消息的重新传递完全依赖于代理。Dapr 不保证这一点。某些代理如 emqx、vernemq 等支持它，但这不是 MQTT3 规范的一部分。
使用重试弹性策略会使同一个 Dapr 边车重试重新传递消息。因此是同一个 Dapr 边车和同一个应用程序接收同一条消息。

使用 TLS 进行通信

要配置使用 TLS 进行通信，请确保 MQTT 代理（例如 mosquitto）配置为支持证书，并在组件配置中提供 caCert、clientCert、clientKey 元数据。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt
  version: v1
  metadata:
  - name: url
    value: "ssl://host.domain[:port]"
  - name: qos
    value: 1
  - name: retain
    value: "false"
  - name: cleanSession
    value: "false"
  - name: caCert
    value: ${{ myLoadedCACert }}
  - name: clientCert
    value: ${{ myLoadedClientCert }}
  - name: clientKey
    secretKeyRef:
      name: myMqttClientKey
      key: myMqttClientKey
auth:
  secretStore: <SECRET_STORE_NAME>

请注意，虽然 caCert 和 clientCert 值可能不是密钥，但为了方便起见，也可以从 Dapr 密钥存储中引用它们。

消费共享主题

在消费共享主题时，每个消费者必须具有唯一标识符。默认情况下，应用程序 ID 用于唯一标识每个消费者和发布者。在自托管模式下，每次调用 dapr run 时使用不同的应用程序 ID 足以让它们从同一个共享主题消费。然而，在 Kubernetes 上，应用程序 pod 的多个实例将共享同一个应用程序 ID，从而阻止所有实例消费同一个主题。为了克服这一点，请使用 {uuid} 标签配置组件的 consumerID 元数据，这将在启动时为每个实例分配一个随机生成的 consumerID 值。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt
  version: v1
  metadata:
    - name: consumerID
      value: "{uuid}"
    - name: url
      value: "tcp://admin:public@localhost:1883"
    - name: qos
      value: 1
    - name: retain
      value: "false"
    - name: cleanSession
      value: "true"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

请注意，在这种情况下，每次 Dapr 重启时消费者 ID 的值都是随机的，因此我们也将 cleanSession 设置为 true。

创建 MQTT 代理

您可以使用 Docker 在本地运行 MQTT 代理：

docker run -d -p 1883:1883 -p 9001:9001 --name mqtt eclipse-mosquitto:1.6

然后您可以使用客户端端口与服务器交互：mqtt://localhost:1883

您可以使用以下 yaml 在 kubernetes 中运行 MQTT 代理：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mqtt-broker
  labels:
    app-name: mqtt-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app-name: mqtt-broker
  template:
    metadata:
      labels:
        app-name: mqtt-broker
    spec:
      containers:
        - name: mqtt
          image: eclipse-mosquitto:1.6
          imagePullPolicy: IfNotPresent
          ports:
            - name: default
              containerPort: 1883
              protocol: TCP
            - name: websocket
              containerPort: 9001
              protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: mqtt-broker
  labels:
    app-name: mqtt-broker
spec:
  type: ClusterIP
  selector:
    app-name: mqtt-broker
  ports:
    - port: 1883
      targetPort: default
      name: default
      protocol: TCP
    - port: 9001
      targetPort: websocket
      name: websocket
      protocol: TCP

然后您可以使用客户端端口与服务器交互：tcp://mqtt-broker.default.svc.cluster.local:1883

8.11 - MQTT3

MQTT3 发布订阅组件的详细文档

组件格式

要设置 MQTT3 发布订阅，请创建类型为 pubsub.mqtt3 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅指南了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt3
  version: v1
  metadata:
    - name: url
      value: "tcp://[username][:password]@host.domain[:port]"
    # Optional
    - name: retain
      value: "false"
    - name: cleanSession
      value: "false"
    - name: qos
      value: "1"
    - name: consumerID
      value: "channel1"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储。

规格元数据字段

字段	必填	详情	示例
`url`	Y	MQTT 代理的地址。可以是 `secretKeyRef` 以使用密钥引用。对于非 TLS 通信，使用 `tcp://` URI 协议。对于 TLS 通信，使用 `ssl://` URI 协议。	`"tcp://[username][:password]@host.domain[:port]"`
`consumerID`	N	用于连接到 MQTT 代理的客户端 ID。默认为 Dapr 应用 ID。	可以设置为字符串值（例如上面示例中的 `"channel1"`）或字符串格式值（例如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
`retain`	N	定义消息是否由代理保存为指定主题的最后一个已知良好值。默认为 `"false"`。	`"true"`, `"false"`
`cleanSession`	N	如果为 `"true"`，则设置到 MQTT 代理的连接消息中的 `clean_session` 标志（更多信息）。默认为 `"false"`。	`"true"`, `"false"`
`caCert`	使用 TLS 时必填	用于验证服务器 TLS 证书的 PEM 格式证书颁发机构 (CA) 证书。	参见下面的示例
`clientCert`	使用 TLS 时必填	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	参见下面的示例
`clientKey`	使用 TLS 时必填	PEM 格式的 TLS 客户端密钥。必须与 `clientCert` 一起使用。可以是 `secretKeyRef` 以使用密钥引用。	参见下面的示例
`qos`	N	指示消息的服务质量级别 (QoS)（更多信息）。默认为 `1`。	`0`, `1`, `2`

使用 TLS 进行通信

要配置使用 TLS 的通信，请确保 MQTT 代理（例如 emqx）配置为支持证书，并在组件配置中提供 caCert、clientCert、clientKey 元数据。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt3
  version: v1
  metadata:
    - name: url
      value: "ssl://host.domain[:port]"
  # TLS configuration
    - name: caCert
      value: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    - name: clientCert
      value: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    - name: clientKey
      secretKeyRef:
        name: myMqttClientKey
        key: myMqttClientKey
    # Optional
    - name: retain
      value: "false"
    - name: cleanSession
      value: "false"
    - name: qos
      value: 1

请注意，虽然 caCert 和 clientCert 值可能不是密钥，但为了方便起见，也可以从 Dapr 密钥存储中引用它们。

消费共享主题

在消费共享主题时，每个消费者必须具有唯一的标识符。默认情况下，应用 ID 用于唯一标识每个消费者和发布者。在自托管模式下，为每个 dapr run 调用使用不同的应用 ID 就足以使它们从同一个共享主题消费。然而，在 Kubernetes 上，应用 Pod 的多个实例将共享同一个应用 ID，从而阻止所有实例消费同一个主题。为了克服这一点，请使用 {uuid} 标签（这将在每个实例启动时为其生成一个随机生成的值）或 {podName}（这将使用 Kubernetes 上的 Pod 名称）配置组件的 consumerID 元数据。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mqtt-pubsub
spec:
  type: pubsub.mqtt3
  version: v1
  metadata:
    - name: consumerID
      value: "{uuid}"
    - name: cleanSession
      value: "true"
    - name: url
      value: "tcp://admin:public@localhost:1883"
    - name: qos
      value: 1
    - name: retain
      value: "false"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储。

请注意，在这种情况下，消费者 ID 的值在每次 Dapr 重启时都是随机的，因此您还应该将 cleanSession 设置为 "true"。

建议将 StatefulSets 与共享订阅一起使用。

创建 MQTT3 代理

您可以使用 Docker 在本地运行 MQTT 代理（如 emqx）：

docker run -d -p 1883:1883 --name mqtt emqx:latest

然后您可以使用客户端端口与服务器交互：tcp://localhost:1883

您可以使用以下 yaml 在 kubernetes 中运行 MQTT3 代理：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mqtt-broker
  labels:
    app-name: mqtt-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app-name: mqtt-broker
  template:
    metadata:
      labels:
        app-name: mqtt-broker
    spec:
      containers:
        - name: mqtt
          image: emqx:latest
          imagePullPolicy: IfNotPresent
          ports:
            - name: default
              containerPort: 1883
              protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: mqtt-broker
  labels:
    app-name: mqtt-broker
spec:
  type: ClusterIP
  selector:
    app-name: mqtt-broker
  ports:
    - port: 1883
      targetPort: default
      name: default
      protocol: TCP

然后您可以使用客户端端口与服务器交互：tcp://mqtt-broker.default.svc.cluster.local:1883

8.12 - Pulsar

Pulsar 发布订阅组件的详细文档

组件格式

要设置 Apache Pulsar 发布订阅，需创建一个类型为 pubsub.pulsar 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅指南以了解如何创建和应用发布订阅配置。

关于 Apache Pulsar 的更多信息，请阅读官方文档。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: pulsar-pubsub
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: enableTLS
    value: "false"
  - name: tenant
    value: "public"
  - name: token
    value: "eyJrZXlJZCI6InB1bHNhci1wajU0cXd3ZHB6NGIiLCJhbGciOiJIUzI1NiJ9.eyJzd"
  - name: consumerID
    value: "channel1"
  - name: namespace
    value: "default"
  - name: persistent
    value: "true"
  - name: disableBatching
    value: "false"
  - name: receiverQueueSize
    value: "1000"
  - name: <topic-name>.jsonschema # 为配置的主题设置 json schema 验证
    value: |
      {
        "type": "record",
        "name": "Example",
        "namespace": "test",
        "fields": [
          {"name": "ID","type": "int"},
          {"name": "Name","type": "string"}
        ]
      }
  - name: <topic-name>.avroschema # 为配置的主题设置 avro schema 验证
    value: |
      {
        "type": "record",
        "name": "Example",
        "namespace": "test",
        "fields": [
          {"name": "ID","type": "int"},
          {"name": "Name","type": "string"}
        ]
      }

Warning

上面的示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥。此组件支持将 token 参数和任何其他敏感参数及数据存储为 Kubernetes Secrets。

规范元数据字段

Field	Required	Details	Example
host	Y	Pulsar broker 的地址。默认为 `"localhost:6650"`	`"localhost:6650"` OR `"http://pulsar-pj54qwwdpz4b-pulsar.ap-sg.public.pulsar.com:8080"`
enableTLS	N	启用 TLS。默认值：`"false"`	`"true"`, `"false"`
tenant	N	实例内的主题租户。租户对于 Pulsar 中的多租户至关重要，并跨集群分布。默认值：`"public"`	`"public"`
consumerID	N	用于设置订阅名称或消费者 ID。	可以设置为字符串值（如上面示例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
namespace	N	主题的管理单元，充当相关主题的分组机制。默认值：`"default"`	`"default"`
persistent	N	Pulsar 支持两种主题：持久化和非持久化。对于持久化主题，所有消息都会持久化保存在磁盘上（如果 broker 不是独立的，消息会持久化保存在多个磁盘上），而非持久化主题的数据则不会持久化到存储磁盘。	`"true"`, `"false"`
disableBatching	N	禁用批处理。启用批处理时，默认批处理延迟设置为 10 毫秒，默认批处理大小为 1000 条消息，设置 `disableBatching: true` 将使生产者单独发送消息。默认值：`"false"`	`"true"`, `"false"`
receiverQueueSize	N	设置消费者接收队列的大小。控制在 Dapr 显式调用读取消息之前，消费者可以累积多少消息。默认值：`"1000"`	`"1000"`
batchingMaxPublishDelay	N	batchingMaxPublishDelay 设置发送消息将被批处理的时间段（如果启用了批处理消息）。如果设置为非零值，消息将被排队，直到达到此时间间隔或 batchingMaxMessages（见下文）或 batchingMaxSize（见下文）。有两种有效格式，一种是带单位后缀的分数格式，另一种是作为毫秒处理的纯数字格式。有效的时间单位为 “ns”、“us”（或 “µs”）、“ms”、“s”、“m”、“h”。默认值：`"10ms"`	`"10ms"`, `"10"`
batchingMaxMessages	N	batchingMaxMessages 设置批处理中允许的最大消息数。如果设置为大于 1 的值，消息将被排队，直到达到此阈值或 batchingMaxSize（见下文）已达到或批处理间隔已过去。默认值：`"1000"`	`"1000"`
batchingMaxSize	N	batchingMaxSize 设置批处理中允许的最大字节数。如果设置为大于 1 的值，消息将被排队，直到达到此阈值或 batchingMaxMessages（见上文）已达到或批处理间隔已过去。默认值：`"128KB"`	`"131072"`
.jsonschema	N	为配置的主题强制执行 JSON schema 验证。
.avroschema	N	为配置的主题强制执行 Avro schema 验证。
publicKey	N	用于发布者和消费者加密的公钥。值可以是以下两种选项之一：本地 PEM 证书的文件路径，或证书数据字符串值
privateKey	N	用于消费者加密的私钥。值可以是以下两种选项之一：本地 PEM 证书的文件路径，或证书数据字符串值
keys	N	包含 Pulsar 会话密钥名称的逗号分隔字符串。与 `publicKey` 结合使用，用于发布者加密
processMode	N	启用一次处理多条消息。默认值：`"async"`	`"async"`, `"sync"`
subscribeType	N	Pulsar 支持四种订阅类型。默认值：`"shared"`	`"shared"`, `"exclusive"`, `"failover"`, `"key_shared"`
subscribeInitialPosition	N	订阅位置是开始消费时光标设置的初始位置。默认值：`"latest"`	`"latest"`, `"earliest"`
subscribeMode	N	订阅模式指示光标持久化，持久化订阅保留消息并持久化当前位置。默认值：`"durable"`	`"durable"`, `"non_durable"`
partitionKey	N	设置用于路由策略的消息键。默认值：`""`
`maxConcurrentHandlers`	N	定义并发消息处理程序的最大数量。默认值：`100`	`10`
replicateSubscriptionState	N	启用跨地域复制的 Pulsar 集群的订阅状态复制。默认值：`"false"`	`"true"`, `"false"`

使用 Token 进行身份验证

要使用静态 JWT token 向 pulsar 进行身份验证，您可以使用以下元数据字段：

Field	Required	Details	Example
token	N	用于身份验证的令牌。	如何创建 Pulsar token

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: token
    secretKeyRef:
      name: pulsar
      key:  token

使用 OIDC 进行身份验证

自 v3.0 起，Pulsar 支持 OIDC 身份验证。要启用 OIDC 身份验证，您需要向组件规范提供以下 OAuth2 参数。 OAuth2 身份验证不能与 token 身份验证结合使用。建议您使用密钥引用来存储客户端密钥。 pulsar OAuth2 身份验证器并不专门符合 OIDC，因此您有责任确保字段符合要求。例如，颁发者 URL 必须使用 https 协议，请求的范围包括 openid 等。如果省略 oauth2TokenCAPEM 字段，则在使用 https 连接到 OAuth2 颁发者时将使用系统的证书池。

注意： 元数据值会覆盖文件值。

Field	Required	Details	Example
oauth2CredentialsFile	N	包含 `client_id`、`client_secret`、`issuer_url` 的 JSON 文件。使用此项或下面的单独字段。	`"/path/to/credentials.json"`
oauth2TokenURL	N	从中请求 OIDC client_credentials 令牌的 URL。如果不使用 `oauth2CredentialsFile` 则必需。	`"https://oauth.example.com/token"`
oauth2ClientID	N	OIDC 客户端 ID。如果不使用 `oauth2CredentialsFile` 则必需。	`"my-client-id"`
oauth2ClientSecret	N	OIDC 客户端密钥。如果使用 `oauth2ClientID`（而非 `oauth2ClientSecretPath`）则需要。	`"my-client-secret"`
oauth2ClientSecretPath	N	包含客户端密钥的纯文本文件。需要 `oauth2ClientID` 和 `oauth2TokenURL`。	`"/path/to/client_secret.txt"`
oauth2TokenCAPEM	N	用于连接到 OAuth2 颁发者的 CA PEM 证书束。如果未定义，将使用系统的证书池。	`"---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"`
oauth2Audiences	N	请求的受众的逗号分隔列表。不能为空。	`"my-audience-1,my-audience-2"`
oauth2Scopes	N	请求的范围的逗号分隔列表。不能为空。	`"openid,profile,email"`

直接使用元数据字段

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: oauth2TokenURL
    value: https://oauth.example.com/o/oauth2/token
  - name: oauth2TokenCAPEM
    value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"
  - name: oauth2ClientID
    value: my-client-id
  - name: oauth2ClientSecret
    secretKeyRef:
      name: pulsar-oauth2
      key:  my-client-secret
  - name: oauth2Audiences
    value: "my.pulsar.example.com,another.pulsar.example.com"
  - name: oauth2Scopes
    value: "openid,profile,email"
  - name: oauth2ClientSecretPath
    value: "/path/to/oauth2/client_secret.json"

使用 JSON 凭据文件

您可以将凭据存储为具有以下格式的 JSON 文件：

{
  "client_id": "my-client-id",
  "client_secret": "my-client-secret",
  "issuer_url": "https://oauth.example.com/o/oauth2/token"
}

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: oauth2CredentialsFile
    value: "/path/to/oauth2/credentials.json"
  - name: oauth2TokenCAPEM
    value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"
  - name: oauth2Audiences
    value: "my.pulsar.example.com,another.pulsar.example.com"
  - name: oauth2Scopes
    value: "openid,profile,email"

使用纯文本密钥文件

您可以将客户端密钥仅存储在纯文本文件中：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: oauth2TokenURL
    value: https://oauth.example.com/o/oauth2/token
  - name: oauth2ClientID
    value: my-client-id
  - name: oauth2ClientSecretPath
    value: "/path/to/oauth2/client_secret.txt"
  - name: oauth2TokenCAPEM
    value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"
  - name: oauth2Audiences
    value: "my.pulsar.example.com,another.pulsar.example.com"
  - name: oauth2Scopes
    value: "openid,profile,email"

使用 JSON 凭据文件

您可以将凭据存储为具有以下格式的 JSON 文件：

{
  "client_id": "my-client-id",
  "client_secret": "my-client-secret",
  "issuer_url": "https://oauth.example.com/o/oauth2/token"
}

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: oauth2CredentialsFile
    value: "/path/to/oauth2/credentials.json"
  - name: oauth2TokenCAPEM
    value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"
  - name: oauth2Audiences
    value: "my.pulsar.example.com,another.pulsar.example.com"
  - name: oauth2Scopes
    value: "openid,profile,email"

使用纯文本密钥文件

您可以将客户端密钥仅存储在纯文本文件中：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "pulsar.example.com:6650"
  - name: oauth2TokenURL
    value: https://oauth.example.com/o/oauth2/token
  - name: oauth2ClientID
    value: my-client-id
  - name: oauth2ClientSecretPath
    value: "/path/to/oauth2/client_secret.txt"
  - name: oauth2TokenCAPEM
    value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"
  - name: oauth2Audiences
    value: "my.pulsar.example.com,another.pulsar.example.com"
  - name: oauth2Scopes
    value: "openid,profile,email"

启用消息传递重试

Pulsar 发布订阅组件没有内置对重试策略的支持。这意味着边车仅向服务发送一次消息，并且在发生故障时不会重试。要使 Dapr 使用更复杂的重试策略，您可以将重试弹性策略应用于 Pulsar 发布订阅组件。请注意，将是同一个 Dapr 边车向同一应用实例重新传递消息，而不是其他实例。

延迟队列

调用 Pulsar 发布订阅时，可以通过在请求 url 中使用 metadata 查询参数来提供可选的延迟队列。

这些可选参数名称是 metadata.deliverAt 或 metadata.deliverAfter：

deliverAt：延迟消息在指定时间传递（RFC3339 格式）；例如，"2021-09-01T10:00:00Z"
deliverAfter：延迟消息在指定时间量后传递；例如，"4h5m3s"

示例：

curl -X POST http://localhost:3500/v1.0/publish/myPulsar/myTopic?metadata.deliverAt='2021-09-01T10:00:00Z' \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

或

curl -X POST http://localhost:3500/v1.0/publish/myPulsar/myTopic?metadata.deliverAfter='4h5m3s' \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

启用消息压缩

消息压缩可以减小消息大小，代价是在发布期间稍微增加 CPU 使用率。压缩在生产者级别应用。

Compression Type	Description
`none`	无压缩（默认）
`lz4`	LZ4 压缩 - 快速压缩/解压
`zlib`	ZLib 压缩 - 平衡的压缩比
`zstd`	ZSTD 压缩 - 高压缩比

Compression Level	Description
`default`	所选类型的默认压缩级别
`faster`	优先考虑速度而非压缩比
`better`	优先考虑压缩比而非速度

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: compressionType
    value: lz4
  - name: compressionLevel
    value: faster

注意： 元数据键 compressionType 和 compressionLevel 区分大小写，必须完全按照所示方式指定。压缩在发布消息时应用；消费者无论设置如何都会自动解压。

端到端加密

Dapr 支持设置公钥和私钥对以启用 Pulsar 的端到端加密功能。

从文件证书启用发布者加密

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: publicKey
    value: ./public.key
  - name: keys
    value: myapp.key

从文件证书启用消费者加密

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: publicKey
    value: ./public.key
  - name: privateKey
    value: ./private.key

从值启用发布者加密

注意：建议从密钥引用公钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: publicKey
    value:  "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1KDAM4L8RtJ+nLaXBrBh\nzVpvTemsKVZoAct8A+ShepOHT9lgHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDd\nruXSflvSdmYeFAw3Ypphc1A5oM53wSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/\na3golb36GYFrY0MLFTv7wZ87pmMIPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eK\njpwcg35gccvR6o/UhbKAuc60V1J9Wof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0Qi\nCdpIrXvYtANq0Id6gP8zJvUEdPIgNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ\n3QIDAQAB\n-----END PUBLIC KEY-----\n"
  - name: keys
    value: myapp.key

从值启用消费者加密

注意：建议从密钥引用公钥和私钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.pulsar
  version: v1
  metadata:
  - name: host
    value: "localhost:6650"
  - name: publicKey
    value: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1KDAM4L8RtJ+nLaXBrBh\nzVpvTemsKVZoAct8A+ShepOHT9lgHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDd\nruXSflvSdmYeFAw3Ypphc1A5oM53wSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/\na3golb36GYFrY0MLFTv7wZ87pmMIPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eK\njpwcg35gccvR6o/UhbKAuc60V1J9Wof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0Qi\nCdpIrXvYtANq0Id6gP8zJvUEdPIgNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ\n3QIDAQAB\n-----END PUBLIC KEY-----\n"
  - name: privateKey
    value: "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA1KDAM4L8RtJ+nLaXBrBhzVpvTemsKVZoAct8A+ShepOHT9lg\nHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDdruXSflvSdmYeFAw3Ypphc1A5oM53\nwSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/a3golb36GYFrY0MLFTv7wZ87pmMI\nPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eKjpwcg35gccvR6o/UhbKAuc60V1J9\nWof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0QiCdpIrXvYtANq0Id6gP8zJvUEdPIg\nNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ3QIDAQABAoIBAQCKuHnM4ac/eXM7\nQPDVX1vfgyHc3hgBPCtNCHnXfGFRvFBqavKGxIElBvGOcBS0CWQ+Rg1Ca5kMx3TQ\njSweSYhH5A7pe3Sa5FK5V6MGxJvRhMSkQi/lJZUBjzaIBJA9jln7pXzdHx8ekE16\nBMPONr6g2dr4nuI9o67xKrtfViwRDGaG6eh7jIMlEqMMc6WqyhvI67rlVDSTHFKX\njlMcozJ3IT8BtTzKg2Tpy7ReVuJEpehum8yn1ZVdAnotBDJxI07DC1cbOP4M2fHM\ngfgPYWmchauZuTeTFu4hrlY5jg0/WLs6by8r/81+vX3QTNvejX9UdTHMSIfQdX82\nAfkCKUVhAoGBAOvGv+YXeTlPRcYC642x5iOyLQm+BiSX4jKtnyJiTU2s/qvvKkIu\nxAOk3OtniT9NaUAHEZE9tI71dDN6IgTLQlAcPCzkVh6Sc5eG0MObqOO7WOMCWBkI\nlaAKKBbd6cGDJkwGCJKnx0pxC9f8R4dw3fmXWgWAr8ENiekMuvjSfjZ5AoGBAObd\ns2L5uiUPTtpyh8WZ7rEvrun3djBhzi+d7rgxEGdditeiLQGKyZbDPMSMBuus/5wH\nwfi0xUq50RtYDbzQQdC3T/C20oHmZbjWK5mDaLRVzWS89YG/NT2Q8eZLBstKqxkx\ngoT77zoUDfRy+CWs1xvXzgxagD5Yg8/OrCuXOqWFAoGAPIw3r6ELknoXEvihASxU\nS4pwInZYIYGXpygLG8teyrnIVOMAWSqlT8JAsXtPNaBtjPHDwyazfZrvEmEk51JD\nX0tA8M5ah1NYt+r5JaKNxp3P/8wUT6lyszyoeubWJsnFRfSusuq/NRC+1+KDg/aq\nKnSBu7QGbm9JoT2RrmBv5RECgYBRn8Lj1I1muvHTNDkiuRj2VniOSirkUkA2/6y+\nPMKi+SS0tqcY63v4rNCYYTW1L7Yz8V44U5mJoQb4lvpMbolGhPljjxAAU3hVkItb\nvGVRlSCIZHKczADD4rJUDOS7DYxO3P1bjUN4kkyYx+lKUMDBHFzCa2D6Kgt4dobS\n5qYajQKBgQC7u7MFPkkEMqNqNGu5erytQkBq1v1Ipmf9rCi3iIj4XJLopxMgw0fx\n6jwcwNInl72KzoUBLnGQ9PKGVeBcgEgdI+a+tq+1TJo6Ta+hZSx+4AYiKY18eRKG\neNuER9NOcSVJ7Eqkcw4viCGyYDm2vgNV9HJ0VlAo3RDh8x5spEN+mg==\n-----END RSA PRIVATE KEY-----\n"

分区键

调用 Pulsar 发布订阅时，可以通过在请求 url 中使用 metadata 查询参数来提供可选的分区键。

参数名称是 partitionKey。

示例：

curl -X POST http://localhost:3500/v1.0/publish/myPlusar/myTopic?metadata.partitionKey=key1 \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

消息头

所有其他元数据键/值对（不是 partitionKey）都将在 Pulsar 消息中设置为头。例如，为消息设置 correlationId：

curl -X POST http://localhost:3500/v1.0/publish/myPlusar/myTopic?metadata.correlationId=myCorrelationID&metadata.partitionKey=key1 \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

顺序保证

要确保为订阅特定键的每个消费者按顺序到达消息，必须满足三个条件。

subscribeType 应设置为 key_shared。
必须设置 partitionKey。
processMode 应设置为 sync。

创建 Pulsar 实例

docker run -it \
  -p 6650:6650 \
  -p 8080:8080 \
  --mount source=pulsardata,target=/pulsar/data \
  --mount source=pulsarconf,target=/pulsar/conf \
  apachepulsar/pulsar:2.5.1 \
  bin/pulsar standalone

请参阅以下 Helm chart 文档。

8.13 - RabbitMQ

RabbitMQ 发布订阅组件的详细文档

组件格式

要设置 RabbitMQ 发布订阅，请创建类型为 pubsub.rabbitmq 的组件。请参阅发布订阅代理组件文件以了解如何自动生成 ConsumerID。阅读如何：发布和订阅指南以了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: rabbitmq-pubsub
spec:
  type: pubsub.rabbitmq
  version: v1
  metadata:
  - name: connectionString
    value: "amqp://localhost:5672"
  - name: protocol
    value: amqp  
  - name: hostname
    value: localhost 
  - name: username
    value: username
  - name: password
    value: password  
  - name: consumerID
    value: channel1
  - name: durable
    value: false
  - name: deletedWhenUnused
    value: false
  - name: autoAck
    value: false
  - name: deliveryMode
    value: 0
  - name: requeueInFailure
    value: false
  - name: prefetchCount
    value: 0
  - name: reconnectWait
    value: 0
  - name: concurrencyMode
    value: parallel
  - name: publisherConfirm
    value: false
  - name: enableDeadLetter # Optional enable dead Letter or not
    value: true
  - name: maxLen # Optional max message count in a queue
    value: 3000
  - name: maxLenBytes # Optional maximum length in bytes of a queue.
    value: 10485760
  - name: exchangeKind
    value: fanout
  - name: saslExternal
    value: false
  - name: ttlInSeconds
    value: 60
  - name: clientName
    value: {podName}
  - name: heartBeat
    value: 10s
  - name: publishMessagePropertiesToMetadata
    value: "true"

警告

上述示例使用纯文本字符串作为密钥。建议按照此处所述使用密钥存储来管理密钥。

规格元数据字段

字段	必填	详情	示例
connectionString	Y*	RabbitMQ 连接字符串。与 protocol、hostname、username、password 字段互斥	`amqp://user:pass@localhost:5672`
protocol	N*	RabbitMQ 协议。与 connectionString 字段互斥	`amqp`
hostname	N*	RabbitMQ 主机名。与 connectionString 字段互斥	`localhost`
username	N*	RabbitMQ 用户名。与 connectionString 字段互斥	`username`
password	N*	RabbitMQ 密码。与 connectionString 字段互斥	`password`
consumerID	N	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息只会被组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID（`appID`）的值。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式的值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签
durable	N	是否使用持久化队列。默认为 `"false"`	`"true"`, `"false"`
deletedWhenUnused	N	是否将队列配置为自动删除默认为 `"true"`	`"true"`, `"false"`
autoAck	N	队列消费者是否应自动确认消息。默认为 `"false"`	`"true"`, `"false"`
deliveryMode	N	发布消息时的持久化模式。默认为 `"0"`。RabbitMQ 将 `"2"` 视为持久化，将所有其他数字视为非持久化	`"0"`, `"2"`
requeueInFailure	N	在失败时发送否定确认时是否重新排队。默认为 `"false"`	`"true"`, `"false"`
prefetchCount	N	要预取的消息数量。考虑在生产环境中将其更改为非零值。默认为 `"0"`，这意味着将预取所有可用的消息。	`"2"`
publisherConfirm	N	如果启用，客户端在发布消息后会等待发布者确认。默认为 `"false"`	`"true"`, `"false"`
reconnectWait	N	在连接失败时重新连接之前等待的时间（秒）	`"0"`
concurrencyMode	N	`parallel` 是默认值，允许并行处理多条消息（如果配置了，则受 `app-max-concurrency` 注解限制）。设置为 `single` 可禁用并行处理。在大多数情况下，没有必要更改此设置。	`parallel`, `single`
enableDeadLetter	N	启用将无法处理的消息转发到死信主题。默认为 `"false"`	`"true"`, `"false"`
maxLen	N	队列及其死信队列（如果启用了死信）的最大消息数。如果同时设置了 `maxLen` 和 `maxLenBytes`，则两者都将应用；先达到哪个限制将强制执行。默认为无限制。	`"1000"`
maxLenBytes	N	队列及其死信队列（如果启用了死信）的最大字节长度。如果同时设置了 `maxLen` 和 `maxLenBytes`，则两者都将应用；先达到哪个限制将强制执行。默认为无限制。	`"1048576"`
exchangeKind	N	RabbitMQ 交换机的交换机类型。默认为 `"fanout"`。	`"fanout"`,`"topic"`
saslExternal	N	使用 TLS 时，是否应从附加字段（例如 CN）获取用户名。请参阅 RabbitMQ 身份验证机制。默认为 `"false"`。	`"true"`, `"false"`
ttlInSeconds	N	在组件级别设置消息 TTL，可以根据每个请求的消息级 TTL 覆盖。	`"60"`
caCert	使用 TLS 时必需	用于验证服务器 TLS 证书的 PEM 格式证书颁发机构 (CA) 证书。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	使用 TLS 时必需	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	使用 TLS 时必需	PEM 格式的 TLS 客户端密钥。必须与 `clientCert` 一起使用。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`
clientName	N	此 RabbitMQ 客户端提供的连接名称是一个自定义标识符。如果设置，该标识符将在 RabbitMQ 服务器日志条目和管理 UI 中提及。可以设置为 {uuid}、{podName} 或 {appID}，Dapr 运行时会将其替换为实际值。	`"app1"`, `{uuid}`, `{podName}`, `{appID}`
heartBeat	N	定义与服务器的心跳间隔，检测与 RabbitMQ 服务器的对等 TCP 连接的存活状态。默认为 `10s`。	`"10s"`
`publishMessagePropertiesToMetadata`	N	是否将 AMQP 消息属性（头部、消息 ID 等）发布到元数据。	“true”, “false”

使用 TLS 进行通信

要配置使用 TLS 进行通信，请确保 RabbitMQ 节点已启用 TLS，并在组件配置中提供 caCert、clientCert、clientKey 元数据。例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: rabbitmq-pubsub
spec:
  type: pubsub.rabbitmq
  version: v1
  metadata:
  - name: host
    value: "amqps://localhost:5671"
  - name: consumerID
    value: myapp
  - name: durable
    value: false
  - name: deletedWhenUnused
    value: false
  - name: autoAck
    value: false
  - name: deliveryMode
    value: 0
  - name: requeueInFailure
    value: false
  - name: prefetchCount
    value: 0
  - name: reconnectWait
    value: 0
  - name: concurrencyMode
    value: parallel
  - name: publisherConfirm
    value: false
  - name: enableDeadLetter # Optional enable dead Letter or not
    value: true
  - name: maxLen # Optional max message count in a queue
    value: 3000
  - name: maxLenBytes # Optional maximum length in bytes of a queue.
    value: 10485760
  - name: exchangeKind
    value: fanout
  - name: saslExternal
    value: false
  - name: caCert
    value: ${{ myLoadedCACert }}
  - name: clientCert
    value: ${{ myLoadedClientCert }}
  - name: clientKey
    secretKeyRef:
      name: myRabbitMQClientKey
      key: myRabbitMQClientKey

注意，虽然 caCert 和 clientCert 值可能不是密钥，但为了方便起见，也可以从 Dapr 密钥存储中引用它们。

启用消息传递重试

RabbitMQ 发布订阅组件没有内置对重试策略的支持。这意味着边车只向服务发送一条消息。当服务返回结果时，无论消息是否被正确处理，该消息都将被标记为已消费。请注意，这是所有 Dapr PubSub 组件的常见行为，而不仅仅是 RabbitMQ。当 autoAck 设置为 false 且 requeueInFailure 设置为 true 时，Dapr 可以尝试第二次重新传递消息。

要使 Dapr 使用更复杂的重试策略，您可以将重试弹性策略应用于 RabbitMQ 发布订阅组件。

两种重试消息的方式之间存在关键区别：

当使用 autoAck = false 和 requeueInFailure = true 时，RabbitMQ 负责重新传递消息，任何订阅者都可以获得重新传递的消息。如果您有多个消费者实例，那么另一个消费者可能会获得该消息。这通常是更好的方法，因为如果存在暂时性故障，不同的工作人员更有可能成功处理消息。
使用弹性功能使同一个 Dapr 边车重试重新传递消息。因此，它将是同一个 Dapr 边车和同一个应用程序接收同一条消息。

创建 RabbitMQ 服务器

您可以使用 Docker 在本地运行 RabbitMQ 服务器：

docker run -d --hostname my-rabbit --name some-rabbit rabbitmq:3

然后，您可以使用客户端端口与服务器交互：localhost:5672。

在 Kubernetes 上安装 RabbitMQ 的最简单方法是使用 Helm chart：

helm install rabbitmq stable/rabbitmq

查看 chart 输出并获取用户名和密码。

这会将 RabbitMQ 安装到 default 命名空间中。要与 RabbitMQ 交互，请使用以下命令查找服务：kubectl get svc rabbitmq。

例如，如果使用上面的示例安装，RabbitMQ 服务器客户端地址将是：

rabbitmq.default.svc.cluster.local:5672

使用主题交换机路由消息

将 exchangeKind 设置为 "topic" 使用主题交换机，这通常用于消息的多播路由。要使用主题交换机路由消息，您必须设置以下元数据：

routingKey：
具有路由键的消息根据订阅时元数据中定义的 routing key 路由到一个或多个队列。
queueName：
如果您不设置 queueName，则只创建一个队列，所有路由键都将路由到该队列。这意味着所有订阅者都将绑定到该队列，这将无法产生所需的结果。

例如，如果应用程序配置了路由键 keyA 和 queueName 为 queue-A：

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: orderspubsub
spec:
  topic: B
  routes: 
    default: /B
  pubsubname: pubsub
  metadata:
    routingKey: keyA
    queueName: queue-A

它将接收路由键为 keyA 的消息，而不会接收具有其他路由键的消息。

// 使用路由键 `keyA` 发布消息，这些消息将被上面的示例接收。
client.PublishEvent(context.Background(), "pubsub", "B", []byte("this is a message"), dapr.PublishEventWithMetadata(map[string]string{"routingKey": "keyA"}))
// 使用路由键 `keyB` 发布消息，这些消息将不会被上面的示例接收。
client.PublishEvent(context.Background(), "pubsub", "B", []byte("this is another message"), dapr.PublishEventWithMetadata(map[string]string{"routingKey": "keyB"}))

绑定多个 `routingKey`

多个路由键可以用逗号分隔。
下面的示例绑定三个 routingKey：keyA、keyB 和 ""。注意空键的绑定方法。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: orderspubsub
spec:
  topic: B
  routes: 
    default: /B
  pubsubname: pubsub
  metadata:
    routingKey: keyA,keyB,

有关更多信息，请参阅 rabbitmq exchanges。

使用优先级队列

Dapr 支持 RabbitMQ 优先级队列。要为队列设置优先级，请使用 maxPriority 主题订阅元数据。

声明式优先级队列示例

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: pubsub
spec:
  topic: checkout
  routes: 
    default: /orders
  pubsubname: order-pub-sub
  metadata:
    maxPriority: 3

编程式优先级队列示例

@app.route('/dapr/subscribe', methods=['GET'])
def subscribe():
    subscriptions = [
      {
        'pubsubname': 'pubsub',
        'topic': 'checkout',
        'routes': {
          'default': '/orders'
        },
        'metadata': {'maxPriority': '3'}
      }
    ]
    return jsonify(subscriptions)

const express = require('express')
const bodyParser = require('body-parser')
const app = express()
app.use(bodyParser.json({ type: 'application/*+json' }));

const port = 3000

app.get('/dapr/subscribe', (req, res) => {
  res.json([
    {
      pubsubname: "pubsub",
      topic: "checkout",
      routes: {
        default: '/orders'
      },
      metadata: {
        maxPriority: '3'
      }
    }
  ]);
})

package main

	"encoding/json"
	"net/http"

const appPort = 3000

type subscription struct {
	PubsubName string            `json:"pubsubname"`
	Topic      string            `json:"topic"`
	Metadata   map[string]string `json:"metadata,omitempty"`
	Routes     routes            `json:"routes"`
}

type routes struct {
	Rules   []rule `json:"rules,omitempty"`
	Default string `json:"default,omitempty"`
}

// This handles /dapr/subscribe
func configureSubscribeHandler(w http.ResponseWriter, _ *http.Request) {
	t := []subscription{
		{
			PubsubName: "pubsub",
			Topic:      "checkout",
			Routes: routes{
				Default: "/orders",
			},
      Metadata: map[string]string{
        "maxPriority": "3"
      },
		},
	}

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(t)
}

发布消息时设置优先级

要为消息设置优先级，请将发布元数据键 maxPriority 添加到发布端点或 SDK 方法。

curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders?metadata.priority=3 -H "Content-Type: application/json" -d '{"orderId": "100"}'

with DaprClient() as client:
        result = client.publish_event(
            pubsub_name=PUBSUB_NAME,
            topic_name=TOPIC_NAME,
            data=json.dumps(orderId),
            data_content_type='application/json',
            metadata= { 'priority': '3' })

await client.pubsub.publish(PUBSUB_NAME, TOPIC_NAME, orderId, { 'priority': '3' });

client.PublishEvent(ctx, PUBSUB_NAME, TOPIC_NAME, []byte(strconv.Itoa(orderId)), map[string]string{"priority": "3"})

使用仲裁队列

默认情况下，Dapr 创建 classic 队列。要创建 quorum 队列，请将以下元数据添加到您的发布订阅订阅中

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: pubsub
spec:
  topic: checkout
  routes: 
    default: /orders
  pubsubname: order-pub-sub
  metadata:
    queueType: quorum

生存时间

您可以在消息级别或组件级别设置生存时间 (TTL) 值。使用组件规格中的 ttlInSeconds 字段设置默认的组件级 TTL。

注意

如果您同时设置了组件级和消息级 TTL，则默认的组件级 TTL 将被忽略，而使用消息级 TTL。

单一活跃消费者

RabbitMQ 单一活跃消费者设置确保一次只有一个消费者处理来自队列的消息，并在活跃消费者被取消或失败时切换到另一个注册的消费者。当消息必须按照到达队列的精确顺序消费并且不支持多实例分布式处理时，可能需要这种方法。当此选项在队列上由 Dapr 启用时，Dapr 运行时的实例将成为单一活跃消费者。为了允许另一个应用程序实例在失败时接管，Dapr 运行时必须探测应用程序的健康状况并取消订阅发布订阅组件。

注意

此模式将阻止应用程序扩展，因为只有一个实例可以处理负载。虽然这对于与遗留或敏感应用程序的 Dapr 集成可能很有趣，但如果您需要可扩展性，您应该考虑允许分布式处理的设计。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: pubsub
spec:
  topic: orders
  routes:
    default: /orders
  pubsubname: order-pub-sub
  metadata:
    singleActiveConsumer: "true"

将消息属性发布到元数据

要启用发布到元数据中的消息属性，请在组件规格中将 publishMessagePropertiesToMetadata 字段设置为 "true"。这将包括消息 ID、时间戳和标头等属性在已发布消息的元数据中。

8.14 - Redis Streams

Redis Streams 发布订阅组件的详细文档

组件格式

要设置 Redis Streams 发布订阅，请创建一个类型为 pubsub.redis 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: redis-pubsub
spec:
  type: pubsub.redis
  version: v1
  metadata:
  - name: redisHost
    value: localhost:6379
  - name: redisPassword
    value: "KeFg23!"
  - name: consumerID
    value: "channel1"
  - name: useEntraID
    value: "true"
  - name: enableTLS
    value: "false"

警告

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
redisHost	Y	redis 主机的连接字符串。如果 `"redisType"` 为 `"cluster"`，则可以是多个以逗号分隔的主机或单个主机。使用 Redis Sentinel（`"failover"` 为 `"true"`）时，也可以提供多个 sentinel 地址，以逗号分隔。	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379`
redisPassword	N	Redis 主机的密码。无默认值。可以是 `secretKeyRef` 以使用密钥引用	`""`, `"KeFg23!"`
redisUsername	N	Redis 主机的用户名。默认为空。请确保你的 redis 服务器版本为 6 或以上，并且已正确创建 acl 规则。	`""`, `"default"`
consumerID	N	消费者组 ID。	可设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
useEntraID	N	为 Azure Cache for Redis 实现 EntraID 支持。在启用此功能之前： `redisHost` 名称必须以 `"server:port"` 的形式指定必须启用 TLS 在创建 Redis 实例 > Azure Cache for Redis下了解有关此设置的更多信息	`"true"`, `"false"`
enableTLS	N	如果 Redis 实例支持使用公共证书的 TLS，可以配置为启用或禁用。默认为 `"false"`	`"true"`, `"false"`
clientCert	N	客户端证书的内容，用于需要客户端证书的 Redis 实例。必须与 `clientKey` 一起使用，并且 `enableTLS` 必须设置为 true。建议按照此处所述使用密钥存储	`"----BEGIN CERTIFICATE-----\nMIIC..."`
clientKey	N	客户端私钥的内容，与 `clientCert` 一起用于身份验证。建议按照此处所述使用密钥存储	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
redeliverInterval	N	检查待重新传递消息的间隔时间。可以使用 Go 持续时间字符串（例如 “ms”、“s”、“m”）或毫秒数。默认为 `"60s"`。`"0"` 禁用重新传递。	`"30s"`, `"5000"`
processingTimeout	N	消息在尝试重新传递之前必须待处理的时间量。可以使用 Go 持续时间字符串（例如 “ms”、“s”、“m”）或毫秒数。默认为 `"15s"`。`"0"` 禁用重新传递。	`"60s"`, `"600000"`
queueDepth	N	用于处理的消息队列大小。默认为 `"100"`。	`"1000"`
concurrency	N	处理消息的并发工作线程数。默认为 `"10"`。	`"15"`
redisType	N	redis 的类型。有两个有效值，一个是 `"node"` 用于单节点模式，另一个是 `"cluster"` 用于 redis 集群模式。默认为 `"node"`。	`"cluster"`
redisDB	N	连接到 redis 后选择的数据库。如果 `"redisType"` 为 `"cluster"`，则忽略此选项。默认为 `"0"`。	`"0"`
redisMaxRetries	N	放弃前重试命令的最大次数。默认为不重试失败的命令。	`"5"`
redisMinRetryInterval	N	每次重试之间 redis 命令的最小退避时间。默认为 `"8ms"`；`"-1"` 禁用退避。	`"8ms"`
redisMaxRetryInterval	N	每次重试之间 redis 命令的最大退避时间。默认为 `"512ms"`；`"-1"` 禁用退避。	`"5s"`
dialTimeout	N	建立新连接的拨号超时时间。默认为 `"5s"`。	`"5s"`
readTimeout	N	socket 读取的超时时间，如果设置为 `"0s"`，读取将是阻塞的。如果达到超时，redis 命令将因超时而失败而不是阻塞。默认为 `"0s"`，`"-1"` 表示无超时。	`"3s"`
writeTimeout	N	socket 写入的超时时间。如果达到超时，redis 命令将因超时而失败而不是阻塞。默认为 readTimeout。	`"3s"`
poolSize	N	socket 连接的最大数量。默认为 runtime.NumCPU 报告的每个 CPU 10 个连接。	`"20"`
poolTimeout	N	如果所有连接都忙，客户端等待连接的时间，然后返回错误。默认为 readTimeout + 1 秒。	`"5s"`
maxConnAge	N	客户端关闭连接的连接时长。默认为不关闭旧连接。	`"30m"`
minIdleConns	N	保持打开的最小空闲连接数，以避免与新关联的性能下降。默认为 `"0"`。	`"2"`
idleCheckFrequency	N	空闲连接回收器进行空闲检查的频率。默认为 `"1m"`。`"-1"` 禁用空闲连接回收器。	`"-1"`
idleTimeout	N	客户端关闭空闲连接的时间量。应小于服务器的超时时间。默认为 `"5m"`。`"-1"` 禁用空闲超时检查。	`"10m"`
failover	N	启用故障转移配置的属性。需要设置 sentinelMasterName。启用后，redisHost 应包含 sentinel 地址。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	sentinel 主节点名称。请参阅 Redis Sentinel 文档	`""`, `"mymaster"`
sentinelUsername	N	Redis Sentinel 的用户名。仅当 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"username"`
sentinelPassword	N	Redis Sentinel 的密码。仅当 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"password"`
maxLenApprox	N	流中的最大项目数。当达到指定长度时，旧条目将自动驱逐，以使流保持恒定大小。默认为无限制。	`"10000"`
streamTTL	N	流条目的 TTL 持续时间。超过此持续时间的条目将被驱逐。这是一个近似值，因为它是通过使用 ‘~’ 修饰符的 Redis 流 `MINID` 修剪来实现的。实际保留可能包含略多于 TTL 严格定义的条目，因为 Redis 优化了修剪操作以提高效率，可能会保留一些额外的条目。	`"30d"`

创建 Redis 实例

Dapr 可以使用任何 Redis 实例——容器化的、在本地开发机器上运行的或托管的云服务，只要 Redis 的版本是 5.x 或 6.x。

Dapr CLI 将自动为您创建和设置 Redis Streams 实例。当您运行 dapr init 时，Redis 实例将通过 Docker 安装，组件文件将在默认目录中创建。（$HOME/.dapr/components 目录或 Windows 上的 %USERPROFILE%\.dapr\components）。

您可以使用 Helm 在我们的 Kubernetes 集群中快速创建 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis --set image.tag=6.2

运行 kubectl get pods 以查看现在集群中运行的 Redis 容器。

在 redis.yaml 文件中添加 redis-master:6379 作为 redisHost。例如：

    metadata:
    - name: redisHost
      value: redis-master:6379

接下来，我们将获取 Redis 密码，具体取决于我们使用的操作系统：
- Windows：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" > encoded.b64，这将创建一个包含编码密码的文件。接下来，运行 certutil -decode encoded.b64 password.txt，这将把您的 redis 密码放入名为 password.txt 的文本文件中。复制密码并删除这两个文件。
- Linux/MacOS：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode 并复制输出的密码。
将此密码作为 redisPassword 值添加到您的 redis.yaml 文件中。例如：
```
    - name: redisPassword
      value: "lhDOkwTlp0"
```

AWS Redis

使用官方 Microsoft 文档创建 Azure Cache for Redis 实例。
实例创建后，从 Azure 门户获取主机名（FQDN）和您的访问密钥。
- 对于主机名：
  - 导航到资源的概览页面。
  - 复制主机名值。
- 对于您的访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存您的密钥。
将您的密钥和主机名添加到 Dapr 可以应用到集群的 redis.yaml 文件中。
- 如果您正在运行示例，请将主机和密钥添加到提供的 redis.yaml 中。
- 如果您从头开始创建项目，请按照组件格式部分中的说明创建 redis.yaml 文件。
将 redisHost 键设置为 [上一步的主机名]:6379，将 redisPassword 键设置为您之前保存的密钥。
**注意：**在生产级应用程序中，请遵循密钥管理说明来安全地管理您的密钥。
启用 EntraID 支持：
- 在您的 Azure Redis 服务器上启用 Entra ID 身份验证。这可能需要几分钟。
- 将 useEntraID 设置为 "true" 以实现 Azure Cache for Redis 的 EntraID 支持。
将 enableTLS 设置为 "true" 以支持 TLS。

注意：useEntraID 假定您的 UserPrincipal（通过 AzureCLICredential）或系统分配的托管标识具有 RedisDataOwner 角色权限。如果使用用户分配的标识，您需要指定 azureClientID 属性。

GCP Cloud MemoryStore

注意

Dapr CLI 在自托管模式下作为 dapr init 命令的一部分自动部署本地 redis 实例。

Redis Sentinel 配置

使用 Redis Sentinel 实现高可用性时，将 redisType 设置为 "node"，使用 failover: "true" 启用故障转移模式，并提供 sentinel 主节点名称。可以在 redisHost 字段中指定多个以逗号分隔的 sentinel 地址以实现冗余。

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: redis-pubsub
spec:
  type: pubsub.redis
  version: v1
  metadata:
  - name: redisHost
    value: "sentinel1:26379,sentinel2:26379,sentinel3:26379"
  - name: redisType
    value: "node"
  - name: failover
    value: "true"
  - name: sentinelMasterName
    value: "mymaster"
```

弹性和重新传递

Redis Streams 发布订阅组件遵循 Dapr 弹性策略。在您的应用程序处理程序返回（成功、重试或丢弃）后，组件向 Redis 确认消息。Redis 然后停止重新传递该消息。重试和死信行为由您的弹性策略控制（例如 maxRetries 和重试持续时间）。

8.15 - RocketMQ

RocketMQ 发布订阅组件的详细文档

组件格式

要设置 RocketMQ 发布订阅，需创建一个类型为 pubsub.rocketmq 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 如何自动生成。阅读如何操作：发布和订阅指南了解如何创建和应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: rocketmq-pubsub
spec:
  type: pubsub.rocketmq
  version: v1
  metadata:
    - name: instanceName
      value: dapr-rocketmq-test
    - name: consumerGroup
      value: dapr-rocketmq-test-g-c
    - name: producerGroup 
      value: dapr-rocketmq-test-g-p
    - name: consumerID
      value: channel1
    - name: nameSpace
      value: dapr-test
    - name: nameServer
      value: "127.0.0.1:9876,127.0.0.2:9876"
    - name: retries
      value: 3
    - name: consumerModel
      value: "clustering"
    - name: consumeOrderly
      value: false

警告

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	默认值	示例
instanceName	N	实例名称	`time.Now().String()`	`dapr-rocketmq-test`
consumerGroup	N	消费者组名称。推荐。如果 `producerGroup` 为 `null`，则使用 `groupName`。		`dapr-rocketmq-test-g-c`
producerGroup (consumerID)	N	生产者组名称。推荐。如果 `producerGroup` 为 `null`，则使用 `consumerID`。如果 `consumerID` 也为 null，则使用 `groupName`。		`dapr-rocketmq-test-g-p`
consumerID	N	消费者 ID（消费者标签）将一个或多个消费者组织到一个组中。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，一条消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）的值。	可设置为字符串值（如上面示例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
groupName	N	消费者/生产者组名称。已弃用。		`dapr-rocketmq-test-g`
nameSpace	N	RocketMQ 命名空间		`dapr-rocketmq`
nameServerDomain	N	RocketMQ 名称服务器域名		`https://my-app.net:8080/nsaddr`
nameServer	N	RocketMQ 名称服务器，用 “,” 或 “;” 分隔		`127.0.0.1:9876;127.0.0.2:9877,127.0.0.3:9877`
accessKey	N	访问密钥（用户名）		`"admin"`
secretKey	N	密钥（密码）		`"password"`
securityToken	N	安全令牌
retries	N	向代理发送消息的重试次数	`3`	`3`
producerQueueSelector (queueSelector)	N	生产者队列选择器。队列选择器有五种实现：`hash`、`random`、`manual`、`roundRobin`、`dapr`。	`dapr`	`hash`
consumerModel	N	定义消息如何传递给每个消费者客户端的消息模型。RocketMQ 支持两种消息模型：`clustering` 和 `broadcasting`。	`clustering`	`broadcasting`、`clustering`
fromWhere (consumeFromWhere)	N	消费者启动时的消费点。有三个消费点：`CONSUME_FROM_LAST_OFFSET`、`CONSUME_FROM_FIRST_OFFSET`、`CONSUME_FROM_TIMESTAMP`	`CONSUME_FROM_LAST_OFFSET`	`CONSUME_FROM_LAST_OFFSET`
consumeTimestamp	N	以秒精度回溯消费时间。时间格式为 `yyyymmddhhmmss`。例如，`20131223171201` 表示时间为 17:12:01，日期为 2013 年 12 月 23 日	`time.Now().Add(time.Minute * (-30)).Format("20060102150405")`	`20131223171201`
consumeOrderly	N	确定是否使用 FIFO 顺序的有序消息。	`false`	`false`
consumeMessageBatchMaxSize	N	批量消费大小，超出范围 `[1, 1024]`	`512`	`10`
consumeConcurrentlyMaxSpan	N	并发最大跨度偏移量。这对顺序消费没有影响。范围：`[1, 65535]`	`1000`	`1000`
maxReconsumeTimes	N	最大重新消费次数。`-1` 表示 16 次。如果消息在成功之前重新消费的次数超过 {@link maxReconsumeTimes}，它们将被定向到删除队列。	顺序消息为 `MaxInt32`；并发消息为 `16`	`16`
autoCommit	N	启用自动提交	`true`	`false`
consumeTimeout	N	消息可能阻塞消费线程的最长时间。时间单位：分钟	`15`	`15`
consumerPullTimeout	N	Socket 超时时间（毫秒）
pullInterval	N	消息拉取间隔	`100`	`100`
pullBatchSize	N	一次从代理拉取的消息数量。如果 `pullBatchSize` 为 `null`，则使用 `ConsumerBatchSize`。`pullBatchSize` 超出范围 `[1, 1024]`	`32`	`10`
pullThresholdForQueue	N	队列级别的流控阈值。每个消息队列默认最多缓存 1000 条消息。考虑 `PullBatchSize` - 瞬时值可能会超过限制。范围：`[1, 65535]`	`1024`	`1000`
pullThresholdForTopic	N	主题级别的流控阈值。如果 `pullThresholdForTopic` 不受限，`pullThresholdForQueue` 的值将被覆盖并基于 `pullThresholdForTopic` 计算。例如，如果 `pullThresholdForTopic` 的值为 1000，并且为此消费者分配了 10 个消息队列，那么 `pullThresholdForQueue` 将被设置为 100。范围：`[1, 6553500]`	`-1(不限)`	`10`
pullThresholdSizeForQueue	N	限制队列级别的缓存消息大小。考虑 `pullBatchSize` - 瞬时值可能会超过限制。消息的大小仅通过消息体测量，因此不准确。范围：`[1, 1024]`	`100`	`100`
pullThresholdSizeForTopic	N	限制主题级别的缓存消息大小。如果 `pullThresholdSizeForTopic` 不受限，`pullThresholdSizeForQueue` 的值将被覆盖并基于 `pullThresholdSizeForTopic` 计算。例如，如果 `pullThresholdSizeForTopic` 的值为 1000 MiB，并且为此消费者分配了 10 个消息队列，那么 `pullThresholdSizeForQueue` 将被设置为 100 MiB。范围：`[1, 102400]`	`-1`	`100`
content-type	N	消息内容类型。	`"text/plain"`	`"application/cloudevents+json; charset=utf-8"`、`"application/octet-stream"`
logLevel	N	日志级别	`warn`	`info`
sendTimeOut	N	向 RocketMQ 的代理发送消息的超时时间，以纳秒为单位测量。已弃用。	3 秒	`10000000000`
sendTimeOutSec	N	发布消息的超时时长（秒）。如果 `sendTimeOutSec` 为 `null`，则使用 `sendTimeOut`。	3 秒	`3`
mspProperties	N	此集合中的 RocketMQ 消息属性在数据分离中传递给 APP。用 “,” 分隔多个属性		`key,mkey`

出于向后兼容的原因，元数据中支持以下值，但不鼓励使用。

字段（支持但已弃用）	必填	详情	示例
groupName	N	RocketMQ 发布者的生产者组名称	`"my_unique_group_name"`
sendTimeOut	N	发布消息的超时时长（纳秒）	`0`
consumerBatchSize	N	一次从代理拉取的消息数量	`32`

设置 RocketMQ

请参阅 https://rocketmq.apache.org/docs/quick-start/ 以设置本地 RocketMQ 实例。

每次调用元数据字段

分区键

调用 RocketMQ 发布订阅时，可以通过在请求 URL 中使用 metadata 查询参数来提供可选的分区键。

您需要在 metadata 中指定 rocketmq-tag、"rocketmq-key"、rocketmq-shardingkey、rocketmq-queue

示例：

curl -X POST http://localhost:3500/v1.0/publish/myRocketMQ/myTopic?metadata.rocketmq-tag=?&metadata.rocketmq-key=?&metadata.rocketmq-shardingkey=key&metadata.rocketmq-queue=1 \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "message": "Hi"
        }
      }'

QueueSelector

RocketMQ 组件总共包含五个队列选择器。RocketMQ 客户端提供以下队列选择器：

HashQueueSelector
RandomQueueSelector
RoundRobinQueueSelector
ManualQueueSelector

要了解有关这些 RocketMQ 客户端队列选择器的更多信息，请阅读 RocketMQ 文档。

Dapr RocketMQ 组件实现了以下队列选择器：

DaprQueueSelector

本文重点介绍 DaprQueueSelector 的设计。

DaprQueueSelector

DaprQueueSelector 集成了三个队列选择器：

HashQueueSelector
RoundRobinQueueSelector
ManualQueueSelector

DaprQueueSelector 从请求参数中获取队列 ID。您可以通过运行以下命令来设置队列 ID：

http://localhost:3500/v1.0/publish/myRocketMQ/myTopic?metadata.rocketmq-queue=1

上述方法实现了 ManualQueueSelector。

接下来，DaprQueueSelector 尝试：

获取 ShardingKey
对 ShardingKey 进行哈希处理以确定队列 ID。

您可以通过以下方式设置 ShardingKey：

http://localhost:3500/v1.0/publish/myRocketMQ/myTopic?metadata.rocketmq-shardingkey=key

如果 ShardingKey 不存在，则使用 RoundRobin 算法来确定队列 ID。

8.16 - Solace-AMQP

Solace-AMQP 发布订阅组件的详细文档

组件格式

要设置 Solace-AMQP 发布订阅，需创建类型为 pubsub.solace.amqp 的组件。请参阅发布订阅代理组件文件以了解 ConsumerID 的自动生成方式。阅读操作指南：发布与订阅以了解如何创建并应用发布订阅配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: solace
spec:
  type: pubsub.solace.amqp
  version: v1
  metadata:
    - name: url
      value: 'amqp://localhost:5672'
    - name: username
      value: 'default'
    - name: password
      value: 'default'
    - name: consumerID
      value: 'channel1'

警告

上述示例将密钥以纯文本形式使用。建议使用密钥存储来管理密钥，如此处所述。

规范元数据字段

字段	必填	详情	示例
url	Y	AMQP 代理的地址。可使用 `secretKeyRef` 引用密钥。非 TLS 通信使用 `amqp://` URI 方案。 TLS 通信使用 `amqps://` URI 方案。	`"amqp://host.domain[:port]"`
username	Y	连接到代理的用户名。仅在未指定 anonymous 或其设置为 `false` 时必需。	`default`
password	Y	连接到代理的密码。仅在未指定 anonymous 或其设置为 `false` 时必需。	`default`
consumerID	N	消费者 ID（consumer tag）将一个或多个消费者组织成一个组。相同消费者 ID 的消费者作为单一虚拟消费者协作；例如，一条消息仅由组内的一个消费者处理一次。若未提供 `consumerID`，Dapr 运行时会将其设置为 Dapr 应用程序 ID（`appID`）的值。	可设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看组件元数据中可使用的所有模板标签。
anonymous	N	在不验证凭据的情况下连接到代理。仅在代理上启用时有效。若设置为 `true`，则无需用户名和密码。	`true`
caCert	使用 TLS 时必需	用于验证服务器 TLS 证书的 PEM 格式证书颁发机构（CA）证书。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	使用 TLS 时必需	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	使用 TLS 时必需	PEM 格式的 TLS 客户端私钥。必须与 `clientCert` 一起使用。可使用 `secretKeyRef` 引用密钥。	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`

使用 TLS 进行通信

要配置使用 TLS 的通信：

确保 Solace 代理配置为支持证书。
在组件配置中提供 caCert、clientCert 和 clientKey 元数据。

例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: solace
spec:
  type: pubsub.solace.amqp
  version: v1
  metadata:
  - name: url
    value: "amqps://host.domain[:port]"
  - name: username
    value: 'default'
  - name: password
    value: 'default'
  - name: caCert
    value: ${{ myLoadedCACert }}
  - name: clientCert
    value: ${{ myLoadedClientCert }}
  - name: clientKey
    secretKeyRef:
      name: mySolaceClientKey
      key: mySolaceClientKey
auth:
  secretStore: <SECRET_STORE_NAME>

虽然 caCert 和 clientCert 值可能不是密钥，但为方便起见，它们也可以从 Dapr 密钥存储中引用。

向主题和队列发布/订阅消息

默认情况下，消息通过主题进行发布和订阅。如果您希望目标是队列，请在主题前加上 queue: 前缀，Solace AMQP 组件将连接到队列。

创建 Solace 代理

您可以使用 Docker 在本地运行 Solace 代理：

docker run -d -p 8080:8080 -p 55554:55555 -p 8008:8008 -p 1883:1883 -p 8000:8000 -p 5672:5672 -p 9000:9000 -p 2222:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --name=solace solace/solace-pubsub-standard

然后，您可以使用客户端端口与服务器交互：mqtt://localhost:5672

您还可以在 Solace Cloud 上注册免费的 SaaS 代理。

9 - 密钥存储组件规格

与 Dapr 对接的受支持的密钥存储

下表列出了 Dapr 密钥管理构建块支持的密钥存储。了解如何为 Dapr 密钥管理设置不同的密钥存储。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Alibaba Cloud

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
AlibabaCloud OOS Parameter Store		Alpha	v1	1.6

Amazon Web Services (AWS)

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
AWS Secrets Manager	✅	Beta	v1	1.15
AWS SSM Parameter Store		Alpha	v1	1.1

Generic

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
HashiCorp Vault	✅	Stable	v1	1.10
Kubernetes secrets	✅	Stable	v1	1.0
Local environment variables		Stable	v1	1.9
Local file	✅	Stable	v1	1.9
OpenBao	✅	Stable	v1	1.16

Google Cloud Platform (GCP)

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
GCP Secret Manager		Alpha	v1	1.0

HuaweiCloud Cloud

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
HuaweiCloud Cloud Secret Management Service (CSMS)		Alpha	v1	1.8

Microsoft Azure

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
Azure Key Vault		Stable	v1	1.0

Tencent Cloud

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
Tencent Cloud Secrets Manager (SSM)		Alpha	v1	1.9

9.1 - AWS Secrets Manager

有关 AWS Secrets Manager 密钥存储组件的详细信息

组件格式

要设置 AWS Secrets Manager 密钥存储，请创建类型为 secretstores.aws.secretmanager 的组件。有关如何创建和应用密钥存储配置的信息，请参阅此指南。有关使用 Dapr 组件检索和使用密钥的信息，请参阅引用密钥指南。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: awssecretmanager
spec:
  type: secretstores.aws.secretmanager
  version: v1
  metadata:
  - name: region
    value: "[aws_region]"
  - name: accessKey
    value: "[aws_access_key]"
  - name: secretKey
    value: "[aws_secret_key]"
  - name: sessionToken
    value: "[aws_session_token]"
  - name: multipleKeyValuesPerSecret
    value: "false"

警告

上面的示例使用明文字符串作为密钥。建议使用本地密钥存储（如 Kubernetes secret store 或本地文件）来引导安全的密钥存储。

规范元数据字段

字段	必填	详情	示例
region	Y	AWS Secrets Manager 实例部署到的特定 AWS 区域	`"us-east-1"`
accessKey	Y	用于访问此资源的 AWS Access Key	`"key"`
secretKey	Y	用于访问此资源的 AWS Secret Access Key	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`
multipleKeyValuesPerSecret	N	当设置为 `"true"` 时，允许在单个密钥中存储多个键值对。默认为 `"false"`	`"true"`

重要

当在 EKS（AWS Kubernetes）上使用应用程序运行 Dapr 边车（daprd）时，如果您使用的节点/Pod 已附加到定义了对 AWS 资源访问权限的 IAM 策略，则不得在所使用的组件规范定义中提供 AWS access-key、secret-key 和令牌。

可选的每请求元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。
`metadata.version_stage`	给定密钥的版本阶段。

配置每个密钥的多个键值对

multipleKeyValuesPerSecret 标志确定密钥存储是每个密钥呈现单个值还是多个键值对。

每个密钥的单个值

如果 multipleKeyValuesPerSecret 为 false（默认），AWS Secrets Manager 将按原样返回密钥值。给定名为 database-credentials 的密钥，其包含以下 JSON 内容：

{
  "username": "admin",
  "password": "secret123",
  "host": "db.example.com"
}

请求此密钥会将整个 JSON 作为单个值返回：

$ curl http://localhost:3500/v1.0/secrets/awssecretmanager/database-credentials
{
  "database-credentials": "{\"username\":\"admin\",\"password\":\"secret123\",\"host\":\"db.example.com\"}"
}

每个密钥的多个键值对

如果 multipleKeyValuesPerSecret 为 true，密钥存储会解析存储在 AWS Secrets Manager 中的 JSON 内容，并将其作为多个键值对返回。

从上方请求相同的 database-credentials 密钥时，响应会将 JSON 对象分解为各自的条目，允许将其解析为多个键值对。

$ curl http://localhost:3500/v1.0/secrets/awssecretmanager/database-credentials
{
  "username": "admin",
  "password": "secret123", 
  "host": "db.example.com"
}

创建 AWS Secrets Manager 实例

使用 AWS 文档设置 AWS Secrets Manager：https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html。

9.2 - AWS SSM Parameter Store

AWS SSM Parameter Store 密钥存储组件的详细信息

组件格式

要设置 AWS SSM Parameter Store 密钥存储，需创建类型为 secretstores.aws.parameterstore 的组件。有关如何创建和应用密钥存储配置的信息，请参阅此指南。有关使用 Dapr 组件检索和使用密钥的信息，请参阅此关于引用密钥的指南。

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: awsparameterstore
spec:
  type: secretstores.aws.parameterstore
  version: v1
  metadata:
  - name: region
    value: "[aws_region]"
  - name: accessKey
    value: "[aws_access_key]"
  - name: secretKey
    value: "[aws_secret_key]"
  - name: sessionToken
    value: "[aws_session_token]"
  - name: prefix
    value: "[secret_name]"

Warning

上述示例将密钥作为纯字符串使用。建议使用本地密钥存储（例如 Kubernetes secret store 或本地文件）来引导安全的密钥存储。

规范元数据字段

字段	必填	详情	示例
region	Y	部署 AWS SSM Parameter Store 实例的特定 AWS 区域	`"us-east-1"`
accessKey	Y	用于访问此资源的 AWS Access Key	`"key"`
secretKey	Y	用于访问此资源的 AWS Secret Access Key	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`
prefix	N	允许您指定多个 SSM Parameter Store 密钥存储组件。	`"prefix"`

Important

当在 EKS（AWS Kubernetes）上使用您的应用程序运行 Dapr 边车（daprd）时，如果您使用的节点/pod 已经附加到定义了对 AWS 资源访问权限的 IAM 策略，则不得在正在使用的组件规范定义中提供 AWS access-key、secret-key 和 tokens。

创建 AWS SSM Parameter Store 实例

使用 AWS 文档设置 AWS SSM Parameter Store：https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html。

9.3 - Azure Key Vault secret store

关于 Azure Key Vault secret store 组件的详细信息

组件格式

要设置 Azure Key Vault secret store，需创建一个类型为 secretstores.azure.keyvault 的组件。

请参阅 secret store 组件指南了解如何创建和应用 secret store 配置。
请参阅引用 secret 指南以使用 Dapr 组件检索和使用 secret。
请参阅下方的配置组件部分。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName # Required
    value: [your_keyvault_name]
  - name: azureEnvironment # Optional, defaults to AZUREPUBLICCLOUD
    value: "AZUREPUBLICCLOUD"
  # See authentication section below for all options
  - name: azureTenantId
    value: "[your_service_principal_tenant_id]"
  - name: azureClientId
    value: "[your_service_principal_app_id]"
  - name: azureCertificateFile
    value : "[pfx_certificate_file_fully_qualified_local_path]"

使用 Microsoft Entra ID 进行身份验证

Azure Key Vault secret store 组件仅支持使用 Microsoft Entra ID 进行身份验证。在启用此组件之前：

阅读向 Azure 进行身份验证文档。
创建一个 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为你的应用程序平台创建一个托管标识。

规范元数据字段

Field	Required	Details	Example
`vaultName`	Y	Azure Key Vault 的名称	`"mykeyvault"`
`azureEnvironment`	N	如果使用不同的 Azure 云，则为 Azure 环境的可选名称	`"AZUREPUBLICCLOUD"`（默认值）、`"AZURECHINACLOUD"`、`"AZUREUSGOVERNMENTCLOUD"`、`"AZUREGERMANCLOUD"`
Auth metadata		有关更多信息，请参阅向 Azure 进行身份验证

此外，你必须提供向 Azure 进行身份验证文档中说明的身份验证字段。

可选的按请求元数据属性

从此 secret store 检索 secret 时，可以提供以下可选查询参数：

Query Parameter	Description
`metadata.version_id`	给定 secret 密钥的版本。
`metadata.maxresults`	（仅用于批量请求）要返回的 secret 数量，超过后将截断请求。

示例

先决条件

Azure 订阅
Azure CLI
jq
你正在使用 bash 或 zsh shell
你已按照向 Azure 进行身份验证中的说明创建了 Microsoft Entra ID 应用程序（服务主体）。你需要以下值：
Value Description
SERVICE_PRINCIPAL_ID 你为给定应用程序创建的服务主体的 ID

创建 Azure Key Vault 并为服务主体授权

设置一个包含你创建的服务主体的变量：

SERVICE_PRINCIPAL_ID="[your_service_principal_object_id]"

设置一个用于创建所有资源的位置的变量：

LOCATION="[your_location]"

（你可以通过以下命令获取完整的选项列表：az account list-locations --output tsv）

创建一个资源组，并给它取一个你喜欢的名称：

RG_NAME="[resource_group_name]"
RG_ID=$(az group create \
  --name "${RG_NAME}" \
  --location "${LOCATION}" \
  | jq -r .id)

创建一个使用 Azure RBAC 进行授权的 Azure Key Vault：

KEYVAULT_NAME="[key_vault_name]"
az keyvault create \
  --name "${KEYVAULT_NAME}" \
  --enable-rbac-authorization true \
  --resource-group "${RG_NAME}" \
  --location "${LOCATION}"

使用 RBAC 为 Microsoft Entra ID 应用程序分配角色，以便它可以访问 Key Vault。在本例中，分配 “Key Vault Secrets User” 角色，该角色具有对 Azure Key Vault 的 “Get secrets” 权限。

az role assignment create \
  --assignee "${SERVICE_PRINCIPAL_ID}" \
  --role "Key Vault Secrets User" \
  --scope "${RG_ID}/providers/Microsoft.KeyVault/vaults/${KEYVAULT_NAME}"

根据你的应用程序，可以使用其他限制较少的角色，例如 “Key Vault Secrets Officer” 和 “Key Vault Administrator”。请参阅 Microsoft Docs 以了解有关 Key Vault 的 Azure 内置角色的更多信息。

配置组件

使用客户端密钥

要使用客户端密钥，请在 components 目录中创建一个名为 azurekeyvault.yaml 的文件。使用以下模板，填写你创建的 Microsoft Entra ID 应用程序的详细信息：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    value : "[your_client_secret]"

使用证书

如果你想使用本地磁盘上保存的证书，请使用以下模板。填写你创建的 Microsoft Entra ID 应用程序的详细信息：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureCertificateFile
    value : "[pfx_certificate_file_fully_qualified_local_path]"

在 Kubernetes 中，你需要将客户端密钥或证书存储到 Kubernetes Secret Store 中，然后在 YAML 文件中引用它们。在开始之前，你需要你创建的 Microsoft Entra ID 应用程序的详细信息。

使用客户端密钥

使用以下命令创建一个 Kubernetes secret：
```
kubectl create secret generic [your_k8s_secret_name] --from-literal=[your_k8s_secret_key]=[your_client_secret]
```
- [your_client_secret] 是上面生成的应用程序客户端密钥
- [your_k8s_secret_name] 是 Kubernetes secret store 中的 secret 名称
- [your_k8s_secret_key] 是 Kubernetes secret store 中的 secret 密钥

创建一个 azurekeyvault.yaml 组件文件。

组件 yaml 使用 auth 属性引用 Kubernetes secretstore，secretKeyRef 引用存储在 Kubernetes secret store 中的客户端密钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    secretKeyRef:
      name: "[your_k8s_secret_name]"
      key: "[your_k8s_secret_key]"
auth:
  secretStore: kubernetes

应用 azurekeyvault.yaml 组件：
```
kubectl apply -f azurekeyvault.yaml
```

使用证书

使用以下命令创建一个 Kubernetes secret：
```
kubectl create secret generic [your_k8s_secret_name] --from-file=[your_k8s_secret_key]=[pfx_certificate_file_fully_qualified_local_path]
```
- [pfx_certificate_file_fully_qualified_local_path] 是你之前获得的 PFX 文件的路径
- [your_k8s_secret_name] 是 Kubernetes secret store 中的 secret 名称
- [your_k8s_secret_key] 是 Kubernetes secret store 中的 secret 密钥

创建一个 azurekeyvault.yaml 组件文件。

组件 yaml 使用 auth 属性引用 Kubernetes secretstore，secretKeyRef 引用存储在 Kubernetes secret store 中的证书。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureCertificate
    secretKeyRef:
      name: "[your_k8s_secret_name]"
      key: "[your_k8s_secret_key]"
auth:
  secretStore: kubernetes

应用 azurekeyvault.yaml 组件：
```
kubectl apply -f azurekeyvault.yaml
```

使用 Azure 托管标识

确保你的 AKS 集群已启用托管标识，并按照使用托管标识的指南进行操作。

创建一个 azurekeyvault.yaml 组件文件。

组件 yaml 引用特定的 KeyVault 名称。你将在后续步骤中使用的托管标识必须获得对此特定 KeyVault 实例的读取访问权限。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"

应用 azurekeyvault.yaml 组件：
```
kubectl apply -f azurekeyvault.yaml
```
通过 Microsoft Entra ID workload identity 在 Pod 级别创建并分配托管标识
创建工作负载标识后，为其授予 read 权限：
- 在你所需的 KeyVault 实例上
- 在你的应用程序部署中。通过以下两种方式注入 Pod 标识：
  - 通过标签注释
  - 通过指定与所需工作负载标识关联的 Kubernetes 服务帐户
```
apiVersion: v1
kind: Pod
metadata:
  name: mydaprdemoapp
  labels:
    aadpodidbinding: $POD_IDENTITY_NAME
```

直接使用 Azure 托管标识与通过 Microsoft Entra ID workload identity 使用托管标识的对比

当直接使用托管标识时，你可以将多个标识与一个应用关联，需要使用 azureClientId 来指定应使用哪个标识。

但是，当通过 Microsoft Entra ID workload identity 使用托管标识时，azureClientId 不是必需的，并且不起作用。要使用的 Azure 标识是从与 Azure 标识关联的服务帐户推断出来的，该关联是通过 Azure 联合标识建立的。

参考

9.4 - GCP Secret Manager

GCP Secret Manager 密钥存储组件的详细信息

组件格式

要设置 GCP Secret Manager 密钥存储，需创建一个类型为 secretstores.gcp.secretmanager 的组件。请参阅此指南了解如何创建和应用密钥存储配置。请参阅关于引用密钥的指南，以在 Dapr 组件中检索和使用密钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: gcpsecretmanager
spec:
  type: secretstores.gcp.secretmanager
  version: v1
  metadata:
  - name: type
    value: <replace-with-account-type>
  - name: project_id
    value: <replace-with-project-id>
  - name: private_key_id
    value: <replace-with-private-key-id>
  - name: client_email
    value: <replace-with-email>
  - name: client_id
    value: <replace-with-client-id>
  - name: auth_uri
    value: <replace-with-auth-uri>
  - name: token_uri
    value: <replace-with-token-uri>
  - name: auth_provider_x509_cert_url
    value: <replace-with-auth-provider-cert-url>
  - name: client_x509_cert_url
    value: <replace-with-client-cert-url>
  - name: private_key
    value: <replace-with-private-key>

Warning

以上示例使用明文字符串作为密钥。建议使用本地密钥存储（如 Kubernetes secret store）或本地文件来引导安全密钥存储。

规格元数据字段

字段	必填	详情	示例
`project_id`	Y	与此组件关联的项目 ID。	`"project_id"`
`type`	N	账户类型。	`"service_account"`
`private_key_id`	N	如果使用显式凭据，此字段应包含服务账户 JSON 文档中的 `private_key_id` 字段	`"privateKeyId"`
`private_key`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `private_key` 字段。替换为 x509 证书	`12345-12345`
`client_email`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `client_email` 字段	`"client@email.com"`
`client_id`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `client_id` 字段	`0123456789-0123456789`
`auth_uri`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `auth_uri` 字段	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `token_uri` 字段	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `auth_provider_x509_cert_url` 字段	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `client_x509_cert_url` 字段	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`

GCP 凭据

由于 GCP Secret Manager 组件使用 GCP Go 客户端库，默认情况下它使用 Application Default Credentials 进行身份验证。这在 Authenticate to GCP Cloud services using client libraries 指南中有进一步说明。此外，请参阅如何设置 Application Default Credentials。

可选的每请求元数据属性

可以向 GCP Secret Manager 组件提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。

设置 GCP Secret Manager 实例

使用 GCP 文档设置 GCP Secret Manager：https://cloud.google.com/secret-manager/docs/quickstart。

9.5 - HashiCorp Vault

HashiCorp Vault 密钥存储组件的详细信息

创建 Vault 组件

要设置 HashiCorp Vault 密钥存储，需要创建一个类型为 secretstores.hashicorp.vault 的组件。请参阅此指南了解如何创建和应用密钥存储配置。请参阅引用密钥指南，了解如何使用 Dapr 组件检索和使用密钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: vault
spec:
  type: secretstores.hashicorp.vault
  version: v1
  metadata:
  - name: vaultAddr
    value: [vault_address] # 可选。默认值："https://127.0.0.1:8200"
  - name: caCert # 可选。与此项或 caPath 或 caPem 二选一
    value: "[ca_cert]"
  - name: caPath # 可选。与此项或 CaCert 或 caPem 二选一
    value: "[path_to_ca_cert_file]"
  - name: caPem # 可选。与此项或 CaCert 或 CaPath 二选一
    value : "[encoded_ca_cert_pem]"
  - name: skipVerify # 可选。默认值：false
    value : "[skip_tls_verification]"
  - name: tlsServerName # 可选。
    value : "[tls_config_server_name]"
  - name: vaultTokenMountPath # 如果未提供 vaultToken 则为必填。令牌文件的路径。
    value : "[path_to_file_containing_token]"
  - name: vaultToken # 如果未提供 vaultTokenMountPath 则为必填。令牌值。
    value : "[path_to_file_containing_token]"
  - name: vaultKVPrefix # 可选。默认值："dapr"
    value : "[vault_prefix]"
  - name: vaultKVUsePrefix # 可选。默认值："true"
    value: "[true/false]"
  - name: enginePath # 可选。默认值："secret"
    value: "secret"
  - name: vaultValueType # 可选。默认值："map"
    value: "map"

Warning

上述示例将密钥用作纯文本字符串。建议使用本地密钥存储，例如 Kubernetes secret store 或本地文件来引导安全密钥存储。

规范元数据字段

字段	必填	详情	示例
vaultAddr	N	Vault 服务器的地址。默认值为 `"https://127.0.0.1:8200"`	`"https://127.0.0.1:8200"`
caPem	N	要使用的 CA 证书的内联内容，采用 PEM 格式。如果已定义，则优先于 `caPath` 和 `caCert`。	见下方
caPath	N	包含要使用的 CA 证书文件的文件夹路径，采用 PEM 格式。如果文件夹包含多个文件，将仅使用找到的第一个文件。如果已定义，则优先于 `caCert`。	`"path/to/cacert/holding/folder"`
caCert	N	要使用的 CA 证书的路径，采用 PEM 格式。	`""path/to/cacert.pem"`
skipVerify	N	跳过 TLS 验证。默认值为 `"false"`	`"true"`, `"false"`
tlsServerName	N	在 TLS 握手期间请求的服务器名称，以支持虚拟托管。此值还用于验证 Vault 服务器提供的 TLS 证书。	`"tls-server"`
vaultTokenMountPath	Y	包含令牌的文件的路径	`"path/to/file"`
vaultToken	Y	用于在 Vault 中进行身份验证的令牌。	`"tokenValue"`
vaultKVPrefix	N	vault 中的前缀。默认值为 `"dapr"`	`"dapr"`, `"myprefix"`
vaultKVUsePrefix	N	如果为 false，vaultKVPrefix 将被强制为空。如果未给出该值或设置为 true，则在访问 vault 时使用 vaultKVPrefix。若要能够使用存储的 BulkGetSecret 方法，需要将其设置为 false。	`"true"`, `"false"`
enginePath	N	vault 中的引擎路径。默认值为 `"secret"`	`"kv"`, `"any"`
vaultValueType	N	Vault 值类型。`map` 表示将值解析为 `map[string]string`，`text` 表示将值作为字符串使用。‘map’ 设置 `multipleKeyValuesPerSecret` 行为。`text` 使 Vault 充当具有名称/值语义的密钥存储。默认值为 `"map"`	`"map"`, `"text"`

可选的请求元数据属性

可以向 Hashicorp Vault 密钥存储组件提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。

设置 Hashicorp Vault 实例

使用 Vault 文档设置 Hashicorp Vault：https://www.vaultproject.io/docs/install/index.html。

对于 Kubernetes，您可以使用 Helm Chart：https://github.com/hashicorp/vault-helm。

每个密钥的多个键值

HashiCorp Vault 支持在一个密钥中存储多个键值。虽然这种行为最终取决于由 enginePath 配置的底层密钥引擎，但它可能会改变您从 Vault 存储和检索密钥的方式。例如，密钥中的多个键值是在 secret 引擎中公开的行为，这是由 enginePath 字段配置的默认引擎。

检索密钥时，将返回一个 JSON 有效负载，其中键名作为字段，各自的值作为值。

假设您按如下方式向 Vault 设置添加一个密钥：

vault kv put secret/dapr/mysecret firstKey=aValue secondKey=anotherValue thirdKey=yetAnotherDistinctValue

在上述示例中，密钥名为 mysecret，它下面有 3 个键值。请注意，密钥是在 dapr 前缀下创建的，因为这是 vaultKVPrefix 标志的默认值。从 Dapr 检索它将产生以下输出：

$ curl http://localhost:3501/v1.0/secrets/my-hashicorp-vault/mysecret

{
  "firstKey": "aValue",
  "secondKey": "anotherValue",
  "thirdKey": "yetAnotherDistinctValue"
}

请注意，密钥的名称（mysecret）在结果中未重复。

TLS 服务器验证

字段 skipVerify、tlsServerName、caCert、caPath 和 caPem 控制 Dapr 在使用 TLS/HTTPS 连接时是否以及如何验证 vault 服务器的证书。

内联 CA PEM caPem

caPem 字段值应该是您要使用的 PEM CA 证书的内容。鉴于 PEM 证书由多行组成，定义该值起初可能看起来具有挑战性。YAML 允许使用几种方式来定义多行值。

以下是定义 caPem 字段的一种方法。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: vault
spec:
  type: secretstores.hashicorp.vault
  version: v1
  metadata:
  - name: vaultAddr
    value: https://127.0.0.1:8200
  - name: caPem
    value: |-
          -----BEGIN CERTIFICATE-----
          << 您的 PEM 文件内容的其余部分在此处，适当缩进。 >>
          -----END CERTIFICATE-----

9.6 - HuaweiCloud Cloud Secret Management Service (CSMS)

关于 HuaweiCloud Cloud Secret Management Service (CSMS) 密钥存储组件的详细信息

组件格式

要设置 HuaweiCloud Cloud Secret Management Service (CSMS) 密钥存储，请创建一个类型为 secretstores.huaweicloud.csms 的组件。有关如何创建和应用密钥存储配置，请参阅此指南。有关如何使用 Dapr 组件检索和使用密钥，请参阅此引用密钥指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: huaweicloudcsms
spec:
  type: secretstores.huaweicloud.csms
  version: v1
  metadata:
  - name: region
    value: "[huaweicloud_region]"
  - name: accessKey
    value: "[huaweicloud_access_key]"
  - name: secretAccessKey
    value: "[huaweicloud_secret_access_key]"

警告

上述示例将密钥作为纯字符串使用。建议使用本地密钥存储（例如 Kubernetes secret store 或本地文件）来引导安全的密钥存储。

规范元数据字段

字段	必填	详情	示例
region	Y	HuaweiCloud CSMS 实例部署到的特定区域	`"cn-north-4"`
accessKey	Y	用于访问此资源的 HuaweiCloud Access Key	`"accessKey"`
secretAccessKey	Y	用于访问此资源的 HuaweiCloud Secret Access Key	`"secretAccessKey"`

可选的请求级别元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。

设置 HuaweiCloud Cloud Secret Management Service (CSMS) 实例

使用 HuaweiCloud 文档设置 HuaweiCloud Cloud Secret Management Service (CSMS)：https://support.huaweicloud.com/intl/en-us/usermanual-dew/dew_01_9993.html。

9.7 - Kubernetes 密钥

Kubernetes 密钥存储组件的详细信息

默认 Kubernetes 密钥存储组件

当 Dapr 部署到 Kubernetes 集群时，会自动创建一个名为 kubernetes 的密钥存储。这个预置的密钥存储允许您使用原生的 Kubernetes 密钥存储，无需为密钥存储编写、部署或维护组件配置文件，对于希望简单访问 Kubernetes 集群中原生存储的密钥的开发者非常有用。

仍然可以配置 Kubernetes 密钥存储的自定义组件定义文件（详情见下文）。使用自定义定义可以将代码中引用的密钥存储与托管平台解耦，因为存储名称不是固定的，可以自定义，使代码更加通用和可移植。此外，通过显式定义 Kubernetes 密钥存储组件，您可以从本地 Dapr 自托管安装连接到 Kubernetes 密钥存储。这需要有效的 kubeconfig 文件。

限制密钥存储访问范围

当使用密钥范围限制应用程序对密钥的访问时，需要在范围定义中包含默认密钥存储以对其进行限制。

创建自定义 Kubernetes 密钥存储组件

要设置 Kubernetes 密钥存储，需创建类型为 secretstores.kubernetes 的组件。有关如何创建和应用密钥存储配置，请参阅此指南。有关使用 Dapr 组件检索和使用密钥，请参阅此指南引用密钥。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mycustomsecretstore
spec:
  type: secretstores.kubernetes
  version: v1
  metadata:[]

规范元数据字段

Field	Required	Details	Example
`defaultNamespace`	N	默认用于检索密钥的命名空间。如果未设置，则必须在每个请求元数据中指定 `namespace`，或通过环境变量 `NAMESPACE` 指定	`"default-ns"`
`kubeconfigPath`	N	kubeconfig 文件的路径。如果未指定，存储使用默认的集群内配置值	`"/path/to/kubeconfig"`

可选的每次请求元数据属性

可以向 Kubernetes 密钥存储组件提供以下可选查询参数：

Query Parameter	Description
`metadata.namespace`	密钥的命名空间。如果未指定，则使用 pod 的命名空间。

9.8 - Local file (for Development)

Detailed information on the local file secret store component

此 Dapr 密钥存储组件从给定文件读取纯文本 JSON，不使用身份验证。

Warning

不推荐在生产环境中使用此密钥管理方式。

Component format

要设置基于本地文件的密钥存储，请创建类型为 secretstores.local.file 的组件。在 ./components 目录中创建具有以下内容的文件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: local-secret-store
spec:
  type: secretstores.local.file
  version: v1
  metadata:
  - name: secretsFile
    value: [path to the JSON file]
  - name: nestedSeparator
    value: ":"
  - name: multiValued
    value: "false"

Spec metadata fields

Field	Required	Details	Example
secretsFile	Y	存储密钥的文件路径	`"path/to/file.json"`
nestedSeparator	N	在将 JSON 层级结构展平为 map 时由存储使用。默认为 `":"`	`":"`
multiValued	N	`"true"` 设置 `multipleKeyValuesPerSecret` 行为。允许在展平 JSON 层级结构之前具有一层多值键/值对。默认为 `"false"`	`"true"`

Setup JSON file to hold the secrets

给定以下从 secretsFile 加载的 JSON：

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "sql": "your sql connection string",
        "mysql": "your mysql connection string"
    }
}

标志 multiValued 决定密钥存储是呈现名称/值行为还是每个密钥多个键值的行为。

Name/Value semantics

如果 multiValued 为 false，存储会加载 JSON 文件并创建具有以下键值对的 map：

flattened key	value
“redisPassword”	`"your redis password"`
“connectionStrings:sql”	`"your sql connection string"`
“connectionStrings:mysql”	`"your mysql connection string"`

如果将 multiValued 设置为 true，在键 connectionStrings 上调用 GET 请求将导致 500 HTTP 响应和错误消息。例如：

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "errorCode": "ERR_SECRET_GET",
  "message": "failed getting secret with key connectionStrings from secret store local-secret-store: secret connectionStrings not found"
}

此错误是预期的，因为根据上表，不存在 connectionStrings 键。

但是，请求展平键 connectionStrings:sql 将成功响应，结果如下：

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings:sql

{
  "connectionStrings:sql": "your sql connection string"
}

Multiple key-values behavior

如果 multiValued 为 true，密钥存储将启用每个密钥多个键值的行为：

顶层之后的嵌套结构将被展平。
它将相同的 JSON 文件解析为以下表格：

key	value
“redisPassword”	`"your redis password"`
“connectionStrings”	`{"mysql":"your mysql connection string","sql":"your sql connection string"}`

请注意，在上表中：

connectionStrings 现在是一个 JSON 对象，包含两个键：mysql 和 sql。
来自名称/值语义映射表的 connectionStrings:sql 和 connectionStrings:mysql 展平键已缺失。

现在在键 connectionStrings 上调用 GET 请求将成功返回 HTTP 响应，类似于以下内容：

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "sql": "your sql connection string",
  "mysql": "your mysql connection string"
}

同时，现在请求展平键 connectionStrings:sql 将返回 500 HTTP 错误响应，内容如下：

{
  "errorCode": "ERR_SECRET_GET",
  "message": "failed getting secret with key connectionStrings:sql from secret store local-secret-store: secret connectionStrings:sql not found"
}

Handling deeper nesting levels

请注意，如 spec metadata fields table 中所述，multiValued 仅处理单个嵌套层级。

假设您有一个启用了 multiValued 的本地文件密钥存储，指向具有以下 JSON 内容的 secretsFile：

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "mysql": {
          "username": "your mysql username",
          "password": "your mysql password"
        }
    }
}

connectionStrings 下键 mysql 的内容的嵌套层级大于 1，将被展平。

它在内存中的样子如下：

key	value
“redisPassword”	`"your redis password"`
“connectionStrings”	`{ "mysql:username": "your mysql username", "mysql:password": "your mysql password" }`

同样，请求键 connectionStrings 将成功返回 HTTP 响应，但其内容如上表所示，将是展平的：

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "mysql:username": "your mysql username",
  "mysql:password": "your mysql password"
}

这对于模拟 Vault 或 Kubernetes 等每个密钥键返回多个键/值对的密钥存储非常有用。

9.9 - OpenBao

OpenBao 密钥存储组件的详细信息。

用法

目前没有专门的 OpenBao 密钥存储。不过，你可以使用 secretstores.hashicorp.vault 组件，该组件已经过测试并被确认可以正常工作。

有关如何设置和配置密钥存储的说明，请参阅 HashiCorp Vault 指南。相同的 metadata 字段与 OpenBao 兼容。

组件示例

---
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: openbao
spec:
  # 使用来自 vault 的
  # 密钥存储提供者
  type: secretstores.hashicorp.vault
  version: v1
  metadata:
    - name: vaultAddr
      value: http://openbao.openbao.svc.cluster.local:8200
    - name: skipVerify # 可选。默认值：false
      value: true
    - name: vaultToken
      secretKeyRef:
        name: roottoken
        key: token
    - name: enginePath # 可选。默认值："secret"
      value: "secrets"
    - name: vaultValueType # 可选。默认值："map"
      value: "map"

9.10 - Tencent Cloud Secrets Manager (SSM)

有关 Tencent Cloud Secrets Manager (SSM) 密钥存储组件的详细信息

组件格式

要设置 Tencent Cloud Secrets Manager (SSM) 密钥存储，请创建类型为 secretstores.tencentcloud.ssm 的组件。有关如何创建和应用密钥存储配置，请参阅此指南。有关使用 Dapr 组件检索和使用密钥，请参阅此引用密钥指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: tencentcloudssm
spec:
  type: secretstores.tencentcloud.ssm
  version: v1
  metadata:
  - name: region
    value: "[tencentcloud_region]"
  - name: secretId
    value: "[tencentcloud_secret_id]"
  - name: secretKey
    value: "[tencentcloud_secret_key]"
  - name: token
    value: "[tencentcloud_secret_token]"

Warning

上述示例将密钥作为纯字符串使用。建议使用本地密钥存储，例如 Kubernetes secret store 或本地文件来引导安全密钥存储。

规范元数据字段

字段	必填	详情	示例
region	Y	部署 Tencent SSM 实例的特定区域	`"ap-beijing-3"`
secretId	Y	腾讯云账户的 SecretId	`"xyz"`
secretKey	Y	腾讯云账户的 SecretKey	`"xyz"`
token	N	腾讯云账户的 Token。仅在使用临时凭证时需要	`""`

可选的每次请求元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。

设置 Tencent Cloud Secrets Manager (SSM)

使用 Tencent Cloud 文档设置 Tencent Cloud Secrets Manager (SSM)：https://www.tencentcloud.com/products/ssm

9.11 - 阿里云 OOS Parameter Store

关于阿里云 OOS Parameter Store secret store 组件的详细信息

组件格式

若要设置阿里云 OOS Parameter Store secret store，需创建一个类型为 secretstores.alicloud.parameterstore 的组件。有关如何创建和应用 secretstore 配置，请参阅此指南。有关检索和使用 secret 与 Dapr 组件的指南，请参阅此引用 secret 指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: alibabacloudparameterstore
spec:
  type: secretstores.alicloud.parameterstore
  version: v1
  metadata:
  - name: regionId
    value: "[alicloud_region_id]"
  - name: accessKeyId 
    value: "[alicloud_access_key_id]"
  - name: accessKeySecret
    value: "[alicloud_access_key_secret]"
  - name: securityToken
    value: "[alicloud_security_token]"

Warning

上述示例使用明文字符串作为 secret。建议使用本地 secret store（如 Kubernetes secret store 或本地文件）来引导安全的密钥存储。

规范元数据字段

Field	Required	Details	Example
regionId	Y	AlibabaCloud OOS Parameter Store 实例部署的特定区域	`"cn-hangzhou"`
accessKeyId	Y	用于访问此资源的阿里云 Access Key ID	`"accessKeyId"`
accessKeySecret	Y	用于访问此资源的阿里云 Access Key Secret	`"accessKeySecret"`
securityToken	N	要使用的阿里云 Security Token	`"securityToken"`

可选的每请求元数据属性

从此 secret store 检索 secret 时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定 secret 密钥的版本
`metadata.path`	（仅用于批量请求）元数据中的路径。如果未设置，默认为根路径（所有 secret）。

创建阿里云 OOS Parameter Store 实例

使用阿里云文档设置阿里云 OOS Parameter Store：https://www.alibabacloud.com/help/en/doc-detail/186828.html。

9.12 - 本地环境变量（用于开发）

本地环境变量 secret store 组件的详细信息

此 Dapr secret store 组件使用本地定义的环境变量，不使用身份验证。

警告

不建议在生产环境中使用这种 secret 管理方法。

组件格式

要设置本地环境变量 secret store，请创建一个类型为 secretstores.local.env 的组件。在 ./components 目录中创建包含以下内容的文件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: envvar-secret-store
spec:
  type: secretstores.local.env
  version: v1
  metadata:
    # - name: prefix
    #   value: "MYAPP_"

规范元数据字段

字段	必填	详情	示例
`prefix`	否	如果设置，则将操作限制为具有给定前缀的环境变量。前缀将从返回的 secret 名称中移除。在 Windows 上匹配不区分大小写，在所有其他操作系统上匹配区分大小写。	`"MYAPP_"`

注意事项

出于安全原因，此组件不能用于访问以下环境变量：

APP_API_TOKEN
任何名称以 DAPR_ 前缀开头的变量

10 - 状态存储组件规格

与 Dapr 对接的受支持状态存储

下表列出了 Dapr 状态管理构建块在不同级别上支持的状态存储。了解如何为 Dapr 状态管理配置不同的状态存储。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

注意

如果状态存储同时支持事务操作和 ETag，则可用于 Actor。

Generic

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
Aerospike	✅		✅				Alpha	v1	1.0
Apache Cassandra	✅			✅			Stable	v1	1.9
CockroachDB	✅	✅	✅	✅	✅		Stable	v1	1.10
Couchbase	✅		✅				Alpha	v1	1.0
etcd	✅	✅	✅	✅	✅	✅	Beta	v2	1.12
Hashicorp Consul	✅						Alpha	v1	1.0
Hazelcast	✅						Alpha	v1	1.0
In-memory	✅	✅	✅	✅	✅	✅	Stable	v1	1.9
JetStream KV	✅						Alpha	v1	1.7
Memcached	✅			✅			Stable	v1	1.9
MongoDB	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
MySQL & MariaDB	✅	✅	✅	✅	✅	✅	Stable	v1	1.10
Oracle Database	✅	✅	✅	✅	✅	✅	Beta	v1	1.7
PostgreSQL v1	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
PostgreSQL v2	✅	✅	✅	✅	✅	✅	Stable	v2	1.13
RavenDB	✅	✅	✅	✅	✅		Stable	v1	1.16
Redis	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
RethinkDB	✅						Beta	v1	1.9
SQLite	✅	✅	✅	✅	✅	✅	Stable	v1	1.11
Zookeeper	✅		✅				Alpha	v1	1.0

Alibaba Cloud

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
AliCloud TableStore	✅		✅				Alpha	v1	1.3

Amazon Web Services (AWS)

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
AWS DynamoDB	✅	✅	✅	✅	✅		Stable	v1	1.10

Cloudflare

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
Cloudflare Workers KV	✅			✅			Beta	v1	1.10

Google Cloud Platform (GCP)

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
GCP Firestore	✅						Stable	v1	1.11

Microsoft Azure

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
Azure Blob Storage	✅		✅				Stable	v2	1.13
Azure Cosmos DB	✅	✅	✅	✅	✅		Stable	v1	1.0
Azure Table Storage	✅		✅				Stable	v1	1.9
Microsoft SQL Server V1	✅	✅	✅	✅	✅	✅	Stable	v1	1.5
Microsoft SQL Server V2	✅	✅	✅	✅	✅	✅	Stable	v2	1.17

Oracle Cloud

Component	CRUD	Transactional	ETag	TTL	Actors	Workflow	Status	Component version	Since runtime version
Autonomous Database (ATP and ADW)	✅	✅	✅	✅	✅	✅	Alpha	v1	1.7
Coherence	✅			✅			Alpha	v1	1.16
Object Storage	✅		✅	✅			Alpha	v1	1.6

10.1 - Aerospike

Aerospike 状态存储组件的详细信息

组件格式

要设置 Aerospike 状态存储，请创建一个类型为 state.Aerospike 的组件。有关如何创建和应用状态存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.Aerospike
  version: v1
  metadata:
  - name: hosts
    value: <REPLACE-WITH-HOSTS> # 必填。以逗号分隔的主机字符串。示例："aerospike:3000,aerospike2:3000"
  - name: namespace
    value: <REPLACE-WITH-NAMESPACE> # 必填。Aerospike 命名空间。
  - name: set
    value: <REPLACE-WITH-SET> # 可选

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规格元数据字段

字段	必填	详情	示例
hosts	Y	数据库服务器的主机名/端口	`"localhost:3000"`, `"aerospike:3000,aerospike2:3000"`
namespace	Y	Aerospike 命名空间	`"namespace"`
set	N	数据库中的 setName	`"myset"`

设置 Aerospike

您可以使用 Docker 在本地运行 Aerospike：

docker run -d --name aerospike -p 3000:3000 -p 3001:3001 -p 3002:3002 -p 3003:3003 aerospike

然后可以使用 localhost:3000 与服务器交互。

在 Kubernetes 上安装 Aerospike 最简单的方法是使用 Helm chart：

helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
helm install --name my-aerospike --namespace aerospike stable/aerospike

这会将 Aerospike 安装到 aerospike 命名空间中。要与 Aerospike 交互，使用以下命令查找服务：kubectl get svc aerospike -n aerospike。

例如，如果使用上述示例安装，Aerospike 主机地址将是：

aerospike-my-aerospike.aerospike.svc.cluster.local:3000

10.2 - Alibaba Cloud TableStore

关于用于 Dapr 的 Alibaba Cloud TableStore 状态存储组件的详细信息

组件格式

要设置 Alibaba Cloud TableStore 状态存储，请创建类型为 state.alicloud.tablestore 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.alicloud.tablestore
  version: v1
  metadata:
  - name: endpoint
    value: <REPLACE-WITH-ENDPOINT>
  - name: instanceName
    value: <REPLACE-WITH-INSTANCE-NAME>
  - name: tableName
    value: <REPLACE-WITH-TABLE-NAME>
  - name: accessKeyID
    value: <REPLACE-WITH-ACCESS-KEY-ID>
  - name: accessKey
    value: <REPLACE-WITH-ACCESS-KEY>

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用 secret store 来管理密钥。

规格元数据字段

字段	必填	详情	示例
`endpoint`	Y	Alibaba Cloud TableStore 实例的端点	`"https://tablestore.aliyuncs.com"`
`instanceName`	Y	Alibaba Cloud TableStore 实例的名称	`"my_instance"`
`tableName`	Y	用于 Dapr 状态的表的名称。如果不存在，将会创建它	`"my_table"`
`accessKeyID`	Y	用于身份验证的访问密钥 ID	`"my_access_key_id"`
`accessKey`	Y	用于身份验证的访问密钥	`"my_access_key"`

身份验证

Alibaba Cloud TableStore 支持使用 Access Key 和 Access Key ID 进行身份验证。

你也可以使用 Dapr 的 secret store 来安全地存储这些值，而不是直接将它们包含在 YAML 文件中。

使用密钥引用的示例：

- name: accessKeyID
  secretKeyRef:
    name: alicloud-secrets
    key: accessKeyID
- name: accessKey
  secretKeyRef:
    name: alicloud-secrets
    key: accessKey

10.3 - AWS DynamoDB

AWS DynamoDB 状态存储组件的详细信息

组件格式

要设置 DynamoDB 状态存储，请创建类型为 state.aws.dynamodb 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: accessKey
    value: "AKIAIOSFODNN7EXAMPLE" # 可选
  - name: secretKey
    value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" # 可选
  - name: endpoint
    value: "http://localhost:8080" # 可选
  - name: region
    value: "eu-west-1" # 可选
  - name: sessionToken
    value: "myTOKEN" # 可选
  - name: ttlAttributeName
    value: "expiresAt" # 可选
  - name: ttlInSeconds
    value: <int> # 可选
  - name: partitionKey
    value: "ContractID" # 可选
  # 如希望将 AWS DynamoDB 用作 actor 的状态存储，请取消此注释（可选）
  #- name: actorStateStore
  #  value: "true"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

主键

为了将 DynamoDB 用作 Dapr 状态存储，表必须具有名为 key 的主键。有关更改此行为的选项，请参阅分区键部分。

规格元数据字段

字段	必填	详情	示例
table	Y	要使用的 DynamoDB 表名	`"Contracts"`
accessKey	N	具有访问 SNS 和 SQS 适当权限的 AWS 账户 ID。可以是 `secretKeyRef` 以使用密钥引用	`"AKIAIOSFODNN7EXAMPLE"`
secretKey	N	AWS 用户的密钥。可以是 `secretKeyRef` 以使用密钥引用	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
region	N	实例的 AWS 区域。有关有效区域，请参阅此页面：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html。确保该区域支持 DynamoDB。	`"us-east-1"`
endpoint	N	组件要使用的 AWS 端点。仅用于本地开发。针对生产 AWS 运行时不需要 `endpoint`	`"http://localhost:4566"`
sessionToken	N	要使用的 AWS 会话令牌。仅在使用临时安全凭证时才需要会话令牌。	`"TOKEN"`
ttlAttributeName	N	应用于 TTL 的表属性名称。	`"expiresAt"`
ttlInSeconds	N	允许指定以秒为单位的生存时间（TTL），该 TTL 将应用于每个状态存储请求，除非通过请求元数据明确定义了 TTL。如果设置为零或更小，则不会应用默认 TTL，并且只有在设置了 ttlAttributeName 且在请求元数据中明确提供了 TTL 时，项目才会过期。	`600`
partitionKey	N	表主键或分区键属性名称。此字段用于替换默认主键属性名称 `"key"`。请参阅分区键部分。	`"ContractID"`
actorStateStore	N	将此状态存储用于 actor。默认为 “false”	`"true"`, `"false"`

Important

在 EKS（AWS Kubernetes）上使用您的应用程序运行 Dapr 边车（daprd）时，如果您使用的节点/pod 已附加到定义了 AWS 资源访问权限的 IAM 策略，则不得在您使用的组件规格定义中提供 AWS 访问密钥、密钥和令牌。

设置 AWS DynamoDB

有关身份验证相关属性的信息，请参阅向 AWS 进行身份验证

生存时间（TTL）

要使用 DynamoDB TTL 功能，您必须在表上启用 TTL 并定义属性名称。属性名称必须在 ttlAttributeName 字段中定义。请参阅官方 AWS 文档。

分区键

默认情况下，DynamoDB 状态存储组件使用表属性名称 key 作为 DynamoDB 表中的主键/分区键。可以通过在组件配置中指定元数据字段来覆盖，其键为 partitionKey，值为所需的属性名称。

要了解有关 DynamoDB 主键/分区键的更多信息，请阅读 AWS DynamoDB 开发者指南。

以下 statestore.yaml 文件显示了如何配置 DynamoDB 状态存储组件以使用分区键属性名称 ContractID：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: partitionKey
    value: "ContractID"

上述组件规格假定以下 DynamoDB 表布局：

{
    "Table": {
        "AttributeDefinitions": [
            {
                "AttributeName": "ContractID",
                "AttributeType": "S"
            }
        ],
        "TableName": "Contracts",
        "KeySchema": [
            {
                "AttributeName": "ContractID",
                "KeyType": "HASH"
            }
        ],
}

以下操作将 "A12345" 作为 key 的值传递，根据上面提供的组件规格，Dapr 运行时将把 key 属性名称替换为 ContractID，作为发送到 DynamoDB 的分区/主键：

$ dapr run --app-id contractsprocessing --app-port ...

$ curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "A12345",
          "value": "Dapr Contract"
        }
      ]'

以下 AWS CLI 命令显示 DynamoDB Contracts 表的内容：

$ aws dynamodb get-item \
    --table-name Contracts \
    --key '{"ContractID":{"S":"contractsprocessing||A12345"}}' 
{
    "Item": {
        "value": {
            "S": "Dapr Contract"
        },
        "etag": {
            "S": "....."
        },
        "ContractID": {
            "S": "contractsprocessing||A12345"
        }
    }
}

工作流限制

Note

如下所述，DynamoDB 的限制可能使其不适合生产环境。目前无法将工作流数据从 DynamoDB 迁移到另一个状态存储，这意味着在生产环境中超过这些限制将导致工作流失败，且没有解决方法。

工作流越复杂（活动数量、子工作流等），它在每个状态存储事务中执行的状态操作就越多。 DynamoDB 在单个事务中可以执行的最大操作数为 100。这意味着 DynamoDB 只能处理复杂度有限的工作流，因此并不适合所有工作流场景。有关在工作流执行期间保存的记录数量的一般指南，可在此处找到。

10.4 - Azure Blob Storage

Azure Blob Store 状态存储组件的详细信息

组件格式

要设置 Azure Blob Storage 状态存储，需创建类型为 state.azure.blobstorage 的组件。请参阅本指南了解如何创建并应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.blobstorage
  # 支持 v1 和 v2。用户应始终默认使用 v2。没有从 v1 到 v2 的迁移路径，参见下面的 `versioning`。
  version: v2
  metadata:
  - name: accountName
    value: "[your_account_name]"
  - name: accountKey
    value: "[your_account_key]"
  - name: containerName
    value: "[your_container_name]"

Warning

上述示例将密钥以明文字符串的形式使用。建议使用密钥存储来管理密钥，如此处所述。

版本

Dapr 有 2 个版本的 Azure Blob Storage 状态存储组件：v1 和 v2。建议所有新应用程序使用 v2。v1 被视为旧版本，仅为了与现有应用程序兼容而保留。

在 v1 中，发现了一个长期存在的实现问题，其中组件错误地剥离了键前缀，其行为本质上就像 keyPrefix 总是被设置为 none。
组件的更新版本 v2 修复了此错误行为，并使状态存储正确遵守 keyPrefix 属性。

虽然 v1 和 v2 具有相同的元数据字段，但它们在其他方面不兼容，并且没有从 v1 到 v2 的自动数据迁移路径。

如果您正在使用此组件的 v1 版本，则应继续使用 v1，直到创建新的状态存储。

规格元数据字段

字段	必填	详情	示例
`accountName`	Y	存储账户名称	`"mystorageaccount"`。
`accountKey`	Y（除非使用 Microsoft Entra ID）	主存储密钥或辅助存储密钥	`"key"`
`containerName`	Y	用于 Dapr 状态的容器的名称。如果容器不存在，将为您创建该容器	`"container"`
`azureEnvironment`	N	如果使用不同的 Azure 云，则为 Azure 环境的可选名称	`"AZUREPUBLICCLOUD"`（默认值）、`"AZURECHINACLOUD"`、`"AZUREUSGOVERNMENTCLOUD"`
`endpoint`	N	可选的自定义终结点 URL。当使用 Azurite 模拟器或为 Azure Storage 使用自定义域时（尽管这不是官方支持的），这很有用。终结点必须是完整的基本 URL，包括协议（`http://` 或 `https://`）、IP 或 FQDN 以及可选端口。	`"http://127.0.0.1:10000"`
`ContentType`	N	blob 的内容类型	`"text/plain"`
`ContentMD5`	N	blob 的 MD5 哈希	`"vZGKbMRDAnMs4BIwlXaRvQ=="`
`ContentEncoding`	N	blob 的内容编码	`"UTF-8"`
`ContentLanguage`	N	blob 的内容语言	`"en-us"`
`ContentDisposition`	N	blob 的内容处置。传达有关如何处理响应负载的其他信息	`"attachment"`
`CacheControl`	N	blob 的缓存控制	`"no-cache"`

设置 Azure Blob Storage

按照说明从 Azure 文档中了解如何创建 Azure 存储账户。

如果您希望为 Dapr 创建一个要使用的容器，可以预先创建。但是，如果 Blob Storage 状态提供程序不存在，它将自动为您创建一个。

为了将 Azure Blob Storage 设置为状态存储，您需要以下属性：

accountName：存储账户名称。例如：mystorageaccount。
accountKey：主存储账户密钥或辅助存储账户密钥。
containerName：用于 Dapr 状态的容器的名称。如果容器不存在，将为您创建该容器。

使用 Microsoft Entra ID 进行身份验证

此组件支持使用 Microsoft Entra ID 进行身份验证，作为使用账户密钥的替代方法。在可能的情况下，建议在生产系统中使用 Microsoft Entra ID 进行身份验证，以利用更好的安全性、精细的访问控制以及为在 Azure 上运行的应用程序使用托管标识的能力。

以下脚本针对 bash 或 zsh shell 进行了优化，并且需要安装以下应用程序：
Azure CLI
jq
您还必须在 Azure CLI 中通过 Azure 身份验证。

要开始使用 Microsoft Entra ID 对 Blob Storage 状态存储组件进行身份验证，请确保您已创建 Microsoft Entra ID 应用程序和服务主体，如向 Azure 进行身份验证文档中所述。
完成后，使用您创建的服务主体的 ID 设置一个变量：

SERVICE_PRINCIPAL_ID="[your_service_principal_object_id]"

使用您的 Azure 存储账户的名称及其所在的资源组的名称设置以下变量：

STORAGE_ACCOUNT_NAME="[your_storage_account_name]"
RG_NAME="[your_resource_group_name]"

使用 RBAC 为我们的服务主体分配一个角色，以便它可以访问存储账户内的数据。
在这种情况下，您分配的是"Storage blob Data Contributor"角色，该角色具有广泛的访问权限；根据您的应用程序，也可以使用其他更严格的角色。

RG_ID=$(az group show --resource-group ${RG_NAME} | jq -r ".id")
az role assignment create \
  --assignee "${SERVICE_PRINCIPAL_ID}" \
  --role "Storage blob Data Contributor" \
  --scope "${RG_ID}/providers/Microsoft.Storage/storageAccounts/${STORAGE_ACCOUNT_NAME}"

当使用 Microsoft Entra ID 对组件进行身份验证时，不需要 accountKey 字段。相反，请根据向 Azure 进行身份验证文档，在组件的元数据中指定所需的凭据（如果有）。

例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.blobstorage
  version: v1
  metadata:
  - name: accountName
    value: "[your_account_name]"
  - name: containerName
    value: "[your_container_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    value : "[your_client_secret]"

应用配置

在 Kubernetes 中

要将 Azure Blob Storage 状态存储应用于 Kubernetes，请使用 kubectl CLI：

kubectl apply -f azureblob.yaml

本地运行

要在本地运行，请创建一个包含 YAML 文件的 components 目录，并使用标志 --resources-path 将路径提供给 dapr run 命令。

此状态存储在容器中创建一个 blob 文件，并将原始状态放入其中。

例如，来自名为 myservice 的服务的以下操作：

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

这将在容器中创建 blob 文件，其中 key 作为文件名，value 作为文件的内容。

并发

根据 Azure Blob Storage 文档，通过使用 ETag 来实现 Azure Blob Storage 状态并发。

10.5 - Azure Cosmos DB (SQL API)

Azure Cosmos DB (SQL API) 状态存储组件的详细信息

组件格式

要设置 Azure Cosmos DB 状态存储，请创建类型为 state.azure.cosmosdb 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.cosmosdb
  version: v1
  metadata:
  - name: url
    value: <REPLACE-WITH-URL>
  - name: masterKey
    value: <REPLACE-WITH-MASTER-KEY>
  - name: database
    value: <REPLACE-WITH-DATABASE>
  - name: collection
    value: <REPLACE-WITH-COLLECTION>
  # 如果您希望使用 Azure Cosmos DB 作为 actor 的状态存储，请取消注释此选项（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例使用明文字符串作为密钥。建议使用密钥存储来管理密钥，具体说明请参见此处。

如果您希望将 Cosmos DB 用作 actor 存储，请在 yaml 中添加以下内容。

  - name: actorStateStore
    value: "true"

规范元数据字段

字段	必填	详情	示例
url	Y	Cosmos DB 的 URL	`"https://******.documents.azure.com:443/"`。
masterKey	Y*	用于向 Cosmos DB 账户进行身份验证的密钥。仅在不使用 Microsoft Entra ID 身份验证时需要。	`"key"`
database	Y	数据库的名称	`"db"`
collection	Y	集合（容器）的名称	`"collection"`
actorStateStore	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

Microsoft Entra ID 身份验证

Azure Cosmos DB 状态存储组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据选择的 Microsoft Entra ID 身份验证机制需要提供的组件元数据字段，请参阅 Azure 身份验证文档。

您可以在下方的部分中阅读有关使用 Azure AD 身份验证设置 Cosmos DB 的更多信息。

设置 Azure Cosmos DB

按照说明从 Azure 文档中了解如何创建 Azure Cosmos DB 账户。数据库和集合必须在 Dapr 使用之前在 Cosmos DB 中创建。

重要：集合的分区键必须命名为 /partitionKey（注意：这是区分大小写的）。

为了将 Cosmos DB 设置为状态存储，您需要以下属性：

URL：Cosmos DB 的 URL。例如：https://******.documents.azure.com:443/
主密钥：用于向 Cosmos DB 账户进行身份验证的密钥。如果使用 Microsoft Entra ID 身份验证，请跳过此项。
数据库：数据库的名称
集合：集合（或容器）的名称

TTL 和清理

此状态存储支持使用 Dapr 存储的记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以覆盖 CosmodDB 容器上的默认 TTL，指示数据何时应被视为"已过期"。请注意，只有当容器的 DefaultTimeToLive 字段具有非 NULL 值时，此值才会生效。有关更多信息，请参阅 CosmosDB 文档。

生产环境的最佳实践

Azure Cosmos DB 在单个 Azure Cosmos DB 账户的所有数据库之间共享严格的可接受的元数据请求速率限制。与 Azure Cosmos DB 的新连接会占用可接受的请求速率限制的很大一部分。（请参阅 Cosmos DB 文档）

因此，必须应用多种策略来避免同时建立与 Azure Cosmos DB 的新连接：

确保应用程序的边车仅在需要时才加载 Azure Cosmos DB 组件，以避免不必要的数据库连接。这可以通过将组件范围限定到特定应用程序来实现。
选择顺序部署或启动应用程序的部署策略，以最大程度减少对 Azure Cosmos DB 账户的新连接突发。
避免为不相关的数据库或系统重用同一个 Azure Cosmos DB 账户（即使在 Dapr 之外）。不同的 Azure Cosmos DB 账户具有不同的速率限制。
增加 initTimeout 值以允许组件在边车初始化期间重试连接 Azure Cosmos DB，最多 5 分钟。默认值为 5s，应该增加。使用 Kubernetes 时，增加此值可能还需要更新您的 Readiness 和 Liveness 探测。

spec:
  type: state.azure.cosmosdb
  version: v1
  initTimeout: 5m
  metadata:

数据格式

要使用 Cosmos DB 状态存储，您的数据必须以 JSON 序列化格式发送到 Dapr。仅具有 JSON 可序列化是不够的。

如果您使用的是 Dapr SDK（例如 .NET SDK），SDK 会自动将您的数据序列化为 JSON。

如果您想直接调用 Dapr 的 HTTP 端点，请查看下面分区键部分中的示例（使用 curl）。

分区键

对于 非 actor 状态操作，Azure Cosmos DB 状态存储将使用对 Dapr API 的请求中提供的 key 属性来确定 Cosmos DB 分区键。可以通过在请求中指定元数据字段来覆盖此设置，该元数据字段的键为 partitionKey，值为所需的分区。

以下操作使用 nihilus 作为发送到 Cosmos DB 的分区键值：

curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

对于 非 actor 状态操作，如果您想控制 Cosmos DB 分区，可以在元数据中指定它。重用上面的示例，以下是如何将其放在 mypartition 分区下

curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth",
          "metadata": {
            "partitionKey": "mypartition"
          }
        }
      ]'

对于 actor 状态操作，分区键由 Dapr 使用 appId、actor 类型和 actor id 生成，使得同一 actor 的数据始终位于同一分区下（您无需指定它）。这是因为 actor 状态操作必须使用事务，而在 Cosmos DB 中，事务中的项目必须位于同一分区上。

为使用 Microsoft Entra ID 进行身份验证而设置 Cosmos DB

使用 Dapr Cosmos DB 状态存储并通过 Microsoft Entra ID 进行身份验证时，您需要执行一些额外步骤来设置环境。

先决条件：

您需要按照 Azure 身份验证页面上的说明创建一个服务主体。以下命令需要服务主体的 ID（请注意，这与您的应用程序的客户端 ID 或您在元数据中用于 azureClientId 的值不同）。
Azure CLI
jq
以下脚本针对 bash 或 zsh shell 进行了优化

授予您的 Microsoft Entra ID 应用程序对 Cosmos DB 的访问权限

您可以在官方文档中找到更多信息，包括分配更细粒度权限的说明。

为了授予您的应用程序访问存储在 Cosmos DB 中的数据的权限，您需要为其分配 Cosmos DB 数据平面的自定义角色。在此示例中，您将使用内置角色"Cosmos DB 内置数据参与者"，该角色授予您的应用程序对数据的完全读写访问权限；您可以选择按照官方文档中的说明创建自定义的、精细的角色。

# 包含您的 Cosmos DB 的资源组名称
RESOURCE_GROUP="..."
# 您的 Cosmos DB 账户名称
ACCOUNT_NAME="..."
# 您的服务主体对象的 ID
PRINCIPAL_ID="..."
# "Cosmos DB 内置数据参与者"角色的 ID
# 您也可以使用自定义角色的 ID
ROLE_ID="00000000-0000-0000-0000-000000000002"

az cosmosdb sql role assignment create \
  --account-name "$ACCOUNT_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --scope "/" \
  --principal-id "$PRINCIPAL_ID" \
  --role-definition-id "$ROLE_ID"

优化

优化 Cosmos DB 以实现批量操作写入性能

如果您构建的系统仅通过键 (id) 从 Cosmos DB 读取数据，这是使用状态管理 API 或 actor 时的默认 Dapr 行为，您可以通过一些方式优化 Cosmos DB 以提高写入速度。这是通过从索引中排除所有路径来实现的。默认情况下，Cosmos DB 对文档内的所有字段进行索引。在写入繁重的系统上，并且对文档内的值运行很少或没有查询的情况下，此索引策略会减慢在 Cosmos DB 中写入或更新文档的时间。这在大量系统中会更加严重。

例如，Cosmos SQL 容器索引的默认 Terraform 定义如下：

indexing_policy {
  indexing_mode = "consistent"

  included_path {
    path = "/*"
  }
}

可以通过从索引中排除所有其他字段来强制 Cosmos DB 仅索引 id 和 partitionKey 字段。这可以通过将上述内容更新为以下内容来实现：

indexing_policy {
  # 如果您纯粹将容器用作键值存储，这也可以设置为 "none"。如果您的容器仅用作分布式缓存，这可能适用。
  indexing_mode = "consistent" 

  # 请注意，included_path 已被替换为 excluded_path
  excluded_path {
    path = "/*"
  }
}

注意

此优化的代价是对状态存储中文档内的字段的查询。这可能会影响任何定义和执行的存储过程或 SQL 查询。仅建议在您使用 Dapr 状态管理 API 或 Dapr Actor 与 Cosmos DB 交互时才应用此优化。

优化 Cosmos DB 以节省成本

如果您打算仅将 Cosmos DB 用作键值对，可能会考虑将状态对象转换为 JSON 并在持久化到状态之前对其进行压缩，然后在从状态中读取时对其进行解压缩，这可能符合您的利益。这是因为 Cosmos DB 根据给定时间段（通常是每小时）内使用的最大 RU/s 数向您收费。此外，RU 使用量计算为每读取或写入 1 KB 数据 1 RU。压缩通过减少存储在 Cosmos DB 中的数据大小来帮助减少 RU 使用量。

这种节省对于 Dapr actor 来说特别重要。虽然 Dapr 状态管理 API 在保存之前对对象进行 base64 编码，但 Dapr actor 状态以原始格式化的 JSON 形式保存。这意味着多行带有缩进用于格式化。压缩可以显着减少 actor 状态对象的大小。例如，如果您有一个 actor 状态对象，在 actor 水合时大小为 75KB，您将使用 75 RU/s 从状态中读取该对象。如果您随后修改状态对象并将其增长到 100KB，您将使用 100 RU/s 将该对象写入 Cosmos DB，总共 175 RU/s 用于 I/O 操作。假设您的 actor 每秒并发处理 1000 个请求，您将至少需要 175,000 RU/s 才能满足该负载。通过有效的压缩，大小减少可以达到 90% 左右，这意味着您只需要大约 17,500 RU/s 就能满足负载。

注意

此特定优化仅在您将大型对象保存到状态时才有意义。在任一端执行压缩和解压缩的性能和内存权衡需要适合您的用例。此外，一旦数据保存到状态，它就不可读，也不可查询。仅当您将大型状态对象保存为键值对时，才应采用此优化。

工作流限制

注意

如下所述，CosmosDB 具有限制，可能使其不适合生产环境。目前没有将工作流数据从 CosmosDB 迁移到另一个状态存储的路径，这意味着在生产环境中超出这些限制将导致工作流失败，并且没有解决方法。

工作流越复杂，包含的活动数量、子工作流等越多，每个状态存储事务执行的 DB 状态操作就越多。所有输入和输出值都保存到工作流历史记录中，并且是这些事务操作的一部分。 CosmosDB 的最大文档大小为 2MB，最大事务大小为 100 个操作。尝试超出这些限制写入 CosmosDB 会导致错误代码 413。这意味着工作流历史记录不得超过此大小，这意味着 CosmosDB 不适合具有大型输入/输出值或更复杂的工作流。有关在工作流执行期间保存的记录数量的一般指南，可以在此处找到。

10.6 - Azure Table Storage

关于 Azure Table Storage 状态存储组件的详细信息，该组件可用于连接到 Cosmos DB Table API 和 Azure Tables

组件格式

要设置 Azure Tablestorage 状态存储，请创建一个类型为 state.azure.tablestorage 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.tablestorage
  version: v1
  metadata:
  - name: accountName
    value: <REPLACE-WITH-ACCOUNT-NAME>
  - name: accountKey
    value: <REPLACE-WITH-ACCOUNT-KEY>
  - name: tableName
    value: <REPLACE-WITH-TABLE-NAME>
# - name: cosmosDbMode
#   value: false

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体说明请参见此处。

规范元数据字段

字段	必填	详情	示例
`accountName`	Y	存储账户名称	`"mystorageaccount"`。
`accountKey`	Y	主密钥或辅助存储密钥	`"key"`
`tableName`	Y	用于 Dapr 状态的表的名称。如果表不存在，将自动为你创建	`"table"`
`cosmosDbMode`	N	如果启用，则连接到 Cosmos DB Table API 而非 Azure Tables（存储账户）。默认为 `false`。	`"false"`
`serviceURL`	N	完整的存储服务终结点 URL。适用于公有云之外的 Azure 环境。	`"https://mystorageaccount.table.core.windows.net/"`
`skipCreateTable`	N	跳过对指定存储表的检查（以及在必要时创建该表）。在使用具有最小权限的 Active Directory 身份验证时很有用。默认为 `false`。	`"true"`

Microsoft Entra ID 身份验证

Azure Cosmos DB 状态存储组件支持使用所有 Microsoft Entra ID 机制进行身份验证。有关更多信息以及根据所选的 Microsoft Entra ID 身份验证机制需要提供的相关组件元数据字段，请参阅向 Azure 进行身份验证的文档。

你可以在下一节中阅读有关使用 Microsoft Entra ID 身份验证设置 Cosmos DB 的其他信息。

选项 1：设置 Azure Table Storage

按照 Azure 文档中的说明创建 Azure 存储账户。

如果你希望为 Dapr 创建一个表，可以提前创建。不过，除非启用了 skipCreateTable 选项，否则如果表不存在，Table Storage 状态提供程序会自动为你创建一个。

要设置 Azure Table Storage 作为状态存储，你需要以下属性：

AccountName：存储账户名称。例如：mystorageaccount。
AccountKey：主密钥或辅助存储密钥。如果使用 Microsoft Entra ID 身份验证，请跳过此项。
TableName：用于 Dapr 状态的表的名称。如果表不存在，将自动为你创建，除非启用了 skipCreateTable 选项。
cosmosDbMode：将此项设置为 false 以连接到 Azure Tables。

选项 2：设置 Azure Cosmos DB Table API

按照 Azure 文档中的说明创建一个具有 Table API 的 Cosmos DB 账户。

要设置 Azure Cosmos DB Table API 作为状态存储，你需要以下属性：

AccountName：Cosmos DB 账户名称。例如：mycosmosaccount。
AccountKey：Cosmos DB 主密钥。如果使用 Microsoft Entra ID 身份验证，请跳过此项。
TableName：用于 Dapr 状态的表的名称。如果表不存在，将自动为你创建，除非启用了 skipCreateTable 选项。
cosmosDbMode：将此项设置为 true 以连接到 Azure Tables。

分区

Azure Table Storage 状态存储使用在 Dapr API 请求中提供的 key 属性来确定 row key。服务名称用作 partition key。这提供了最佳性能，因为每种服务类型在自己的表分区中存储状态。

此状态存储在表存储中创建一个名为 Value 的列，并将原始状态放入其中。

例如，以下来自名为 myservice 的服务的操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

将在表中创建以下记录：

PartitionKey	RowKey	Value
myservice	nihilus	darth

并发

Azure Table Storage 状态并发是通过根据官方文档使用 ETag 来实现的。

10.7 - Cassandra

Cassandra 状态存储组件的详细信息

组件格式

要设置 Cassandra 状态存储，请创建类型为 state.cassandra 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cassandra
  version: v1
  metadata:
  - name: hosts
    value: <REPLACE-WITH-COMMA-DELIMITED-HOSTS> # 必填。示例：cassandra.cassandra.svc.cluster.local
  - name: username
    value: <REPLACE-WITH-PASSWORD> # 可选。默认值：""
  - name: password
    value: <REPLACE-WITH-PASSWORD> # 可选。默认值：""
  - name: consistency
    value: <REPLACE-WITH-CONSISTENCY> # 可选。默认值："All"
  - name: table
    value: <REPLACE-WITH-TABLE> # 可选。默认值："items"
  - name: keyspace
    value: <REPLACE-WITH-KEYSPACE> # 可选。默认值："dapr"
  - name: protoVersion
    value: <REPLACE-WITH-PROTO-VERSION> # 可选。默认值："4"
  - name: replicationFactor
    value: <REPLACE-WITH-REPLICATION-FACTOR> #  可选。默认值："1"

警告

上述示例使用明文字符串作为密钥。建议使用密钥存储来管理密钥，具体说明请参阅此处。

规范元数据字段

字段	必填	详情	示例
hosts	Y	主机的逗号分隔值	`"cassandra.cassandra.svc.cluster.local"`。
port	N	通信端口。默认值为 `"9042"`	`"9042"`
username	Y	数据库用户的用户名。无默认值	`"user"`
password	Y	用户的密码	`"password"`
consistency	N	一致性值	`"All"`、`"Quorum"`
table	N	表名。默认值为 `"items"`	`"items"`、`"tab"`
keyspace	N	要使用的 Cassandra 键空间。默认值为 `"dapr"`	`"dapr"`
protoVersion	N	客户端的协议版本。默认值为 `"4"`	`"3"`、`"4"`
replicationFactor	N	调用的复制因子。默认值为 `"1"`	`"3"`

设置 Cassandra

您可以使用 Datastax Docker 镜像在本地运行 Cassandra：

docker run -e DS_LICENSE=accept --memory 4g --name my-dse -d datastax/dse-server -g -s -k

然后您可以使用 localhost:9042 与服务器交互。

在 Kubernetes 上安装 Cassandra 最简单的方法是使用 Helm chart：

kubectl create namespace cassandra
helm install cassandra incubator/cassandra --namespace cassandra

这将默认把 Cassandra 安装到 cassandra 命名空间中。要与 Cassandra 交互，请使用以下命令查找服务：kubectl get svc -n cassandra。

例如，如果使用上述示例安装，Cassandra DNS 将是：

cassandra.cassandra.svc.cluster.local

Apache Ignite

Apache Ignite 与作为缓存层的 Cassandra 集成不被此组件支持。

Apache Ignite

Apache Ignite 与作为缓存层的 Cassandra 集成不被此组件支持。

Apache Ignite

Apache Ignite 与作为缓存层的 Cassandra 集成不被此组件支持。

10.8 - Cloudflare Workers KV

Cloudflare Workers KV 状态存储组件的详细信息

创建 Dapr 组件

要设置 Cloudflare Workers KV 状态存储，请创建一个类型为 state.cloudflare.workerskv 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cloudflare.workerskv
  version: v1
  # 如果 Dapr 为您管理 Worker，请增加 initTimeout
  initTimeout: "120s"
  metadata:
    # Workers KV 命名空间的 ID（必需）
    - name: kvNamespaceID
      value: ""
    # Worker 的名称（必需）
    - name: workerName
      value: ""
    # PEM 编码的 Ed25519 私钥（必需）
    - name: key
      value: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQ...
        -----END PRIVATE KEY-----
    # Cloudflare 账户 ID（让 Dapr 管理 Worker 时必需）
    - name: cfAccountID
      value: ""
    # Cloudflare 的 API 令牌（让 Dapr 管理 Worker 时必需）
    - name: cfAPIToken
      value: ""
    # Worker 的 URL（如果在 Dapr 外部预先创建了 Worker 则必需）
    - name: workerUrl
      value: ""

警告

上述示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`kvNamespaceID`	Y	预先创建的 Workers KV 命名空间的 ID	`"123456789abcdef8b5588f3d134f74ac"`
`workerName`	Y	要连接的 Worker 的名称	`"mydaprkv"`
`key`	Y	Ed25519 私钥，PEM 编码	参见上文示例
`cfAccountID`	Y/N	Cloudflare 账户 ID。让 Dapr 管理 Worker 时必需。	`"456789abcdef8b5588f3d134f74ac"def`
`cfAPIToken`	Y/N	Cloudflare 的 API 令牌。让 Dapr 管理 Worker 时必需。	`"secret-key"`
`workerUrl`	Y/N	Worker 的 URL。如果在 Dapr 外部预先预配了 Worker 则必需。	`"https://mydaprkv.mydomain.workers.dev"`

当您配置 Dapr 为您创建 Worker 时，可能需要为组件的 initTimeout 属性设置更长的值，以留出足够的时间来部署 Worker 脚本。例如：initTimeout: "120s"

创建 Workers KV 命名空间

要使用此组件，您必须在您的 Cloudflare 账户中创建一个 Workers KV 命名空间。

您可以通过以下两种方式之一创建新的 Workers KV 命名空间：

使用 Cloudflare 控制面板
记下您在控制面板中可以看到的 Workers KV 命名空间的 “ID”。这是一个十六进制字符串（例如 123456789abcdef8b5588f3d134f74ac）——不是您创建时使用的名称！

使用 Wrangler CLI：

# 如需身份验证，首先运行 `npx wrangler login`
wrangler kv:namespace create <NAME>

输出包含命名空间的 ID，例如：

{ binding = "<NAME>", id = "123456789abcdef8b5588f3d134f74ac" }

配置 Worker

由于 Cloudflare Workers KV 命名空间只能由在 Workers 上运行的脚本访问，Dapr 需要维护一个 Worker 来与 Workers KV 存储进行通信。

Dapr 可以自动为您管理 Worker，或者您可以自己预先预配一个 Worker。在 workerd 上运行时，预先预配 Worker 是唯一支持的选项。

重要

为每个 Dapr 组件使用单独的 Worker。不要为不同的 Cloudflare Workers KV 状态存储组件使用同一个 Worker 脚本，也不要为 Dapr 中不同的 Cloudflare 组件使用同一个 Worker 脚本（例如，Workers KV 状态存储和 Queues 绑定）。

如果您想让 Dapr 为您管理 Worker，您需要提供以下 3 个元数据选项：

workerName：Worker 脚本的名称。这将是您的 Worker URL 的第一部分。例如，如果为您的 Cloudflare 账户配置的 “workers.dev” 域是 mydomain.workers.dev，并且您将 workerName 设置为 mydaprkv，Dapr 部署的 Worker 将在 https://mydaprkv.mydomain.workers.dev 访问。
cfAccountID：您的 Cloudflare 账户的 ID。登录 Cloudflare 控制面板后，您可以在浏览器地址栏中找到它，ID 是 dash.cloudflare.com 右侧的十六进制字符串。例如，如果 URL 是 https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef，则 cfAccountID 的值是 456789abcdef8b5588f3d134f74acdef。
cfAPIToken：具有创建和编辑 Workers 及 Workers KV 命名空间权限的 API 令牌。您可以在 Cloudflare 控制面板的 “My Profile” 部分的 “API Tokens” 页面中创建它：
1. 点击 “Create token”。
2. 选择 “Edit Cloudflare Workers” 模板。
3. 按照屏幕上的说明生成新的 API 令牌。

当 Dapr 配置为为您管理 Worker 时，当 Dapr 运行时启动时，它会检查 Worker 是否存在且是最新的。如果 Worker 不存在，或者使用的是过时的版本，Dapr 将自动为您创建或升级它。

如果您不想授予 Dapr 为您部署 Worker 脚本的权限，可以手动预配一个 Worker 供 Dapr 使用。请注意，如果您有多个 Dapr 组件通过 Worker 与 Cloudflare 服务交互，您需要为每个组件创建一个单独的 Worker。

要手动预配 Worker 脚本，您需要在本地机器上安装 Node.js。

创建一个新文件夹来放置 Worker 的源代码，例如：daprworker。
如果尚未完成，请使用以下命令通过 Wrangler（Cloudflare Workers CLI）进行身份验证：npx wrangler login。
在新创建的文件夹中，创建一个新的 wrangler.toml 文件，内容如下，并根据需要填写缺失的信息：

# 您的 Worker 的名称，例如 "mydaprkv"
name = ""

# 不要更改这些选项
main = "worker.js"
compatibility_date = "2022-12-09"
usage_model = "bundled"

[vars]
# 将此设置为 Ed25519 密钥的**公钥**部分，PEM 编码（换行符替换为 `\n`）。
# 示例：
# PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowB...=\n-----END PUBLIC KEY-----
PUBLIC_KEY = ""
# 将此设置为您的 Worker 的名称（与上方的 "name" 属性值相同），例如 "mydaprkv"。
TOKEN_AUDIENCE = ""

[[kv_namespaces]]
# 将以下两个值设置为您的 KV 命名空间的 ID（而不是名称），例如 "123456789abcdef8b5588f3d134f74ac"。
# 请注意，它们将被设置为相同的值。
binding = ""
id = ""

注意：有关如何生成 Ed25519 密钥对，请参阅下一节。确保在部署 Worker 时使用密钥的公钥部分！

将 Worker 的（预编译和压缩的）代码复制到 worker.js 文件中。您可以使用以下命令执行此操作：

# 将此设置为您正在使用的 Dapr 版本
DAPR_VERSION="release-1.18"
curl -LfO "https://raw.githubusercontent.com/dapr/components-contrib/${DAPR_VERSION}/internal/component/cloudflare/workers/code/worker.js"

使用 Wrangler 部署 Worker：

npx wrangler publish

Worker 部署完成后，您需要使用以下两个元数据选项来初始化组件：

workerName：Worker 脚本的名称。这是您在 wrangler.toml 文件的 name 属性中设置的值。
workerUrl：已部署的 Worker 的 URL。npx wrangler command 将显示完整的 URL，例如 https://mydaprkv.mydomain.workers.dev。

生成 Ed25519 密钥对

所有 Cloudflare Workers 都监听公共 Internet，因此 Dapr 需要使用额外的身份验证和数据保护措施来确保没有其他人员或应用程序可以与您的 Worker 通信（进而与您的 Worker KV 命名空间通信）。这些措施包括行业标准措施，例如：

Dapr 向 Worker 发出的所有请求都通过不记名令牌（技术上是 JWT）进行身份验证，该令牌使用 Ed25519 密钥签名。
Dapr 与您的 Worker 之间的所有通信都通过加密连接进行，使用 TLS (HTTPS)。
不记名令牌在每个请求上生成，仅在很短的时间内有效（目前为一分钟）。

要让 Dapr 颁发不记名令牌并让您的 Worker 验证它们，您需要生成一个新的 Ed25519 密钥对。以下是使用 OpenSSL 或 step CLI 生成密钥对的示例。

自 OpenSSL 1.1.0 起支持生成 Ed25519 密钥，因此如果您使用的是旧版本的 OpenSSL，以下命令将不起作用。

Mac 用户注意：在 macOS 上，Apple 附带的 “openssl” 二进制文件实际上基于 LibreSSL，截至撰写本文时，它不支持 Ed25519 密钥。如果您使用的是 macOS，请使用 step CLI，或使用 brew install openssl@3 从 Homebrew 安装 OpenSSL 3.0，然后将以下命令中的 openssl 替换为 $(brew --prefix)/opt/openssl@3/bin/openssl。

您可以使用 OpenSSL 生成新的 Ed25519 密钥对：

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

在 macOS 上，使用来自 Homebrew 的 openssl@3：

$(brew --prefix)/opt/openssl@3/bin/openssl genpkey -algorithm ed25519 -out private.pem
$(brew --prefix)/opt/openssl@3/bin/openssl pkey -in private.pem -pubout -out public.pem

如果您还没有 step CLI，请按照官方说明安装它。

接下来，您可以使用 step CLI 生成新的 Ed25519 密钥对：

step crypto keypair \
  public.pem private.pem \
  --kty OKP --curve Ed25519 \
  --insecure --no-password

无论您如何生成密钥对，按照上述说明，您将拥有两个文件：

private.pem 包含密钥的私钥部分；使用此文件的内容作为组件元数据的 key 属性。
public.pem 包含密钥的公钥部分，仅当您手动部署 Worker 时才需要（按照上一节的说明）。

警告

保护您密钥的私钥部分，并将其视为机密值！

其他注意事项

请注意，Cloudflare Workers KV 不保证强数据一致性。虽然对同一 Cloudflare 数据中心发出的请求的更改通常是立即可见的，但更改复制到所有 Cloudflare 区域可能需要一定的时间（通常长达一分钟）。
此状态存储支持 Dapr 的 TTL，但 TTL 的最小值为 1 分钟。

10.9 - CockroachDB

CockroachDB 状态存储组件的详细信息

创建 Dapr 组件

创建一个名为 cockroachdb.yaml 的文件，粘贴以下内容并将 <CONNECTION STRING> 值替换为您的连接字符串。CockroachDB 的连接字符串遵循与 PostgreSQL 连接字符串相同的标准。例如，"host=localhost user=root port=26257 connect_timeout=10 database=dapr_test"。有关如何定义连接字符串的信息，请参阅 CockroachDB 关于数据库连接的文档。

如果您还想配置 CockroachDB 来存储 actor，请添加 actorStateStore 选项，如下面的示例所示。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cockroachdb
  version: v1
  metadata:
  # Connection string
  - name: connectionString
    value: "<CONNECTION STRING>"
  # Timeout for database operations, in seconds (optional)
  #- name: timeoutInSeconds
  #  value: 20
  # Name of the table where to store the state (optional)
  #- name: tableName
  #  value: "state"
  # Name of the table where to store metadata used by Dapr (optional)
  #- name: metadataTableName
  #  value: "dapr_metadata"
  # Cleanup interval in seconds, to remove expired rows (optional)
  #- name: cleanupIntervalInSeconds
  #  value: 3600
  # Max idle time for connections before they're closed (optional)
  #- name: connectionMaxIdleTime
  #  value: 0
  # Uncomment this if you wish to use CockroachDB as a state store for actors (optional)
  #- name: actorStateStore
  #  value: "true"

Warning

上面的示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	CockroachDB 的连接字符串	`"host=localhost user=root port=26257 connect_timeout=10 database=dapr_test"`
`timeoutInSeconds`	N	所有数据库操作的超时时间（秒）。默认为 `20`	`30`
`tableName`	N	存储数据的表的名称。默认为 `state`。可以选择性地包含模式名称作为前缀，例如 `public.state`	`"state"`, `"public.state"`
`metadataTableName`	N	Dapr 用于存储一些元数据属性的表的名称。默认为 `dapr_metadata`。可以选择性地包含模式名称作为前缀，例如 `public.dapr_metadata`	`"dapr_metadata"`, `"public.dapr_metadata"`
`cleanupIntervalInSeconds`	N	清理过期 TTL 行的间隔（秒）。默认值：`3600`（即 1 小时）。将此设置为 <=0 的值会禁用定期清理。	`1800`, `-1`
`connectionMaxIdleTime`	N	未使用的连接在连接池中自动关闭前的最大空闲时间。默认情况下没有值，这由数据库驱动程序选择。	`"5m"`
`actorStateStore`	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

设置 CockroachDB

运行一个 CockroachDB 实例。您可以使用以下命令在 Docker CE 中运行 CockroachDB 的本地实例：
此示例不描述生产配置，因为它设置的是单节点集群，仅推荐用于本地环境。
```
docker run --name roach1 -p 26257:26257 cockroachdb/cockroach:v21.2.3 start-single-node --insecure
```
为状态数据创建一个数据库。
要在 CockroachDB 中创建新数据库，请在容器内运行以下 SQL 命令：
```
docker exec -it roach1 ./cockroach sql --insecure -e 'create database dapr_test'
```

在 Kubernetes 上安装 CockroachDB 最简单的方法是使用 CockroachDB Operator：

高级

TTL 和清理

此状态存储支持 Dapr 存储记录的 Time-To-Live (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应在多少秒后被视为"过期"。

由于 CockroachDB 没有内置的 TTL 支持，Dapr 通过在状态表中添加一个列来实现此功能，该列指示数据应被视为"过期"的时间。即使"过期"记录仍物理存储在数据库中，也不会返回给调用者。后台"垃圾收集器"会定期扫描状态表中的过期行并将其删除。

您可以使用 cleanupIntervalInSeconds 元数据属性设置删除过期记录的间隔，该属性默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频率地扫描过期行，但可能需要存储过期记录更长时间，从而可能需要更多的存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupIntervalInSeconds 设置为较小的值 - 例如，300（300 秒，或 5 分钟）。
如果您不计划将 TTL 与 Dapr 和 CockroachDB 状态存储一起使用，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库负载。

10.10 - Coherence

关于 Coherence 状态存储组件的详细信息

组件格式

要设置 Coherence 状态存储，请创建一个类型为 state.coherence 的组件。有关如何创建和应用状态存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.coherence
  version: v1
  metadata:
  - name: serverAddress
    value: <REPLACE-WITH-GRPC-PROXY-HOST-AND-PORT> # 必填。示例："my-cluster-grpc:1408"
  - name: tlsEnabled
    value: <REPLACE-WITH-BOOLEAN> # 可选
  - name: tlsClientCertPath
    value: <REPLACE-WITH-PATH> # 可选
  - name: tlsClientKey
    value: <REPLACE-WITH-PATH> # 可选
  - name: tlsCertsPath
    value: <REPLACE-WITH-PATH> # 可选
  - name: ignoreInvalidCerts
    value: <REPLACE-WITH-BOOLEAN> # 可选
  - name: scopeName
    value: <REPLACE-WITH-SCOPE> # 可选
  - name: requestTimeout
    value: <REPLACE-WITH-REQUEST-TIMEOUT> # 可选
  - name: nearCacheTTL
    value: <REPLACE-WITH-NEAR-CACHE-TTL> # 可选
  - name: nearCacheUnits
    value: <REPLACE-WITH-NEAR-CACHE-UNITS> # 可选
  - name: nearCacheMemory
    value: <REPLACE-WITH-NEAR-CACHE-MEMORY> # 可选

警告

上述示例将密钥作为纯字符串使用。建议使用密钥存储来管理密钥，具体说明请参阅此处。

规范元数据字段

字段	必填	详情	示例
serverAddress	是	逗号分隔的端点	`"my-cluster-grpc:1408"`
tlsEnabled	否	指示是否应启用 TLS。默认为 false	`"true"`
tlsClientCertPath	否	Coherence 的客户端证书路径。默认为 “"。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
tlsClientKey	否	Coherence 的客户端密钥。默认为 “"。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
tlsCertsPath	否	Coherence 的附加证书。默认为 “"。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
ignoreInvalidCerts	否	指示是否忽略自签名证书，仅用于测试，不应用于生产环境。默认为 false	`"false"`
scopeName	否	用于内部缓存的作用域名称。默认为 "”	`"my-scope"`
requestTimeout	否	调用集群的超时时间，默认为 “30s”	`"15s"`
nearCacheTTL	否	如果非零，则使用近缓存，近缓存的 TTL 为此值。默认为 0s	`"60s"`
nearCacheUnits	否	如果非零，则使用近缓存，近缓存的最大大小为此值（以单位计）。默认为 0	`"1000"`
nearCacheMemory	否	如果非零，则使用近缓存，近缓存的最大大小为此值（以字节计）。默认为 0	`"4096"`

关于使用近缓存 TTL

Coherence 状态存储允许您指定近缓存来在使用 Dapr 客户端时缓存频繁访问的数据。当您使用 Get(ctx context.Context, req *GetRequest) 访问数据时，返回的条目会存储在近缓存中，并且对近缓存中键的后续数据访问几乎是即时的，而没有近缓存的每次 Get() 操作都会导致网络调用。

使用近缓存选项时，Coherence 会自动向内部缓存添加一个 MapListener，该监听器监听所有缓存事件，并更新或使近缓存中已在服务器上更改或删除的条目失效。

为了管理近缓存使用的内存量，在创建近缓存时支持以下选项：

nearCacheTTL – 对象在近缓存中过期的时间，例如 5 分钟
nearCacheUnits – 近缓存中缓存条目的最大数量
nearCacheMemory – 缓存条目使用的最大内存量

您可以指定 High-Units 或 Memory，并在任一情况下可选择指定 TTL。

近缓存条目的最小过期时间为 1/4 秒。这是为了确保元素过期尽可能高效。如果您尝试将 TTL 设置为更低的值，将会收到错误。

设置 Coherence

使用 Docker 在本地运行 Coherence：

docker run -d -p 1408:1408 -p 30000:30000 ghcr.io/oracle/coherence-ce:25.03.1

然后您可以使用 localhost:1408 与服务器交互。

在 Kubernetes 上安装 Coherence 的最简单方法是使用 Coherence Operator：

安装 Operator：

kubectl apply -f https://github.com/oracle/coherence-operator/releases/download/v3.5.2/coherence-operator.yaml

注意：将 v3.5.2 更改为最新版本。

这将把 Coherence operator 安装到 coherence 命名空间中。

创建 Coherence 集群 yaml my-cluster.yaml

apiVersion: coherence.oracle.com/v1
kind: Coherence
metadata:
  name: my-cluster
spec:
  coherence:
    management:
      enabled: true
  ports:
    - name: management
    - name: grpc
      port: 1408

应用 yaml

kubectl apply -f my-cluster.yaml

要与 Coherence 交互，使用以下命令查找服务：kubectl get svc 并查找名为 ‘*grpc’ 的服务。

NAME                    TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                                               AGE
kubernetes              ClusterIP   10.96.0.1      <none>        443/TCP                                               9m
my-cluster-grpc         ClusterIP   10.96.225.43   <none>        1408/TCP                                              7m3s
my-cluster-management   ClusterIP   10.96.41.6     <none>        30000/TCP                                             7m3s
my-cluster-sts          ClusterIP   None           <none>        7/TCP,7575/TCP,7574/TCP,6676/TCP,30000/TCP,1408/TCP   7m3s
my-cluster-wka          ClusterIP   None           <none>        7/TCP,7575/TCP,7574/TCP,6676/TCP                      7m3s

例如，如果使用上述示例安装，Coherence 主机地址将是：

my-cluster-grpc

10.11 - Couchbase

Couchbase 状态存储组件的详细信息

组件格式

要设置 Couchbase 状态存储，需创建一个类型为 state.couchbase 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.couchbase
  version: v1
  metadata:
  - name: couchbaseURL
    value: <REPLACE-WITH-URL> # 必填。示例："http://localhost:8091"
  - name: username
    value: <REPLACE-WITH-USERNAME> # 必填。
  - name: password
    value: <REPLACE-WITH-PASSWORD> # 必填。
  - name: bucketName
    value: <REPLACE-WITH-BUCKET> # 必填。

警告

上述示例将密钥作为纯文本字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规格元数据字段

Field	Required	Details	Example
couchbaseURL	Y	Couchbase 服务器的 URL	`"http://localhost:8091"`
username	Y	数据库用户名	`"user"`
password	Y	访问密码	`"password"`
bucketName	Y	写入的 bucket 名称	`"bucket"`

设置 Couchbase

您可以使用 Docker 在本地运行 Couchbase：

docker run -d --name db -p 8091-8094:8091-8094 -p 11210:11210 couchbase

然后您可以使用 localhost:8091 与服务器交互并开始服务器设置。

在 Kubernetes 上安装 Couchbase 的最简单方法是使用 Helm chart：

helm repo add couchbase https://couchbase-partners.github.io/helm-charts/
helm install couchbase/couchbase-operator
helm install couchbase/couchbase-cluster

10.12 - Etcd

Etcd 状态存储组件的详细信息

组件格式

要设置 Etcd 状态存储，需创建类型为 state.etcd 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.etcd
  # 支持 v1 和 v2。用户应默认使用 v2。
  # 从 v1 到 v2 没有迁移路径，详见下方的 `versioning`。
  version: v2
  metadata:
  - name: endpoints
    value: <CONNECTION STRING> # 必填。示例： 192.168.0.1:2379,192.168.0.2:2379,192.168.0.3:2379
  - name: keyPrefixPath
    value: <KEY PREFIX STRING> # 可选。默认值：""。示例："dapr"
  - name: tlsEnable
    value: <ENABLE TLS> # 可选。示例："false"
  - name: ca
    value: <CA> # 可选。当 tlsEnable 为 `true` 时必填。
  - name: cert
    value: <CERT> # 可选。当 tlsEnable 为 `true` 时必填。
  - name: key
    value: <KEY> # 可选。当 tlsEnable 为 `true` 时必填。
  # 如果您希望将 Etcd 用作 actor 的状态存储，请取消此注释（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例使用纯文本字符串存储密钥。建议按照此处所述使用密钥存储来管理密钥。

版本说明

Dapr 有 2 个版本的 Etcd 状态存储组件：v1 和 v2。建议使用 v2，因为 v1 已被弃用。

虽然 v1 和 v2 具有相同的元数据字段，但在使用 Dapr v1.12 的 Actor TTL 时，v1 会导致应用中的数据不一致。 v1 和 v2 不兼容，在现有的活跃 Etcd 集群和 keyPrefixPath 上没有从 v1 迁移到 v2 的数据迁移路径。如果您正在使用 v1，应继续使用 v1，直到您创建新的 Etcd 集群或使用不同的 keyPrefixPath。

规格元数据字段

字段	必填	说明	示例
`endpoints`	Y	Etcd 集群的连接字符串	`"192.168.0.1:2379,192.168.0.2:2379,192.168.0.3:2379"`
`keyPrefixPath`	N	Etcd 中的键前缀路径。默认无前缀。	`"dapr"`
`tlsEnable`	N	是否为与 Etcd 的连接启用 TLS。	`"false"`
`ca`	N	连接 Etcd 的 CA 证书，PEM 编码。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
`cert`	N	连接 Etcd 的 TLS 证书，PEM 编码。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN CERTIFICATE-----\nMIIDUTCC..."`
`key`	N	连接 Etcd 的 TLS 密钥，PEM 编码。可以是 `secretKeyRef` 以使用密钥引用。	`"-----BEGIN PRIVATE KEY-----\nMIIEpAIB..."`
`actorStateStore`	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

设置 Etcd

您可以使用 Docker Compose 在本地运行 Etcd 数据库。创建一个名为 docker-compose.yml 的新文件并添加以下内容作为示例：

version: '2'
services:
  etcd:
    image: gcr.io/etcd-development/etcd:v3.4.20
    ports:
      - "2379:2379"
    command: etcd --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://0.0.0.0:2379```

保存 docker-compose.yml 文件并运行以下命令启动 Etcd 服务器：

docker-compose up -d

这将在后台启动 Etcd 服务器并暴露默认的 Etcd 端口 2379。然后您可以使用 etcdctl 命令行客户端在 localhost:12379 上与服务器交互。例如：

etcdctl --endpoints=localhost:2379 put mykey myvalue

使用 Helm 在您的 Kubernetes 集群中快速创建 Etcd 实例。此方法需要安装 Helm。

遵循 Bitnami 说明开始在 Kubernetes 中设置 Etcd。

10.13 - GCP Firestore (Datastore 模式)

GCP Firestore 状态存储组件的详细信息

组件格式

要设置 GCP Firestore 状态存储，请创建一个类型为 state.gcp.firestore 的组件。有关如何创建和应用状态存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.gcp.firestore
  version: v1
  metadata:
  - name: project_id
    value: <REPLACE-WITH-PROJECT-ID> # 必填。
  - name: type 
    value: <REPLACE-WITH-CREDENTIALS-TYPE> # 必填。
  - name: endpoint # 可选。
    value: "http://localhost:8432"
  - name: private_key_id
    value: <REPLACE-WITH-PRIVATE-KEY-ID> # 可选。
  - name: private_key
    value: <REPLACE-WITH-PRIVATE-KEY> # 可选，但如果指定了 `private_key_id` 则为必填。
  - name: client_email
    value: <REPLACE-WITH-CLIENT-EMAIL> # 可选，但如果指定了 `private_key_id` 则为必填。
  - name: client_id
    value: <REPLACE-WITH-CLIENT-ID> # 可选，但如果指定了 `private_key_id` 则为必填。
  - name: auth_uri
    value: <REPLACE-WITH-AUTH-URI> # 可选。
  - name: token_uri
    value: <REPLACE-WITH-TOKEN-URI> # 可选。
  - name: auth_provider_x509_cert_url
    value: <REPLACE-WITH-AUTH-X509-CERT-URL> # 可选。
  - name: client_x509_cert_url
    value: <REPLACE-WITH-CLIENT-x509-CERT-URL> # 可选。
  - name: entity_kind
    value: <REPLACE-WITH-ENTITY-KIND> # 可选。默认值："DaprState"
  - name: noindex
    value: <REPLACE-WITH-BOOLEAN> # 可选。默认值："false"

警告

上面的示例将密钥作为纯字符串使用。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
project_id	Y	要使用的 GCP 项目 ID	`"project-id"`
type	Y	凭证类型	`"service_account"`
endpoint	N	组件要使用的 GCP 端点。仅用于本地开发（例如配合 GCP Datastore Emulator 使用）。针对 GCP 生产 API 运行时不需要 `endpoint`。	`"localhost:8432"`
private_key_id	N	要使用的私钥 ID	`"private-key-id"`
privateKey	N	如果使用显式凭证，此字段应包含服务账号 json 中的 `private_key` 字段	`-----BEGIN PRIVATE KEY-----MIIBVgIBADANBgkqhkiG9w0B`
client_email	N	客户端的电子邮件地址	`"eample@example.com"`
client_id	N	用于身份验证的客户端 ID 值	`"client-id"`
auth_uri	N	要使用的身份验证 URI	`"https://accounts.google.com/o/oauth2/auth"`
token_uri	N	用于查询 Auth token 的令牌 URI	`"https://oauth2.googleapis.com/token"`
auth_provider_x509_cert_url	N	身份验证提供者证书 URL	`"https://www.googleapis.com/oauth2/v1/certs"`
client_x509_cert_url	N	客户端证书 URL	`"https://www.googleapis.com/robot/v1/metadata/x509/x"`
entity_kind	N	Firestore 中的实体名称。默认为 `"DaprState"`	`"DaprState"`
noindex	N	是否禁用状态实体的索引。如果遇到 Firestore 索引大小限制，请使用此设置。默认为 `"false"`	`"true"`

GCP 凭证

由于 GCP Firestore 组件使用 GCP Go 客户端库，默认情况下它使用 Application Default Credentials 进行身份验证。这在使用客户端库向 GCP Cloud 服务进行身份验证指南中有详细说明。

设置 GCP Firestore

您可以使用 GCP Datastore 模拟器在本地运行，说明请参见此处。

然后您可以使用 http://localhost:8432 与服务器交互。

按照此处的说明在 Google Cloud 中开始设置 Firestore。

10.14 - HashiCorp Consul

HashiCorp Consul 状态存储组件的详细信息

组件格式

要设置 Hashicorp Consul 状态存储，请创建类型为 state.consul 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.consul
  version: v1
  metadata:
  - name: datacenter
    value: <REPLACE-WITH-DATA-CENTER> # 必需。例如：dc1
  - name: httpAddr
    value: <REPLACE-WITH-CONSUL-HTTP-ADDRESS> # 必需。例如："consul.default.svc.cluster.local:8500"
  - name: aclToken
    value: <REPLACE-WITH-ACL-TOKEN> # 可选。默认：""
  - name: scheme
    value: <REPLACE-WITH-SCHEME> # 可选。默认："http"
  - name: keyPrefixPath
    value: <REPLACE-WITH-TABLE> # 可选。默认：""

Warning

以上示例将密钥以纯文本字符串形式使用。建议使用密钥存储来管理密钥，具体方法见此处。

规范元数据字段

字段	必需	详情	示例
datacenter	Y	要使用的数据中心	`"dc1"`
httpAddr	Y	Consul 服务器的地址	`"consul.default.svc.cluster.local:8500"`
aclToken	N	每次请求的 ACL Token。默认为 `""`	`"token"`
scheme	N	Consul 服务器的 URI scheme。默认为 `"http"`	`"http"`
keyPrefixPath	N	Consul 中的键前缀路径。默认为 `""`	`"dapr"`

设置 HashiCorp Consul

你可以使用 Docker 在本地运行 Consul：

docker run -d --name=dev-consul -e CONSUL_BIND_INTERFACE=eth0 consul

然后可以使用 localhost:8500 与服务器交互。

在 Kubernetes 上安装 Consul 最简单的方法是使用 Helm chart：

helm install consul stable/consul

这会将 Consul 安装到 default 命名空间中。要与 Consul 交互，请使用以下命令查找服务：kubectl get svc consul。

例如，如果使用上述示例安装，Consul 主机地址将是：

consul.default.svc.cluster.local:8500

10.15 - Hazelcast

Hazelcast 状态存储组件的详细信息

创建 Dapr 组件

要设置 Hazelcast 状态存储，请创建类型为 state.hazelcast 的组件。有关如何创建和应用状态存储配置，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.hazelcast
  version: v1
  metadata:
  - name: hazelcastServers
    value: <REPLACE-WITH-HOSTS> # Required. A comma delimited string of servers. Example: "hazelcast:3000,hazelcast2:3000"
  - name: hazelcastMap
    value: <REPLACE-WITH-MAP> # Required. Hazelcast map configuration.

Warning

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，具体操作请参阅此处。

规格元数据字段

Field	Required	Details	Example
hazelcastServers	Y	服务器列表，以逗号分隔	`"hazelcast:3000,hazelcast2:3000"`
hazelcastMap	Y	Hazelcast Map 配置	`"foo-map"`

设置 Hazelcast

您可以使用 Docker 在本地运行 Hazelcast：

docker run -e JAVA_OPTS="-Dhazelcast.local.publicAddress=127.0.0.1:5701" -p 5701:5701 hazelcast/hazelcast

然后可以使用 127.0.0.1:5701 与服务器进行交互。

在 Kubernetes 上安装 Hazelcast 最简单的方法是使用 Helm chart。

10.16 - In-memory

内存状态组件的详细文档

内存状态存储组件将状态维护在 Dapr 边车的内存中。这主要用于开发目的。状态不会在多个边车之间复制，并且当 Dapr 边车重启时会丢失。

组件格式

要设置内存状态存储，请创建一个类型为 state.in-memory 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.in-memory
  version: v1
  metadata: 
  # 如果您希望将 In-memory 用作 actor 的状态存储，请取消注释（可选）
  #- name: actorStateStore
  #  value: "true"

注意：虽然内存不需要任何特定元数据即可使组件工作，但 spec.metadata 是必需字段。

10.17 - JetStream KV

关于 JetStream KV 状态存储组件的详细信息

组件格式

要设置 JetStream KV 状态存储，需创建一个类型为 state.jetstream 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.jetstream
  version: v1
  metadata:
  - name: natsURL
    value: "nats://localhost:4222"
  - name: jwt
    value: "eyJhbGciOiJ...6yJV_adQssw5c" # 可选。用于去中心化 JWT 认证
  - name: seedKey
    value: "SUACS34K232O...5Z3POU7BNIL4Y" # 可选。用于去中心化 JWT 认证
  - name: bucket
    value: "<bucketName>"

警告

上述示例将密钥以纯字符串形式使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必需	详情	示例
natsURL	Y	NATS 服务器地址 URL	“`nats://localhost:4222`”
jwt	N	NATS 去中心化认证 JWT	“`eyJhbGciOiJ...6yJV_adQssw5c`”
seedKey	N	NATS 去中心化认证种子密钥	“`SUACS34K232O...5Z3POU7BNIL4Y`”
bucket	Y	JetStream KV 存储桶名称	`"<bucketName>"`

创建 NATS 服务器

你可以使用 Docker 在本地运行启用了 JetStream 的 NATS 服务器：

docker run -d -p 4222:4222 nats:latest -js

然后可以使用客户端端口与服务器交互：localhost:4222。

使用 helm 在 Kubernetes 上安装 NATS JetStream：

helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install my-nats nats/nats

这会在 default 命名空间中安装一个单节点 NATS 服务器。要与 NATS 交互，可以使用以下命令查找服务：kubectl get svc my-nats。

创建 JetStream KV 存储桶

需要创建一个键值存储桶，这可以通过 NATS CLI 轻松完成。

nats kv add <bucketName>

10.18 - Memcached

Memcached 状态存储组件的详细信息

组件格式

要设置 Memcached 状态存储，请创建一个类型为 state.memcached 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.memcached
  version: v1
  metadata:
  - name: hosts
    value: <REPLACE-WITH-COMMA-DELIMITED-ENDPOINTS> # 必填。示例："memcached.default.svc.cluster.local:11211"
  - name: maxIdleConnections
    value: <REPLACE-WITH-MAX-IDLE-CONNECTIONS> # 可选。默认："2"
  - name: timeout
    value: <REPLACE-WITH-TIMEOUT> # 可选。默认："1000"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的说明使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
hosts	Y	以逗号分隔的端点	`"memcached.default.svc.cluster.local:11211"`
maxIdleConnections	N	空闲连接的最大数量。默认为 `"2"`	`"3"`
timeout	N	调用的超时时间（毫秒）。默认为 `"1000"`	`"1000"`

设置 Memcached

你可以使用 Docker 在本地运行 Memcached：

docker run --name my-memcache -d memcached

然后你可以使用 localhost:11211 与服务器交互。

在 Kubernetes 上安装 Memcached 最简单的方法是使用 Helm chart：

helm install memcached stable/memcached

这会将 Memcached 安装到 default 命名空间中。要与 Memcached 交互，使用以下命令查找服务：kubectl get svc memcached。

例如，如果使用上述示例安装，Memcached 主机地址将是：

memcached.default.svc.cluster.local:11211

10.19 - Microsoft SQL Server & Azure SQL

Microsoft SQL Server 状态存储组件的详细信息

Note

这是 Sql Server 状态存储组件的 v2 版本，支持 Dapr 工作流。建议新应用使用 v2 版本。

Sql Server v2 状态存储组件与 v1 组件不兼容，两个组件之间无法迁移数据。

目前没有弃用 v1 组件的计划。

组件格式

此状态存储组件可用于 Microsoft SQL Server 和 Azure SQL。

要设置此状态存储，请创建类型为 state.sqlserver 的组件。有关如何创建和应用状态存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.sqlserver
  version: v2
  metadata:
    # 使用 SQL Server 凭据进行身份验证
    - name: connectionString
      value: |
        Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;

    # 使用 Microsoft Entra ID 进行身份验证（仅限 Azure SQL）
    # "useAzureAD" 必须设置为 "true"
    - name: useAzureAD
      value: true
    # Azure SQL 数据库的连接字符串或 URL，可选包含数据库名称
    - name: connectionString
      value: |
        sqlserver://myServerName.database.windows.net:1433?database=myDataBase

    # 其他可选字段（列出默认值）
    - name: tableName
      value: "state"
    - name: metadataTableName
      value: "dapr_metadata"
    - name: schema
      value: "dbo"
    - name: keyType
      value: "string"
    - name: keyLength
      value: "200"
    - name: indexedProperties
      value: ""
    - name: cleanupIntervalInSeconds
      value: "3600"
   # 如果希望将 Microsoft SQL Server 用作 actor 的状态存储，请取消注释此行（可选）
   #- name: actorStateStore
   #  value: "true"

Warning

上面的示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，如此处所述。

如果希望将 SQL Server用作 actor 状态存储，请在元数据中添加以下内容：

  - name: actorStateStore
    value: "true"

规范元数据字段

使用 SQL Server 凭据进行身份验证

使用 SQL Server 凭据进行身份验证时，以下元数据选项是必需的。SQL Server 和 Azure SQL 都支持此方式。

字段	必需	详情	示例
`connectionString`	Y	用于连接的连接字符串。如果连接字符串包含数据库，则该数据库必须已存在。否则，如果省略数据库，将创建名为 “Dapr” 的默认数据库。	`"Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"`

使用 Microsoft Entra ID 进行身份验证

仅 Azure SQL 支持使用 Microsoft Entra ID 进行身份验证。可以使用 Dapr 支持的所有身份验证方法，包括客户端凭据（“服务主体”）和托管标识。

字段	必需	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以使组件能够从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	Azure SQL 数据库的连接字符串或 URL，不包含凭据。如果连接字符串包含数据库，则该数据库必须已存在。否则，如果省略数据库，将创建名为 “Dapr” 的默认数据库。	`"sqlserver://myServerName.database.windows.net:1433?database=myDataBase"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-47e1-b4d5-65447fdd542b"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-4ba2-a905-acd4d3f8f08b"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3XG7zVZK3/vl/a2NSB+a1zXLa8RnMum/IgD0E"`

其他元数据选项

字段	必需	详情	示例
`tableName`	N	要使用的表名。字母数字和下划线。默认为 `"state"`	`"table_name"`
`metadataTableName`	N	Dapr 用于存储少量元数据属性的表的名称。默认为 `dapr_metadata`。	`"dapr_metadata"`
`keyType`	N	使用的键类型。支持的值：`"string"`（默认）、`"uuid"`、`"integer"`。	`"string"`
`keyLength`	N	键的最大长度。如果 “keyType” 不是 `string`，则忽略此项。默认为 `"200"`	`"200"`
`schema`	N	要使用的架构。默认为 `"dbo"`	`"dapr"`,`"dbo"`
`indexedProperties`	N	索引属性列表，作为包含 JSON 文档的字符串。	`'[{"column": "transactionid", "property": "id", "type": "int"}, {"column": "customerid", "property": "customer", "type": "nvarchar(100)"}]'`
`actorStateStore`	N	指示 Dapr 应为 actor 状态存储配置此组件（更多信息）。	`"true"`
`cleanupIntervalInSeconds`	N	清理过期 TTL 行的间隔（以秒为单位）。默认：`"3600"`（即 1 小时）。将此值设置为 <=0 会禁用定期清理。	`"1800"`, `"-1"`

创建 Microsoft SQL Server/Azure SQL 实例

按照说明从 Azure 文档中了解如何创建 SQL 数据库。数据库必须先创建，Dapr 才能使用它。

为了将 SQL Server 设置为状态存储，您需要以下属性：

连接字符串：SQL Server 连接字符串。例如：server=localhost;user id=sa;password=your-password;port=1433;database=mydatabase;
架构：要使用的数据库架构（默认=dbo）。如果不存在，将创建该架构
表名：数据库表名。如果不存在，将创建该表
索引属性：来自 json 数据的可选属性，将被索引并作为单独的列持久化

创建专用用户

当使用专用用户（非 sa）连接时，用户需要这些授权 - 即使用户是所需数据库架构的所有者：

CREATE TABLE
CREATE TYPE

TTL 和清理

此状态存储支持使用 Dapr 存储的记录的生存时间（TTL）。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应在多少秒后被视为"过期"。

由于 SQL Server 没有内置的 TTL 支持，Dapr 通过在状态表中添加一列来实现此功能，指示数据何时应被视为"过期"。“过期"记录不会返回给调用者，即使它们仍物理存储在数据库中。后台"垃圾收集器"会定期扫描状态表中的过期行并删除它们。

您可以使用 cleanupIntervalInSeconds 元数据属性设置过期记录的删除间隔，默认为 3600 秒（即 1 小时）。

较长的间隔需要对过期行进行不太频繁的扫描，但可能需要存储过期记录更长时间，从而可能需要更多存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupIntervalInSeconds 设置为较小的值 - 例如，300（300 秒，或 5 分钟）。
如果您不打算将 TTL 与 Dapr 和 SQL Server 状态存储一起使用，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

状态存储在 ExpireDate 列上没有索引，这意味着每次清理操作都必须执行全表扫描。如果您打算向包含大量使用 TTL 的记录的表写入数据，您应该考虑在 ExpireDate 列上创建索引。索引使查询更快，但使用更多存储空间并略微减慢写入速度。

CREATE CLUSTERED INDEX expiredate_idx ON state(ExpireDate ASC)

高级

v1 和 v2 之间的区别

Sqlserver 状态存储 v1 在 Dapr 1.5 中引入。预先存在的 v1 仍然可用，并未被弃用。

在 v2 组件中，表模式已更改，目标是完全支持工作流。最值得注意的是，Dapr 存储的值现在属于 VARBINARY 类型，这允许工作流正确地存储数据。
然而，由于此更改，v2 组件不支持 Dapr 状态存储查询 API。

由于这些更改，v1 和 v2 组件无法从同一个表读取或写入数据。也无法在组件的两个版本之间迁移数据。

10.20 - Microsoft SQL Server & Azure SQL

Microsoft SQL Server 状态存储组件的详细信息

组件格式

此状态存储组件可与 Microsoft SQL Server 和 Azure SQL 一起使用。

要设置此状态存储，请创建类型为 state.sqlserver 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.sqlserver
  version: v1
  metadata:
    # 使用 SQL Server 凭据进行身份验证
    - name: connectionString
      value: |
        Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;

    # 使用 Microsoft Entra ID 进行身份验证（仅限 Azure SQL）
    # "useAzureAD" 需要设置为 "true"
    - name: useAzureAD
      value: true
    # Azure SQL 数据库的连接字符串或 URL，可选择包含数据库
    - name: connectionString
      value: |
        sqlserver://myServerName.database.windows.net:1433?database=myDataBase

    # 其他可选字段（列出默认值）
    - name: tableName
      value: "state"
    - name: metadataTableName
      value: "dapr_metadata"
    - name: schema
      value: "dbo"
    - name: keyType
      value: "string"
    - name: keyLength
      value: "200"
    - name: indexedProperties
      value: ""
    - name: cleanupIntervalInSeconds
      value: "3600"
   # 如果您希望将 Microsoft SQL Server 用作 actor 的状态存储，请取消注释此行（可选）
   #- name: actorStateStore
   #  value: "true"

警告

上面的示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

如果您希望将 SQL server 用作 actor 状态存储，请在元数据中附加以下内容：

  - name: actorStateStore
    value: "true"

规范元数据字段

使用 SQL Server 凭据进行身份验证

以下元数据选项是使用 SQL Server 凭据进行身份验证必需的。SQL Server 和 Azure SQL 都支持此功能。

字段	必填	详情	示例
`connectionString`	Y	用于连接的连接字符串。如果连接字符串包含数据库，则该数据库必须已存在。否则，如果省略数据库，则会创建名为 “Dapr” 的默认数据库。	`"Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"`

使用 Microsoft Entra ID 进行身份验证

仅 Azure SQL 支持使用 Microsoft Entra ID 进行身份验证。可以使用 Dapr 支持的所有身份验证方法，包括客户端凭据(“服务主体”)和托管标识。

字段	必填	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以使组件能够从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	Azure SQL 数据库的连接字符串或 URL，不带凭据。如果连接字符串包含数据库，则该数据库必须已存在。否则，如果省略数据库，则会创建名为 “Dapr” 的默认数据库。	`"sqlserver://myServerName.database.windows.net:1433?database=myDataBase"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-47e1-b4d5-65447fdd542b"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-4ba2-a905-acd4d3f8f08b"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3XG7zVZK3/vl/a2NSB+a1zXLa8RnMum/IgD0E"`

其他元数据选项

字段	必填	详情	示例
`tableName`	N	要使用的表的名称。字母数字和下划线。默认为 `"state"`	`"table_name"`
`metadataTableName`	N	Dapr 用于存储少量元数据属性的表的名称。默认为 `dapr_metadata`。	`"dapr_metadata"`
`keyType`	N	使用的键类型。支持的值：`"string"`（默认）、`"uuid"`、`"integer"`。	`"string"`
`keyLength`	N	键的最大长度。如果 “keyType” 不是 `string`，则忽略此项。默认为 `"200"`	`"200"`
`schema`	N	要使用的架构。默认为 `"dbo"`	`"dapr"`、`"dbo"`
`indexedProperties`	N	索引属性列表，以包含 JSON 文档的字符串形式提供。	`'[{"column": "transactionid", "property": "id", "type": "int"}, {"column": "customerid", "property": "customer", "type": "nvarchar(100)"}]'`
`actorStateStore`	N	指示 Dapr 应为 actor 状态存储配置此组件（[更多信息](https://docs.dapr.io/zh-hans/reference/api/state_api/#configuring-state-store-for-actors））。	`"true"`
`cleanupIntervalInSeconds`	N	清理过期 TTL 行的间隔（秒）。默认：`"3600"`（即 1 小时）。将此值设置为 <=0 会禁用定期清理。	`"1800"`、`"-1"`

创建 Microsoft SQL Server/Azure SQL 实例

按照说明从 Azure 文档中了解如何创建 SQL 数据库。数据库必须在 Dapr 使用它之前创建。

为了将 SQL Server 设置为状态存储，您需要以下属性：

连接字符串：SQL Server 连接字符串。例如：server=localhost;user id=sa;password=your-password;port=1433;database=mydatabase;
架构：要使用的数据库架构（默认=dbo）。如果不存在则创建
表名称：数据库表名称。如果不存在则创建
索引属性：来自 json 数据的可选属性，将被索引并作为单独的列持久化

创建专用用户

当使用专用用户（不是 sa）连接时，即使用户是所需数据库架构的所有者，也需要为用户授予以下授权：

CREATE TABLE
CREATE TYPE

TTL 和清理

此状态存储支持使用 Dapr 存储的记录的 Time-To-Live (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应该在多少秒后被视为"过期"。

由于 SQL Server 没有内置的 TTL 支持，Dapr 通过在状态表中添加一列来指示数据何时应被视为"过期"来实现此功能。“过期"记录不会返回给调用者，即使它们仍然物理存储在数据库中。后台"垃圾回收器"定期扫描状态表中的过期行并删除它们。

您可以使用 cleanupIntervalInSeconds 元数据属性设置删除过期记录的间隔，该属性默认为 3600 秒（即 1 小时）。

较长的间隔需要较少的过期行扫描频率，但可能需要存储过期记录更长时间，从而可能需要更多的存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupIntervalInSeconds 设置为较小的值 - 例如，300（300 秒，或 5 分钟）。
如果您不打算将 TTL 与 Dapr 和 SQL Server 状态存储一起使用，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

状态存储在 ExpireDate 列上没有索引，这意味着每次清理操作都必须执行全表扫描。如果您打算向使用 TTL 的大量记录的表写入数据，您应该考虑在 ExpireDate 列上创建索引。索引使查询更快，但使用更多的存储空间并稍微降低写入速度。

CREATE CLUSTERED INDEX expiredate_idx ON state(ExpireDate ASC)

10.21 - MongoDB

MongoDB 状态存储组件的详细信息

组件格式

要设置 MongoDB 状态存储，请创建类型为 state.mongodb 的组件。请参阅此指南以了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.mongodb
  version: v1
  metadata:
  - name: server
    value: <REPLACE-WITH-SERVER> # 除非设置了 "host" 字段，否则必填。示例："server.example.com"
  - name: host
    value: <REPLACE-WITH-HOST> # 除非设置了 "server" 字段，否则必填。示例："mongo-mongodb.default.svc.cluster.local:27017"
  - name: username
    value: <REPLACE-WITH-USERNAME> # 可选。示例："admin"
  - name: password
    value: <REPLACE-WITH-PASSWORD> # 可选。
  - name: databaseName
    value: <REPLACE-WITH-DATABASE-NAME> # 可选。默认值："daprStore"
  - name: collectionName
    value: <REPLACE-WITH-COLLECTION-NAME> # 可选。默认值："daprCollection"
  - name: writeConcern
    value: <REPLACE-WITH-WRITE-CONCERN> # 可选。
  - name: readConcern
    value: <REPLACE-WITH-READ-CONCERN> # 可选。
  - name: operationTimeout
    value: <REPLACE-WITH-OPERATION-TIMEOUT> # 可选。默认值："5s"
  - name: params
    value: <REPLACE-WITH-ADDITIONAL-PARAMETERS> # 可选。示例："?authSource=daprStore&ssl=true"
  # 如果希望将 MongoDB 作为 actor 的状态存储，请取消注释（可选）
  #- name: actorStateStore
  #  value: "true"

Warning

上述示例将密钥作为纯文本字符串使用。建议按照此处的描述使用密钥存储。

Actor 状态存储和事务支持

当用作 actor 状态存储或利用事务时，MongoDB 必须在副本集中运行。

如果希望将 MongoDB 用作 actor 存储，请在组件 YAML 中添加此元数据选项：

  - name: actorStateStore
    value: "true"

规格元数据字段

字段	必填	详情	示例
server	Y¹	使用 DNS SRV 记录时要连接的服务器	`"server.example.com"`
host	Y¹	要连接的主机	`"mongo-mongodb.default.svc.cluster.local:27017"`
username	N	连接用户的用户名（与 `host` 结合使用时适用）	`"admin"`
password	N	用户的密码（与 `host` 结合使用时适用）	`"password"`
databaseName	N	要使用的数据库的名称。默认为 `"daprStore"`	`"daprStore"`
collectionName	N	要使用的集合的名称。默认为 `"daprCollection"`	`"daprCollection"`
writeConcern	N	要使用的写入关注点	`"majority"`
readConcern	N	要使用的读取关注点	`"majority"`, `"local"`,`"available"`, `"linearizable"`, `"snapshot"`
operationTimeout	N	操作的超时时间。默认为 `"5s"`	`"5s"`
params	N²	要使用的附加参数	`"?authSource=daprStore&ssl=true"`
actorStateStore	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

^[1] server 和 host 字段互斥。如果两者都未设置或同时设置，Dapr 将返回错误。

^[2] params 字段接受一个查询字符串，将连接特定选项指定为 <name>=<value> 对，用 & 分隔并以 ? 为前缀。例如，要使用 “daprStore” 数据库作为身份验证数据库并在连接中启用 SSL/TLS，请将 params 指定为 ?authSource=daprStore&ssl=true。有关可用选项及其用例的列表，请参阅 mongodb 手册。

设置 MongoDB

您可以使用 Docker 在本地运行单个 MongoDB 实例：

docker run --name some-mongo -d -p 27017:27017 mongo

然后可以通过 localhost:27017 与服务器交互。如果您在组件定义中没有指定 databaseName 值，请确保创建一个名为 daprStore 的数据库。

为了将 MongoDB 状态存储用于事务和 actor 状态存储，您需要以副本集的方式运行 MongoDB。有关使用 Docker 创建三节点副本集的方法，请参阅官方文档。

您可以使用 Bitnami 打包的 Helm chart 在 Kubernetes 上方便地安装 MongoDB。请参阅 Helm chart 的文档以部署 MongoDB，包括作为独立服务器和使用副本集（使用事务和 actor 所必需）。这会将 MongoDB 安装到 default 命名空间。要与服务进行交互，可以使用以下命令：kubectl get svc mongo-mongodb。例如，如果使用上面的 Helm 默认设置进行安装，MongoDB 主机地址将是： mongo-mongodb.default.svc.cluster.local:27017 按照屏幕上的说明获取 MongoDB 的 root 密码。默认情况下，用户名通常为 admin。

TTLs 和清理

此状态存储支持为 Dapr 存储的记录设置生存时间（TTL）。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应被视为"过期"的时间。

10.22 - MySQL & MariaDB

MySQL 状态存储组件的详细信息

组件格式

MySQL 状态存储组件允许连接到 MySQL 和 MariaDB 数据库。在本文档中，我们使用 “MySQL” 来指代这两种数据库。

要设置 MySQL 状态存储，请创建一个类型为 state.mysql 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.mysql
  version: v1
  metadata:
  - name: connectionString
    value: "<CONNECTION STRING>"
  - name: schemaName
    value: "<SCHEMA NAME>"
  - name: tableName
    value: "<TABLE NAME>"
  - name: timeoutInSeconds
    value: "30"
  - name: pemPath # 如果未提供 pemContents 则必需。Pem 文件的路径。
    value: "<PEM PATH>"
  - name: pemContents # 如果未提供 pemPath 则必需。Pem 值。
    value: "<PEM CONTENTS>"    
# 如果您希望将 MySQL & MariaDB 用作 actor 的状态存储，请取消此注释（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

如果您希望将 MySQL 用作 actor 存储，请在 yaml 中添加以下内容。

  - name: actorStateStore
    value: "true"

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	连接到 MySQL 的连接字符串。不要将 schema 添加到连接字符串中	非 SSL 连接：`"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true"`，强制 SSL 连接： `"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true&tls=custom"`
`schemaName`	N	要使用的 schema 名称。如果 schema 不存在将创建。默认为 `"dapr_state_store"`	`"custom_schema"`，`"dapr_schema"`
`tableName`	N	要使用的表名称。如果表不存在将创建。默认为 `"state"`	`"table_name"`，`"dapr_state"`
`timeoutInSeconds`	N	所有数据库操作的超时时间。默认为 `20`	`30`
`pemPath`	N	用于强制 SSL 连接的 PEM 文件的完整路径，如果未提供 pemContents 则必需。不能在 K8s 环境中使用	`"/path/to/file.pem"`，`"C:\path\to\file.pem"`
`pemContents`	N	用于强制 SSL 连接的 PEM 文件内容，如果未提供 pemPath 则必需。可在 K8s 环境中使用	`"pem value"`
`cleanupIntervalInSeconds`	N	清理过期 TTL 行的间隔（秒）。默认：`3600`（即 1 小时）。将此值设置为 <=0 将禁用定期清理。	`1800`，`-1`
`actorStateStore`	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`，`"false"`

设置 MySQL

Dapr 可以使用任何 MySQL 实例——容器化的、在本地开发机器上运行的，或托管云服务。

运行一个 MySQL 实例。您可以使用以下命令在 Docker CE 中运行本地 MySQL 实例：

此示例未描述生产配置，因为它以纯文本形式设置密码，并且用户名保留为 MySQL 默认值 “root”。

docker run --name dapr-mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest

我们可以使用 Helm 在 Kubernetes 集群中快速创建 MySQL 实例。此方法需要安装 Helm。

将 MySQL 安装到您的集群中。

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install dapr-mysql bitnami/mysql

运行 kubectl get pods 查看集群中现在正在运行的 MySQL 容器。
接下来，我们将获取密码，根据我们使用的操作系统，密码的获取方式略有不同：
- Windows：运行 [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($(kubectl get secret --namespace default dapr-mysql -o jsonpath="{.data.mysql-root-password}"))) 并复制输出的密码。
- Linux/MacOS：运行 kubectl get secret --namespace default dapr-mysql -o jsonpath="{.data.mysql-root-password}" | base64 --decode 并复制输出的密码。
使用密码您可以构建连接字符串。

Azure MySQL

如果您使用 Azure 上的 MySQL，请参阅 Azure 关于 SSL 数据库连接的文档，了解如何下载所需证书的信息。

AWS MySQL

GCP MySQL

非 SSL 连接

将 <CONNECTION STRING> 值替换为您的连接字符串。连接字符串是标准的 MySQL 连接字符串。例如，"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true"。

强制 SSL 连接

如果您的服务器需要 SSL，连接字符串必须以 &tls=custom 结尾，例如，"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true&tls=custom"。您必须将 <PEM PATH> 替换为 PEM 文件的完整路径。与 MySQL 的连接需要最低 1.2 版本的 TLS。

TTL 和清理

此状态存储支持 Dapr 存储记录的 Time-To-Live (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以指示何时应将数据视为"过期"。

由于 MySQL 没有对 TTL 的内置支持，这是通过在状态表中添加一列来实现的，该列指示数据何时被视为"过期"。被视为"过期"的记录不会返回给调用者，即使它们仍然物理存储在数据库中。后台"垃圾收集器"会定期扫描状态表中的过期行并将其删除。

删除过期记录的间隔是通过 cleanupIntervalInSeconds 元数据属性设置的，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频率地扫描过期行，但可能需要存储过期记录更长的时间，可能需要更多的存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupIntervalInSeconds 设置为较小的值，例如 300（300 秒，或 5 分钟）。
如果您不计划对 Dapr 和 MySQL 状态存储使用 TTL，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

10.23 - OCI 对象存储

OCI 对象存储状态存储组件的详细信息

组件格式

要设置 OCI 对象存储状态存储，请创建类型为 state.oci.objectstorage 的组件。有关如何创建和应用状态存储配置，请参阅此指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.oci.objectstorage
  version: v1
  metadata:
 - name: instancePrincipalAuthentication
   value: <"true" or "false">  # 可选。默认值："false" 
 - name: configFileAuthentication
   value: <"true" or "false">  # 可选。默认值："false" 。当 instancePrincipalAuthentication == "true" 时不使用 
 - name: configFilePath
   value: <REPLACE-WITH-FULL-QUALIFIED-PATH-OF-CONFIG-FILE>  # 可选。无默认值。仅在 configFileAuthentication == "true" 时使用 
 - name: configFileProfile
   value: <REPLACE-WITH-NAME-OF-PROFILE-IN-CONFIG-FILE>  # 可选。默认值："DEFAULT" 。仅在 configFileAuthentication == "true" 时使用 
 - name: tenancyOCID
   value: <REPLACE-WITH-TENANCY-OCID>  # 当 configFileAuthentication == "true" 或 instancePrincipalAuthentication == "true" 时不使用 
 - name: userOCID
   value: <REPLACE-WITH-USER-OCID>  # 当 configFileAuthentication == "true" 或 instancePrincipalAuthentication == "true" 时不使用 
 - name: fingerPrint
   value: <REPLACE-WITH-FINGERPRINT>  # 当 configFileAuthentication == "true" 或 instancePrincipalAuthentication == "true" 时不使用 
 - name: privateKey  # 当 configFileAuthentication == "true" 或 instancePrincipalAuthentication == "true" 时不使用 
   value: |
          -----BEGIN RSA PRIVATE KEY-----
          REPLACE-WITH-PRIVATE-KEY-AS-IN-PEM-FILE
          -----END RSA PRIVATE KEY-----    
 - name: region
   value: <REPLACE-WITH-OCI-REGION>  # 当 configFileAuthentication == "true" 或 instancePrincipalAuthentication == "true" 时不使用 
 - name: bucketName
	 value: <REPLACE-WITH-BUCKET-NAME>
 - name: compartmentOCID
   value: <REPLACE-WITH-COMPARTMENT-OCID>

警告

上述示例将密钥作为纯文本字符串使用。建议使用密钥存储来管理密钥，具体说明参见此处。

规范元数据字段

字段	必填	详情	示例
instancePrincipalAuthentication	N	布尔值，指示是否使用基于实例主体（instance principal）的身份验证。默认值：`"false"`	`"true"` 或 `"false"` 。
configFileAuthentication	N	布尔值，指示是否通过配置文件提供身份凭据详细信息。默认值：`"false"` 当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"true"` 或 `"false"` 。
configFilePath	N	OCI 配置文件的完整路径名。不存在默认值。当 instancePrincipalAuthentication 为 true 时不使用。注意：不支持 ~/ 前缀。	`"/home/apps/configuration-files/myOCIConfig.txt"`。
configFileProfile	N	配置文件中要使用的配置文件（profile）名称。默认值：`"DEFAULT"` 当 instancePrincipalAuthentication 为 true 时不使用。	`"DEFAULT"` 或 `"PRODUCTION"` 。
tenancyOCID	Y	OCI 租户标识符。当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`。
userOCID	Y	OCI 账户的 OCID（此账户需要访问 OCI 对象存储的权限）。当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"`
fingerPrint	Y	公钥的指纹。当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"`
privateKey	Y	RSA 密钥对的私钥。当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"`
region	Y	OCI 区域。当 instancePrincipalAuthentication 为 true 时不需要也不使用。	`"us-ashburn-1"`
bucketName	Y	写入和读取（并在必要时创建）的存储桶的名称	`"application-state-store-bucket"`
compartmentOCID	Y	包含存储桶的区间（compartment）的 OCID	`"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"`

设置 OCI 对象存储

OCI 对象存储状态存储需要与 Oracle Cloud Infrastructure 进行交互。状态存储支持两种不同的身份验证方法。一种基于身份（用户或服务账户），另一种是利用授予运行应用程序工作负载的计算实例的权限的实例主体身份验证。注意：资源主体身份验证——用于非实例资源（如无服务器函数）——目前不支持。

在 Oracle Cloud Infrastructure 上运行的 Dapr 应用程序——在计算实例中或作为 Kubernetes 上的容器——可以利用实例主体身份验证。有关更多背景信息，请参阅 OCI 文档关于从实例调用 OCI 服务。简而言之：实例需要是动态组的成员，并且该动态组需要通过 IAM 策略获得与对象存储服务交互的权限。对于此类实例主体身份验证，将属性 instancePrincipalAuthentication 指定为 "true"。您不需要配置属性 tenancyOCID、userOCID、region、fingerPrint 和 privateKey——如果您为它们定义了值，这些将被忽略。

基于身份的身份验证通过一个 OCI 账户与 OCI 进行交互，该账户具有通过 OCI 对象存储在指定存储桶中创建、读取和删除对象的权限，并且如果未预先创建存储桶，则允许在指定区间中创建存储桶。OCI 文档描述了如何创建 OCI 账户。状态存储的交互使用公钥的指纹和为 OCI 账户生成的 RSA 密钥对的私钥进行。生成密钥对并获取所需信息的说明可在 OCI 文档中找到。

用于与 OCI 交互的身份和身份凭据的详细信息可以直接在 Dapr 组件属性文件中提供——使用属性 tenancyOCID、userOCID、fingerPrint、privateKey 和 region——或者可以从配置文件中提供，这是许多 OCI 相关工具（如 CLI 和 Terraform）和 SDK 的常见做法。在后一种情况下，必须通过属性 configFilePath 提供确切的文件名和完整路径。注意：路径中不支持 ~/ 前缀。配置文件可以包含多个配置文件（profile）；所需的配置文件可以通过属性 configFileProfile 指定。如果未提供值，则使用 DEFAULT 作为要使用的配置文件的名称。注意：如果找不到指定的配置文件，则使用 DEFAULT 配置文件（如果存在）。OCI SDK 文档提供了有关配置文件定义的详细信息。

如果您希望为 Dapr 创建要使用的存储桶，可以预先执行此操作。但是，对象存储状态提供程序将自动在指定区间中为您创建一个（如果它不存在）。

为了将 OCI 对象存储设置为状态存储，您需要以下属性：

instancePrincipalAuthentication：指示是否应使用基于实例主体的身份验证的标志。
configFileAuthentication：指示是否通过配置文件提供 OCI 身份凭据详细信息的标志。当 instancePrincipalAuthentication 为 true 时不使用。
configFilePath：OCI 配置文件的完整路径名。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 不为 true 时不使用。
configFileProfile：配置文件中要使用的配置文件（profile）名称。默认值："DEFAULT" 当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 不为 true 时不需要也不使用。当在配置文件中找不到指定的配置文件时，如果存在 DEFAULT 配置文件，则使用它。
tenancyOCID：OCI 云租户的标识符，状态将存储在其中。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
userOCID：状态存储组件用于连接到 OCI 的账户的标识符；这必须是在指定区间和存储桶中对 OCI 对象存储服务具有适当权限的账户。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
fingerPrint：为 userOCID 指示的账户生成的 RSA 密钥对中公钥的指纹。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
privateKey：为 userOCID 指示的账户生成的 RSA 密钥对中的私钥。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
region：OCI 区域——例如 us-ashburn-1、eu-amsterdam-1、ap-mumbai-1。当 instancePrincipalAuthentication 为 true 时不使用
bucketName：OCI 对象存储上将创建状态的存储桶名称。此存储桶在状态存储初始化时可能已存在，或将在状态存储初始化期间创建。请注意，存储桶名称在命名空间内是唯一的。
compartmentOCID：租户中区间的标识符，存储桶在其中存在或将被创建。

运行时会发生什么？

每个状态条目在 OCI 对象存储中都由一个对象表示。OCI 对象存储状态存储使用在对 Dapr API 的请求中提供的 key 属性来确定对象的名称。value 作为对象的（字面）内容存储。每个对象都被分配一个唯一的 ETag 值——每当它被创建或更新（即覆盖）时；这是 OCI 对象存储的本机行为。状态存储为它写入的每个对象分配一个元数据标签；该标签是 category，其值是 dapr-state-store。这允许识别为 Dapr 应用程序的状态而创建的对象。

例如，以下操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

创建以下对象：

存储桶	目录	对象名称	对象内容	元标签
components.yaml 中由 bucketName 指定	-（根目录）	nihilus	darth	category: dapr-state-store

Dapr 使用具有复合键的固定键方案在应用程序之间分区状态。对于一般状态，键格式为： App-ID||state key OCI 对象存储状态存储将第一个键段（用于 App-ID）映射到存储桶内的目录，使用 OCI 对象存储文档中描述的用于模拟目录结构的前缀和层次结构。

因此，以下操作（注意复合键）

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "myApplication||nihilus",
          "value": "darth"
        }
      ]'

将创建以下对象：

存储桶	目录	对象名称	对象内容	元标签
components.yaml 中由 bucketName 指定	myApplication	nihilus	darth	category: dapr-state-store

您将能够通过控制台、API、CLI 或 SDK 检查存储桶的内容来检查通过 OCI 对象存储状态存储存储的所有状态。通过直接访问存储桶，您可以准备在运行时作为状态提供给您的应用程序的状态。

生存时间和状态过期

OCI 对象存储状态存储支持 Dapr 的生存时间（TTL）逻辑，确保过期后无法检索状态。有关详细信息，请参阅有关设置状态生存时间的操作指南。

OCI 对象存储本身不支持生存时间设置。此组件中的实现使用放在为其指定了 TTL 的每个对象上的元数据标签。该标签称为 expiry-time-from-ttl，它包含 ISO 日期时间格式的字符串，带有基于 UTC 的过期时间。当通过调用 Get 检索状态时，此组件检查是否设置了 expiry-time-from-ttl，如果设置了，则检查它是否已过期。在这种情况下，不返回状态。

因此，以下操作（注意复合键）

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "temporary",
          "value": "ephemeral",
          "metadata": {"ttlInSeconds": "120"}}
        }
      ]'

创建以下对象：

存储桶	目录	对象名称	对象内容	元标签
components.yaml 中由 bucketName 指定	-	nihilus	darth	category: dapr-state-store , expiry-time-from-ttl: 2022-01-06T08:34:32

expiry-time-from-ttl 的确切值当然取决于状态创建的时间，并且将是该时间之后 120 秒。

请注意，此组件不会从状态存储中删除过期的状态。应用程序操作员可以决定运行定期作业以执行某种形式的垃圾回收，以显式删除所有具有时间戳已过去的 expiry-time-from-ttl 标签的状态。

并发性

OCI 对象存储状态并发性是通过使用 ETag 实现的。OCI 对象存储中的每个对象在创建或更新（即替换）时都会被分配一个唯一的 ETag。当此状态存储的 Set 和 Delete 请求指定 FirstWrite 并发策略时，请求需要提供要写入或删除的状态的实际 ETag 值，请求才能成功。

一致性

OCI 对象存储状态不支持事务。

查询

OCI 对象存储状态不支持查询 API。

10.24 - Oracle Database

Oracle Database 状态存储组件的详细信息

组件格式

创建一个组件属性 yaml 文件，例如命名为 oracle.yaml（但可以命名为任何名称），粘贴以下内容并将 <CONNECTION STRING> 值替换为你的连接字符串。连接字符串是一个标准的 Oracle Database 连接字符串，格式为："oracle://user/password@host:port/servicename"，例如 "oracle://demo:demo@localhost:1521/xe"。

如果你使用 Oracle Wallet 连接数据库，应该为 oracleWalletLocation 属性指定一个值，例如："/home/app/state/Wallet_daprDB/"；这应该指向本地文件系统目录，该目录包含从 Oracle Wallet 归档文件中提取的 cwallet.sso 文件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.oracledatabase
  version: v1
  metadata:
  - name: connectionString
    value: "<CONNECTION STRING>"
  - name: oracleWalletLocation
    value: "<FULL PATH TO DIRECTORY WITH ORACLE WALLET CONTENTS >"  # 可选，无默认值
  - name: tableName
    value: "<NAME OF DATABASE TABLE TO STORE STATE IN >" # 可选，默认为 STATE
  # 如果你想将 Oracle Database 用作 actor 的状态存储，请取消注释（可选）
  #- name: actorStateStore
  #  value: "true"

Warning

上述示例将 secret 作为纯字符串使用。建议按照此处的描述使用 secret store 来管理 secret。

规范元数据字段

Field	Required	Details	Example
connectionString	Y	Oracle Database 的连接字符串	例如 `"oracle://user/password@host:port/servicename"` 即 `"oracle://demo:demo@localhost:1521/xe"`，对于 Autonomous Database 则为 `"oracle://states_schema:State12345pw@adb.us-ashburn-1.oraclecloud.com:1522/k8j2agsqjsw_daprdb_low.adb.oraclecloud.com"`
oracleWalletLocation	N	Oracle Wallet 文件内容的位置（连接 OCI 上的 Autonomous Database 所需）	`"/home/app/state/Wallet_daprDB/"`
tableName	N	此状态存储实例记录数据的数据库表名称，默认为 `"STATE"`	`"MY_APP_STATE_STORE"`
actorStateStore	N	是否将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

运行时会发生什么？

当状态存储组件初始化时，它会连接到 Oracle Database 并检查是否存在与 tableName 指定名称相同的表。如果不存在，它会创建此表（包含 Key、Value、Binary_YN、ETag、Creation_Time、Update_Time、Expiration_time 列）。

每个状态条目由数据库表中的一条记录表示。请求中提供的 key 属性用于确定存储在 KEY 列中的对象的名称。value 作为对象的内容存储。二进制内容以 Base64 编码文本的形式存储。每个对象在创建或更新时都会被分配一个唯一的 ETag 值。

例如，以下操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

会在表 STATE 中创建以下记录：

KEY	VALUE	CREATION_TIME	BINARY_YN	ETAG
nihilus	darth	2022-02-14T22:11:00	N	79dfb504-5b27-43f6-950f-d55d5ae0894f

Dapr 使用固定 key 方案和组合键在应用程序之间分区状态。对于一般状态，key 格式为： App-ID||state key。Oracle Database 状态存储将此 key 完整映射到 KEY 列。

你可以轻松地使用 SQL 查询检查 tableName 表中存储的所有状态，例如 STATE 表。

生存时间和状态过期

Oracle Database 状态存储组件支持 Dapr 的生存时间逻辑，确保过期后无法检索状态。有关详细信息，请参阅关于设置状态生存时间的 How To。

Oracle Database 没有对生存时间设置的内置支持。此组件中的实现使用名为 EXPIRATION_TIME 的列来保存记录被视为过期之后的时间。只有在 Set 请求中指定了 TTL 时，才会设置此列中的值。它被计算为当前 UTC 时间戳加上 TTL 周期。当通过 Get 调用检索状态时，此组件会检查是否设置了 EXPIRATION_TIME，如果设置了，它会检查该时间是否已过去。在这种情况下，不返回任何状态。

以下操作：

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "temporary",
          "value": "ephemeral",
          "metadata": {"ttlInSeconds": "120"}}
        }
      ]'

创建以下对象：

KEY	VALUE	CREATION_TIME	EXPIRATION_TIME	BINARY_YN	ETAG
temporary	ephemeral	2022-03-31T22:11:00	2022-03-31T22:13:00	N	79dfb504-5b27-43f6-950f-d55d5ae0894f

其中 EXPIRATION_TIME 被设置为比 CREATION_TIME 晚 2 分钟（120 秒）的时间戳

请注意，过期状态不会被此组件从状态存储中删除。应用程序操作员可能会决定运行一个定期作业来执行某种形式的垃圾回收，以显式删除所有 EXPIRATION_TIME 在过去的记录。用于收集过期垃圾记录的 SQL 语句：

 delete dapr_state 
 where  expiration_time < SYS_EXTRACT_UTC(SYSTIMESTAMP);

并发

Oracle Database 状态存储中的并发是通过使用 ETag 实现的。在 Oracle Database 状态存储中记录的每条状态在创建或更新时都会被分配一个唯一的 ETag——一个存储在 ETag 列中的生成的唯一字符串。注意：当对现有记录执行 Set 操作时，UPDATE_TIME 列也会被更新。

只有当此状态存储的 Set 和 Delete 请求指定 FirstWrite 并发策略时，请求才需要提供要写入或删除的状态的实际 ETag 值，请求才能成功。如果指定了不同或没有并发策略，则不会对 ETag 值执行检查。

一致性

Oracle Database 状态存储支持事务。多个 Set 和 Delete 命令可以组合在一个请求中，该请求作为单个原子事务处理。

注意：简单的 Set 和 Delete 操作本身就是事务；当 Set 或 Delete 请求返回 HTTP-20X 结果时，数据库事务已成功提交。

查询

Oracle Database 状态存储目前不支持查询 API。

创建 Oracle Database 和用户模式

运行 Oracle Database 实例。你可以使用以下命令在 Docker CE 中运行 Oracle Database 的本地实例——或者当然使用现有的 Oracle Database：
```
docker run -d -p 1521:1521 -e ORACLE_PASSWORD=TheSuperSecret1509! gvenzl/oracle-xe
```
此示例未描述生产配置，因为它以纯文本形式为用户 SYS 和 SYSTEM 设置密码。
当命令的输出指示容器正在运行时，使用 docker ps 命令了解容器 id。然后使用以下命令启动 shell 会话：
```
docker exec -it <container id> /bin/bash
```
随后运行 SQL*Plus 客户端，以 SYS 用户身份连接到数据库：
```
sqlplus sys/TheSuperSecret1509! as sysdba
```
为状态数据创建数据库模式。创建一个新的用户模式——例如名为 dapr——用于存储状态数据。授予此用户（模式）创建表和在关联表空间中存储数据的权限。
要在 Oracle Database 中创建新的用户模式，请运行以下 SQL 命令：
```
create user dapr identified by DaprPassword4239 default tablespace users quota unlimited on users;
grant create session, create table to dapr;
```
（可选）创建用于存储状态记录的表。 Oracle Database 状态存储组件检查存储状态的表是否已存在于它连接的数据库用户模式中，如果不存在，它会创建该表。但是，除了让 Oracle Database 状态存储组件在运行时创建用于存储状态记录的表之外，你还可以提前创建表。这为你——或数据库的 DBA——提供对表的物理配置的更多控制。这也意味着你不必将创建表权限授予用户模式。
运行以下 DDL 语句以在 dapr 数据库用户模式中创建用于存储状态的表：
```
CREATE TABLE dapr_state (
		key varchar2(2000) NOT NULL PRIMARY KEY,
		value clob NOT NULL,
		binary_yn varchar2(1) NOT NULL,
		etag varchar2(50)  NOT NULL,
		creation_time TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL ,
		expiration_time TIMESTAMP WITH TIME ZONE NULL,
		update_time TIMESTAMP WITH TIME ZONE NULL
  )
```

在 Oracle Cloud Infrastructure 上创建免费（或付费）的自治事务处理（ATP）或 ADW（自治数据仓库）实例，如 OCI 永久免费自治数据库文档中所述。
你需要提供用户 ADMIN 的密码。你使用此帐户（至少最初）用于数据库管理活动。你可以在基于 Web 的 SQL Developer 工具、其桌面对应工具或许多数据库开发工具中的任何一个中工作。
为状态数据创建模式。在 Oracle Database 中创建一个新的用户模式用于存储状态数据——例如使用 ADMIN 帐户。授予这个新用户（模式）创建表和在关联表空间中存储数据的权限。
要在 Oracle Database 中创建新的用户模式，请运行以下 SQL 命令：
```
create user dapr identified by DaprPassword4239 default tablespace users quota unlimited on users;
grant create session, create table to dapr;
```
（可选）创建用于存储状态记录的表。 Oracle Database 状态存储组件检查存储状态的表是否已存在于它连接的数据库用户模式中，如果不存在，它会创建该表。但是，除了让 Oracle Database 状态存储组件在运行时创建用于存储状态记录的表之外，你还可以提前创建表。这为你——或数据库的 DBA——提供对表的物理配置的更多控制。这也意味着你不必将创建表权限授予用户模式。
运行以下 DDL 语句以在 dapr 数据库用户模式中创建用于存储状态的表：
```
CREATE TABLE dapr_state (
		key varchar2(2000) NOT NULL PRIMARY KEY,
		value clob NOT NULL,
		binary_yn varchar2(1) NOT NULL,
		etag varchar2(50)  NOT NULL,
		creation_time TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL ,
		expiration_time TIMESTAMP WITH TIME ZONE NULL,
		update_time TIMESTAMP WITH TIME ZONE NULL
  )
```

10.25 - PostgreSQL

PostgreSQL 状态存储组件的详细信息

注意

这是 PostgreSQL 状态存储组件的 v2 版本，在性能和可靠性方面进行了一些改进。建议新应用使用 v2 版本。

PostgreSQL v2 状态存储组件与 v1 组件不兼容，且数据无法在两个组件之间迁移。v2 组件不支持状态存储查询 API。

目前没有计划弃用 v1 组件。

此组件允许使用 PostgreSQL (Postgres) 作为 Dapr 的状态存储，使用 “v2” 组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.postgresql
  # 注意：设置 "version" 为 "v2" 是使用组件 v2 的必需项
  version: v2
  metadata:
    # 连接字符串
    - name: connectionString
      value: "<CONNECTION STRING>"
    # 单独的连接参数 - 可用于覆盖 connectionString 参数
    #- name: host
    #  value: "localhost"
    #- name: hostaddr
    #  value: "127.0.0.1"
    #- name: port
    #  value: "5432"
    #- name: database
    #  value: "my_db"
    #- name: user
    #  value: "postgres"
    #- name: password
    #  value: "example"
    #- name: sslRootCert
    #  value: "/path/to/ca.crt"
    # 数据库操作超时时间，作为 Go duration 或秒数（可选）
    #- name: timeout
    #  value: 20
    # 存储数据的表前缀（可选）
    #- name: tablePrefix
    #  value: ""
    # Dapr 用于存储元数据的表名称（可选）
    #- name: metadataTableName
    #  value: "dapr_metadata"
    # 清理过期行的时间间隔（秒）（可选）
    #- name: cleanupInterval
    #  value: "1h"
    # 此组件连接池的最大连接数（可选）
    #- name: maxConns
    #  value: 0
    # 连接的最大空闲时间，超过此时间后将关闭连接（可选）
    #- name: connectionMaxIdleTime
    #  value: 0
    # 控制执行查询的默认模式（可选）
    #- name: queryExecMode
    #  value: ""
    # 如果希望将 PostgreSQL 用作 actor 或工作流的状态存储，请取消注释（可选）
    #- name: actorStateStore
    #  value: "true"

警告

上述示例使用明文字符串作为密钥。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

使用连接字符串进行身份验证

以下元数据选项是使用 PostgreSQL 连接字符串进行身份验证的必需项。

字段	必需	详情	示例
`connectionString`	Y	PostgreSQL 数据库的连接字符串。有关如何定义连接字符串的信息，请参阅 PostgreSQL 数据库连接文档。	`"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`

使用单独的连接参数进行身份验证

除了使用连接字符串外，您还可以选择指定单独的连接参数。这些参数等同于标准 PostgreSQL 连接参数。

字段	必需	详情	示例
`host`	Y	PostgreSQL 服务器的主机名或 IP 地址	`"localhost"`
`hostaddr`	N	PostgreSQL 服务器的 IP 地址（host 的替代方案）	`"127.0.0.1"`
`port`	Y	PostgreSQL 服务器的端口号	`"5432"`
`database`	Y	要连接的数据库名称	`"my_db"`
`user`	Y	用于连接的 PostgreSQL 用户	`"postgres"`
`password`	Y	PostgreSQL 用户的密码	`"example"`
`sslRootCert`	N	SSL 根证书文件的路径	`"/path/to/ca.crt"`

注意

使用单独的连接参数时，这些参数将覆盖 connectionString 中存在的参数。

使用 Microsoft Entra ID 进行身份验证

Azure Database for PostgreSQL 支持使用 Microsoft Entra ID 进行身份验证。可以使用 Dapr 支持的所有身份验证方法，包括客户端凭据（“服务主体”）和托管标识。

字段	必需	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以启用组件从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含用户，对应于在 PostgreSQL 内部创建的映射到 Microsoft Entra ID 标识的用户名称。这通常是对应主体的名称（例如，Microsoft Entra ID 应用程序的名称）。此连接字符串不应包含任何密码。	`"host=mydb.postgres.database.azure.com user=myapplication port=5432 database=my_db sslmode=require"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-…"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-…"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

所有版本的 PostgreSQL 类型组件都支持使用 AWS IAM 进行身份验证。连接字符串中指定的用户必须是数据库中已存在的用户，并且是已授予 rds_iam 数据库角色的 AWS IAM 启用用户。身份验证基于 AWS 身份验证配置文件或提供的 AccessKey/SecretKey。 AWS 身份验证令牌将在其过期时间之前与 AWS 动态轮换。

字段	必需	详情	示例
`useAWSIAM`	Y	必须设置为 `true` 以启用组件从 AWS IAM 获取访问令牌。此身份验证方法仅适用于 AWS Relational Database Service 的 PostgreSQL 数据库。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。必须包含已存在的用户，对应于在 PostgreSQL 内部创建的映射到 AWS IAM 策略的用户名称。此连接字符串不应包含任何密码。请注意，数据库名字段在 AWS 中表示为 dbname。	`"host=mydb.postgres.database.aws.com user=myapplication port=5432 dbname=my_db sslmode=require"`
`awsRegion`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 起被弃用。请改用 ‘region’。部署 AWS Relational Database Service 的 AWS 区域。	`"us-east-1"`
`awsAccessKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 起被弃用。请改用 ‘accessKey’。与 IAM 账户关联的 AWS 访问密钥	`"AKIAIOSFODNN7EXAMPLE"`
`awsSecretKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 起被弃用。请改用 ‘secretKey’。与访问密钥关联的密钥	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`awsSessionToken`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 起被弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅当您使用临时安全凭证时才需要会话令牌。	`"TOKEN"`

其他元数据选项

字段	必需	详情	示例
`tablePrefix`	N	存储数据的表的前缀。可以选择性地将架构名称作为前缀，例如 `public.prefix_`	`"prefix_"`, `"public.prefix_"`
`metadataTableName`	N	Dapr 用于存储一些元数据属性的表的名称。默认为 `dapr_metadata`。可以选择性地将架构名称作为前缀，例如 `public.dapr_metadata`	`"dapr_metadata"`, `"public.dapr_metadata"`
`timeout`	N	数据库操作的超时时间，作为 Go duration。整数被解释为秒数。默认为 `20s`	`"30s"`, `30`
`cleanupInterval`	N	清理过期 TTL 行的时间间隔，作为 Go duration 或秒数。默认：`1h`（1 小时）。将此设置为 <= 0 的值将禁用定期清理。	`"30m"`, `1800`, `-1`
`maxConns`	N	此组件连接池的最大连接数。设置为 0 或更低以使用默认值，即 4 或 CPU 数量中的较大者。	`"4"`
`connectionMaxIdleTime`	N	未使用的连接在连接池中自动关闭前的最大空闲时间。默认情况下，没有值，这留给数据库驱动程序选择。	`"5m"`
`queryExecMode`	N	控制执行查询的默认模式。默认情况下，Dapr 使用扩展协议并自动准备和缓存预处理语句。然而，这可能与 PGBouncer 等代理不兼容。在这种情况下，最好使用 `exec` 或 `simple_protocol`。	`"simple_protocol"`
`actorStateStore`	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

设置 PostgreSQL

运行 PostgreSQL 实例。您可以使用以下命令在 Docker 中运行本地 PostgreSQL 实例：
```
docker run -p 5432:5432 -e POSTGRES_PASSWORD=example postgres
```
此示例未描述生产环境配置，因为它以纯文本设置密码，用户名保留为 PostgreSQL 默认的 “postgres”。
为状态数据创建数据库。
可以使用默认的 “postgres” 数据库，也可以创建一个新数据库来存储状态数据。
要在 PostgreSQL 中创建新数据库，请运行以下 SQL 命令：
```
CREATE DATABASE my_dapr;
```

高级

v1 和 v2 之间的差异

PostgreSQL 状态存储 v2 在 Dapr 1.13 中引入。现有的 v1 仍然可用，并未被弃用。

在 v2 组件中，表架构已进行了重大更改，旨在提高性能和可靠性。最值得注意的是，Dapr 存储的值现在为 BYTEA 类型，这允许更快的查询，并且在某些情况下比以前使用的 JSONB 列更节省空间。
然而，由于此更改，v2 组件不支持 Dapr 状态存储查询 API。

此外，在 v2 组件中，ETag 现在是随机 UUID，这确保了与其他 PostgreSQL 兼容数据库（如 CockroachDB）的更好兼容性。

由于这些更改，v1 和 v2 组件无法从同一个表读取或写入数据。在此阶段，也无法在两个版本的组件之间迁移数据。

以人类可读格式显示数据

PostgreSQL v2 组件将状态的值存储在 value 列中，该列的类型为 BYTEA。大多数 PostgreSQL 工具（包括 pgAdmin）将值视为二进制，默认情况下不会以人类可读的形式显示。

如果您想检查状态存储中的值，并且您知道它不是二进制数据（例如，JSON 数据），您可以使用如下查询以人类可读的形式显示值：

-- 将 "state" 替换为您环境中的状态表的名称
SELECT *, convert_from(value, 'utf-8') FROM state;

TTL 和清理

由于 PostgreSQL 没有内置的 TTL 支持，这是通过在状态表中添加一个列来实现的，该列指示数据何时应被视为"过期"。即使仍物理存储在数据库中，“过期"的记录也不会返回给调用方。后台"垃圾收集器"会定期扫描状态表中的过期行并删除它们。

您可以使用 cleanupInterval 元数据属性设置过期记录的删除时间间隔，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少的过期行扫描频率，但可能需要存储过期记录更长时间，可能需要更多的存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupInterval 设置为较小的值；例如，5m（5 分钟）。
如果您不计划将 TTL 与 Dapr 和 PostgreSQL 状态存储一起使用，您应该考虑将 cleanupInterval 设置为 <= 0 的值（例如，0 或 -1）以禁用定期清理并减少数据库的负载。

10.26 - PostgreSQL v1

关于 PostgreSQL v1 状态存储组件的详细信息

注意

从 Dapr 1.13 开始，您可以使用 PostgreSQL v2 状态存储组件，它在性能和可靠性方面进行了一些改进。 v2 组件与 v1 不兼容，并且数据无法在两个组件之间迁移。v2 组件不支持状态存储查询 API。

目前没有弃用 v1 组件的计划。

该组件允许使用 PostgreSQL (Postgres) 作为 Dapr 的状态存储，使用 “v1” 组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.postgresql
  version: v1
  metadata:
    # 连接字符串
    - name: connectionString
      value: "<CONNECTION STRING>"
    # 单独的连接参数 - 可用于覆盖 connectionString 参数
    #- name: host
    #  value: "localhost"
    #- name: hostaddr
    #  value: "127.0.0.1"
    #- name: port
    #  value: "5432"
    #- name: database
    #  value: "my_db"
    #- name: user
    #  value: "postgres"
    #- name: password
    #  value: "example"
    #- name: sslRootCert
    #  value: "/path/to/ca.crt"
    # 数据库操作超时时间，以 Go duration 或秒数表示（可选）
    #- name: timeout
    #  value: 20
    # 用于存储状态的表名（可选）
    #- name: tableName
    #  value: "state"
    # 用于存储 Dapr 元数据的表名（可选）
    #- name: metadataTableName
    #  value: "dapr_metadata"
    # 清理间隔（秒），用于删除过期的行（可选）
    #- name: cleanupInterval
    #  value: "1h"
    # 该组件池化的最大连接数（可选）
    #- name: maxConns
    #  value: 0
    # 连接关闭前的最大空闲时间（可选）
    #- name: connectionMaxIdleTime
    #  value: 0
    # 控制执行查询的默认模式（可选）
    #- name: queryExecMode
    #  value: ""
    # 如果您希望将 PostgreSQL 用作 actor 或工作流的状态存储，请取消注释（可选）
    #- name: actorStateStore
    #  value: "true"

警告

上述示例使用纯文本字符串作为密钥。建议按照此处所述使用密钥存储来管理密钥。

规范元数据字段

使用连接字符串进行身份验证

使用 PostgreSQL 连接字符串进行身份验证时，以下元数据选项是必需的。

字段	必需	详情	示例
`connectionString`	Y	PostgreSQL 数据库的连接字符串。有关如何定义连接字符串的信息，请参阅 PostgreSQL 数据库连接文档。	`"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`

使用单独的连接参数进行身份验证

除了使用连接字符串外，您还可以选择指定单独的连接参数。这些参数等同于标准 PostgreSQL 连接参数。

字段	必需	详情	示例
`host`	Y	PostgreSQL 服务器的主机名或 IP 地址	`"localhost"`
`hostaddr`	N	PostgreSQL 服务器的 IP 地址（host 的替代方案）	`"127.0.0.1"`
`port`	Y	PostgreSQL 服务器的端口号	`"5432"`
`database`	Y	要连接的数据库名称	`"my_db"`
`user`	Y	要连接的 PostgreSQL 用户	`"postgres"`
`password`	Y	PostgreSQL 用户的密码	`"example"`
`sslRootCert`	N	SSL 根证书文件的路径	`"/path/to/ca.crt"`

注意

使用单独的连接参数时，这些参数将覆盖 connectionString 中存在的参数。

使用 Microsoft Entra ID 进行身份验证

支持使用 Microsoft Entra ID 进行身份验证，适用于 Azure Database for PostgreSQL。Dapr 支持的所有身份验证方法都可以使用，包括客户端凭据（“服务主体”）和托管标识。

字段	必需	详情	示例
`useAzureAD`	Y	必须设置为 `true` 以启用组件从 Microsoft Entra ID 获取访问令牌。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。这必须包含用户，对应于在 PostgreSQL 中创建的映射到 Microsoft Entra ID 标识的用户名称；这通常是相应主体的名称（例如 Microsoft Entra ID 应用程序的名称）。此连接字符串不应包含任何密码。	`"host=mydb.postgres.database.azure.com user=myapplication port=5432 database=my_db sslmode=require"`
`azureTenantId`	N	Microsoft Entra ID 租户的 ID	`"cd4b2887-304c-…"`
`azureClientId`	N	客户端 ID（应用程序 ID）	`"c7dd251f-811f-…"`
`azureClientSecret`	N	客户端密钥（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

支持使用 AWS IAM 进行身份验证，适用于所有版本的 PostgreSQL 类型组件。连接字符串中指定的用户必须是数据库中已存在的用户，并且是被授予 rds_iam 数据库角色的 AWS IAM 启用用户。身份验证基于 AWS 身份验证配置文件，或提供的 AccessKey/SecretKey。 AWS 身份验证令牌将在其过期时间之前由 AWS 动态轮换。

字段	必需	详情	示例
`useAWSIAM`	Y	必须设置为 `true` 以启用组件从 AWS IAM 获取访问令牌。此身份验证方法仅适用于 AWS Relational Database Service for PostgreSQL 数据库。	`"true"`
`connectionString`	Y	PostgreSQL 数据库的连接字符串。这必须包含已存在的用户，对应于在 PostgreSQL 中创建的映射到 AWS IAM 策略的用户名称。此连接字符串不应包含任何密码。请注意，使用 AWS 时数据库名称字段表示为 dbname。	`"host=mydb.postgres.database.aws.com user=myapplication port=5432 dbname=my_db sslmode=require"`
`awsRegion`	N	部署 AWS Relational Database Service 的 AWS 区域。	`"us-east-1"`
`awsAccessKey`	N	与 IAM 账户关联的 AWS 访问密钥	`"AKIAIOSFODNN7EXAMPLE"`
`awsSecretKey`	N	与访问密钥关联的密钥	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`awsSessionToken`	N	要使用的 AWS 会话令牌。仅在使用临时安全凭证时才需要会话令牌。	`"TOKEN"`

其他元数据选项

字段	必需	详情	示例
`tableName`	N	存储数据的表的名称。默认为 `state`。可以选择性地将架构名称作为前缀，例如 `public.state`	`"state"`, `"public.state"`
`metadataTableName`	N	Dapr 用于存储少量元数据属性的表的名称。默认为 `dapr_metadata`。可以选择性地将架构名称作为前缀，例如 `public.dapr_metadata`	`"dapr_metadata"`, `"public.dapr_metadata"`
`timeout`	N	数据库操作的超时时间，以 Go duration 表示。整数被解释为秒数。默认为 `20s`	`"30s"`, `30`
`cleanupInterval`	N	清理 TTL 过期的行的时间间隔，以 Go duration 或秒数表示。默认值：`1h`（1 小时）。将此值设置为 <= 0 会禁用定期清理。	`"30m"`, `1800`, `-1`
`maxConns`	N	该组件池化的最大连接数。设置为 0 或更低以使用默认值，即 4 或 CPU 数量中的较大者。	`"4"`
`connectionMaxIdleTime`	N	未使用的连接在连接池中自动关闭前的最大空闲时间。默认情况下，没有值，这留给数据库驱动程序选择。	`"5m"`
`queryExecMode`	N	控制执行查询的默认模式。默认情况下，Dapr 使用扩展协议并自动准备和缓存预处理语句。但是，这可能与 PGBouncer 等代理不兼容。在这种情况下，使用 `exec` 或 `simple_protocol` 可能更可取。	`"simple_protocol"`
`actorStateStore`	N	将此状态存储用于 Actor。默认为 `"false"`	`"true"`, `"false"`

设置 PostgreSQL

运行一个 PostgreSQL 实例。您可以使用以下命令在 Docker CE 中运行本地 PostgreSQL 实例：
```
docker run -p 5432:5432 -e POSTGRES_PASSWORD=example postgres
```
此示例未描述生产配置，因为它以纯文本设置密码，并且用户名保留为 PostgreSQL 默认值 “postgres”。
为状态数据创建一个数据库。
可以使用默认的 “postgres” 数据库，也可以创建一个新数据库来存储状态数据。
要在 PostgreSQL 中创建新数据库，请运行以下 SQL 命令：
```
CREATE DATABASE my_dapr;
```

高级

TTL 和清理

该状态存储支持使用 Dapr 存储的记录的 Time-To-Live (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应在多少秒后被视为"过期"。

由于 PostgreSQL 没有内置的 TTL 支持，这是在 Dapr 中通过在状态表中添加一个列来实现的，该列指示数据何时被视为"过期"。即使"过期"记录仍物理存储在数据库中，也不会返回给调用者。后台"垃圾收集器"定期扫描状态表中的过期行并删除它们。

您可以使用 cleanupInterval 元数据属性设置过期记录的删除间隔，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少的过期行扫描频率，但可能需要存储过期记录更长时间，可能需要更多存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupInterval 设置为更小的值；例如，5m（5 分钟）。
如果您不打算将 TTL 与 Dapr 和 PostgreSQL 状态存储一起使用，应考虑将 cleanupInterval 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库负载。

状态表中存储记录过期日期的列 expiredate 默认没有索引，因此每次定期清理都必须执行全表扫描。如果您的表中有大量记录，并且只有其中一些使用 TTL，您可能会发现在该列上创建索引很有用。假设您的状态表名称是 state（默认值），您可以使用此查询：

CREATE INDEX expiredate_idx
    ON state
    USING btree (expiredate ASC NULLS LAST);

10.27 - RavenDB

RavenDB 状态存储组件的详细信息

组件格式

要设置 RavenDB 状态存储，需创建类型为 state.ravendb 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.ravendb
  version: v1
  metadata:
  - name: serverURL
    value: <REPLACE-WITH-SERVER-URL> # 必填。示例："http://localhost:8080"
  - name: databaseName
    value: <REPLACE-WITH-DATABASE-NAME> # 可选。默认值："daprStore"
  - name: certPath
    value: <REPLACE-WITH-CERT-PATH> # 除非服务器不安全，否则必填。
  - name: keyPath
    value: <REPLACE-WITH-KEY-PATH> # 除非服务器不安全，否则必填。
  - name: EnableTTL
    value: <REPLACE-WITH-ENABLE-TTL> # 可选。默认值："true"
  - name: TTLFrequency
    value: <REPLACE-WITH-TTL-FREQUENCY> # 可选。示例："15"。默认值："60"

Warning

上述示例将密钥作为纯字符串使用。建议按照此处描述使用密钥存储来管理密钥。

规范元数据字段

Field	Required	Details	Example
serverURL	Y	RavenDB 实例的 URL	`"http://localhost:8080"`
databaseName	N	要使用的数据库名称。默认为 `"daprStore"`	`"daprStore"`
certPath	N¹	证书文件路径	`"/path/to/client.certificate.crt"`
keyPath	N¹	密钥文件路径	`"/path/to/certificate.key"`
EnableTTL	N	启用 TTL 功能的布尔值。默认为 `"true"`	`"true"`
TTLFrequency	N	TTL 清理频率（秒）。默认为 `"60"`	`"60"`

^[1] 如果服务器 URL 为 http，则 certPath 和 keyPath 字段不是必填的。但是，如果服务器 URL 为 https 且未提供 certPath 和 keyPath，则 Dapr 会返回错误。

TTL 与清理

此状态存储支持使用 Dapr 存储记录的生存时间（Time-To-Live，TTL）。使用 Dapr 存储数据时，可以设置 ttlInSeconds 元数据属性来指示数据何时应被视为"过期"。

10.28 - Redis

Redis 状态存储组件的详细信息

组件格式

要设置 Redis 状态存储，请创建一个类型为 state.redis 的组件。请参阅本指南了解如何创建和应用状态存储配置。

限制

在使用 Redis 和事务 API 之前，请确保您熟悉Redis 关于事务的限制。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.redis
  version: v1
  metadata:
  - name: redisHost
    value: <HOST>
  - name: redisPassword # 可选
    value: <PASSWORD>
  - name: useEntraID
    value: <bool> # 可选，允许值：true, false
  - name: enableTLS
    value: <bool> # 可选，允许值：true, false
  - name: clientCert
    value: # 可选
  - name: clientKey
    value: # 可选    
  - name: maxRetries
    value: # 可选
  - name: maxRetryBackoff
    value: # 可选
  - name: failover
    value: <bool> # 可选，允许值：true, false
  - name: sentinelMasterName
    value: <string> # 可选
  - name: sentinelUsername
    value: # 可选
  - name: sentinelPassword
    value: # 可选
  - name: redeliverInterval
    value: # 可选
  - name: processingTimeout
    value: # 可选
  - name: redisType
    value: # 可选
  - name: redisDB
    value: # 可选
  - name: redisMaxRetries
    value: # 可选
  - name: redisMinRetryInterval
    value: # 可选
  - name: redisMaxRetryInterval
    value: # 可选
  - name: dialTimeout
    value: # 可选
  - name: readTimeout
    value: # 可选
  - name: writeTimeout
    value: # 可选
  - name: poolSize
    value: # 可选
  - name: poolTimeout
    value: # 可选
  - name: maxConnAge
    value: # 可选
  - name: minIdleConns
    value: # 可选
  - name: idleCheckFrequency
    value: # 可选
  - name: idleTimeout
    value: # 可选
  - name: ttlInSeconds
    value: <int> # 可选
  - name: queryIndexes
    value: <string> # 可选
  # 如果希望将 Redis 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

如果您希望将 Redis 用作 actor 存储，请在 yaml 中追加以下内容。

  - name: actorStateStore
    value: "true"

规范元数据字段

字段	必填	说明	示例
redisHost	Y	Redis 主机的连接字符串。如果 `"redisType"` 为 `"cluster"`，可以是多个以逗号分隔的主机或单个主机。使用 Redis Sentinel（`"failover"` 为 `"true"`）时，也可以提供多个以逗号分隔的 sentinel 地址。	`localhost:6379`、`redis-master.default.svc.cluster.local:6379`、`sentinel1:26379,sentinel2:26379,sentinel3:26379`
redisPassword	N	Redis 主机的密码。无默认值。可以使用 `secretKeyRef` 来使用密钥引用	`""`、`"KeFg23!"`
redisUsername	N	Redis 主机的用户名。默认为空。请确保您的 Redis 服务器版本为 6 或以上，并已正确创建 ACL 规则。	`""`、`"default"`
useEntraID	N	为 Azure Cache for Redis 实现 EntraID 支持。启用此功能之前：必须以 `"server:port"` 的格式指定 `redisHost` 名称必须启用 TLS 在创建 Redis 实例 > Azure Cache for Redis下了解有关此设置的更多信息	`"true"`、`"false"`
enableTLS	N	如果 Redis 实例支持使用公共证书的 TLS，可以配置为启用或禁用。默认为 `"false"`	`"true"`、`"false"`
clientCert	N	客户端证书的内容，用于需要客户端证书的 Redis 实例。必须与 `clientKey` 一起使用，且 `enableTLS` 必须设置为 true。建议按照此处的描述使用密钥存储	`"----BEGIN CERTIFICATE-----\nMIIC..."`
clientKey	N	客户端私钥的内容，与 `clientCert` 结合使用进行身份验证。建议按照此处的描述使用密钥存储	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
maxRetries	N	放弃前的最大重试次数。默认为 `3`	`5`、`10`
maxRetryBackoff	N	每次重试之间的最大退避时间。默认为 `2` 秒；`"-1"` 禁用退避。	`3000000000`
failover	N	启用故障转移配置的属性。需要设置 sentinelMasterName。启用时，redisHost 应包含 sentinel 地址。默认为 `"false"`	`"true"`、`"false"`
sentinelMasterName	N	Sentinel 主节点名称。请参阅 Redis Sentinel 文档	`""`、`"mymaster"`
sentinelUsername	N	Redis Sentinel 的用户名。仅当 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"username"`
sentinelPassword	N	Redis Sentinel 的密码。仅当 “failover” 为 true 且 Redis Sentinel 已启用身份验证时适用	`"password"`
redeliverInterval	N	检查待重新投递消息的间隔时间。默认为 `"60s"`。`"0"` 禁用重新投递。	`"30s"`
processingTimeout	N	消息在尝试重新投递之前必须保持待处理状态的时间量。默认为 `"15s"`。`"0"` 禁用重新投递。	`"30s"`
redisType	N	Redis 的类型。有两个有效值，一个是 `"node"` 用于单节点模式，另一个是 `"cluster"` 用于 Redis 集群模式。默认为 `"node"`。	`"cluster"`
redisDB	N	连接到 Redis 后选择的数据库。如果 `"redisType"` 为 `"cluster"`，则忽略此选项。默认为 `"0"`。	`"0"`
redisMaxRetries	N	`maxRetries` 的别名。如果两个值都已设置，则忽略 `maxRetries`。	`"5"`
redisMinRetryInterval	N	每次重试之间 Redis 命令的最小退避时间。默认为 `"8ms"`；`"-1"` 禁用退避。	`"8ms"`
redisMaxRetryInterval	N	`maxRetryBackoff` 的别名。如果两个值都已设置，则忽略 `maxRetryBackoff`。	`"5s"`
dialTimeout	N	建立新连接的拨号超时时间。默认为 `"5s"`。	`"5s"`
readTimeout	N	套接字读取的超时时间。如果达到此时间，Redis 命令将以超时失败而不是阻塞。默认为 `"3s"`，`"-1"` 表示无超时。	`"3s"`
writeTimeout	N	套接字写入的超时时间。如果达到此时间，Redis 命令将以超时失败而不是阻塞。默认为 readTimeout。	`"3s"`
poolSize	N	套接字连接的最大数量。默认为每个 CPU 10 个连接，由 runtime.NumCPU 报告。	`"20"`
poolTimeout	N	如果所有连接都忙，客户端等待连接的时间，然后返回错误。默认为 readTimeout + 1 秒。	`"5s"`
maxConnAge	N	客户端退役（关闭）连接的连接时长。默认为不关闭旧连接。	`"30m"`
minIdleConns	N	保持打开的最小空闲连接数，以避免与创建新连接相关的性能下降。默认为 `"0"`。	`"2"`
idleCheckFrequency	N	空闲连接清理器执行的空闲检查频率。默认为 `"1m"`。`"-1"` 禁用空闲连接清理器。	`"-1"`
idleTimeout	N	客户端关闭空闲连接之后的时间量。应小于服务器的超时时间。默认为 `"5m"`。`"-1"` 禁用空闲超时检查。	`"10m"`
ttlInSeconds	N	允许指定以秒为单位的默认生存时间（TTL），该时间将应用于每个状态存储请求，除非通过请求元数据显式定义 TTL。	`600`
queryIndexes	N	用于查询 JSON 对象的索引模式	参见查询 JSON 对象
actorStateStore	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`、`"false"`

设置 Redis

Dapr 可以使用任何 Redis 实例：容器化的、在本地开发机器上运行的或托管的云服务。

当您运行 dapr init 时，会自动创建一个 Redis 实例作为 Docker 容器

您可以使用 Helm 在 Kubernetes 集群中快速创建 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。请注意，我们显式设置了镜像标签以获取大于 5 的版本，这是 Dapr 的发布订阅功能所需的。如果您仅打算将 Redis 用作状态存储（而不是用于发布订阅），则不必设置镜像版本。
```
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis
```
运行 kubectl get pods 以查看 Redis 容器现在正在集群中运行。

将 redis-master:6379 作为 redisHost 添加到您的 redis.yaml 文件中。例如：

    metadata:
    - name: redisHost
      value: redis-master:6379

接下来，获取 Redis 密码，根据我们使用的操作系统，这略有不同：
- Windows：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" > encoded.b64，这将创建一个包含编码密码的文件。接下来，运行 certutil -decode encoded.b64 password.txt，这将把您的 redis 密码放入名为 password.txt 的文本文件中。复制密码并删除这两个文件。
- Linux/MacOS：运行 kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode 并复制输出的密码。
将此密码作为 redisPassword 值添加到您的 redis.yaml 文件中。例如：
```
    metadata:
    - name: redisPassword
      value: lhDOkwTlp0
```

AWS Redis

使用 Microsoft 官方文档创建 Azure Cache for Redis 实例。
创建实例后，从 Azure 门户获取主机名（FQDN）和访问密钥。
- 对于主机名：
  - 导航到资源的概览页面。
  - 复制主机名值。
- 对于访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存您的密钥。
将您的密钥和主机名添加到 Dapr 可以应用到集群的 redis.yaml 文件中。
- 如果您正在运行示例，请将主机和密钥添加到提供的 redis.yaml 中。
- 如果您是从头开始创建项目，请按照组件格式部分中的说明创建 redis.yaml 文件。
将 redisHost 键设置为 [上一步的主机名]:6379，将 redisPassword 键设置为之前保存的密钥。
注意： 在生产级应用程序中，请遵循密钥管理说明来安全地管理您的密钥。
启用 EntraID 支持：
- 在 Azure Redis 服务器上启用 Entra ID 身份验证。这可能需要几分钟。
- 将 useEntraID 设置为 "true" 以为 Azure Cache for Redis 实现 EntraID 支持。
将 enableTLS 设置为 "true" 以支持 TLS。

注意：useEntraID 假定您的 UserPrincipal（通过 AzureCLICredential）或系统分配的托管身份具有 RedisDataOwner 角色权限。如果使用用户分配的托管身份，您需要指定 azureClientID 属性。

GCP Cloud MemoryStore

查询 JSON 对象（可选）

除了支持以键值对的形式存储和查询状态数据外，Redis 状态存储还可选支持 JSON 对象查询，以满足更复杂的查询或过滤需求。要启用此功能，需要执行以下步骤：

Redis 存储必须支持 Redis 模块，特别是 Redisearch 和 RedisJson。如果您正在部署和运行 Redis，则在部署 Redis 服务时加载 redisearch 和 redisjson 模块。
在组件配置的元数据中指定 queryIndexes 条目。queryIndexes 的值是以下格式的 JSON 数组：

[
  {
    "name": "<索引名称>",
    "indexes": [
      {
        "key": "<文档内选定元素的 JSONPath 类似语法>",
        "type": "<值类型（支持的类型：TEXT、NUMERIC）>",
      },
      ...
    ]
  },
  ...
]

调用状态管理 API 时，将以下元数据添加到 API 调用中：

保存状态、获取状态、删除状态：
- 向 HTTP API 请求添加 metadata.contentType=application/json URL 查询参数
- 向 gRPC API 请求的元数据中添加 "contentType": "application/json" 键值对
查询状态：
- 向 HTTP API 请求添加 metadata.contentType=application/json&metadata.queryIndexName=<索引名称> URL 查询参数
- 向 gRPC API 请求的元数据中添加 "contentType" : "application/json" 和 "queryIndexName" : "<索引名称>" 键值对

考虑一个示例，您存储如下文档：

{
  "key": "1",
  "value": {
    "person": {
      "org": "Dev Ops",
      "id": 1036
    },
    "city": "Seattle",
    "state": "WA"
  }
}

包含相应索引模式的组件配置文件如下所示：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.redis
  version: v1
  initTimeout: 1m
  metadata:
  - name: redisHost
    value: "localhost:6379"
  - name: redisPassword
    value: ""
  - name: queryIndexes
    value: |
      [
        {
          "name": "orgIndx",
          "indexes": [
            {
              "key": "person.org",
              "type": "TEXT"
            },
            {
              "key": "person.id",
              "type": "NUMERIC"
            },
            {
              "key": "state",
              "type": "TEXT"
            },
            {
              "key": "city",
              "type": "TEXT"
            }
          ]
        }
      ]

因此，您现在可以存储、检索和查询这些文档。

考虑“操作方法：查询状态”指南中的示例。让我们使用 Redis 来运行它。

如果您使用的是 Dapr 的自托管部署，当您运行 dapr init 时，会自动创建一个没有 JSON 模块的 Redis 实例作为 Docker 容器。

或者，您可以通过运行以下命令创建 Redis 实例：

docker run -p 6379:6379 --name redis --rm redis

在 dapr init 时创建的或通过上述命令创建的 Redis 容器不能单独与状态存储查询 API 一起使用。您可以在与已安装的 Redis 使用的端口不同的端口上运行 redislabs/rejson docker 镜像，以使用查询 API。

注意：redislabs/rejson 仅支持 amd64 架构。

使用以下命令创建与查询 API 兼容的 redis 实例。

docker run -p 9445:9445 --name rejson --rm redislabs/rejson:2.0.6

按照 Redis 在 Kubernetes 中部署的说明操作，但有一个额外的细节。

安装 Redis Helm 软件包时，提供一个指定容器镜像并启用所需模块的配置文件：

helm install redis bitnami/redis --set image.tag=6.2 -f values.yaml

其中 values.yaml 如下所示：

image:
  repository: redislabs/rejson
  tag: 2.0.6

master:
  extraFlags:
   - --loadmodule
   - /usr/lib/redis/modules/rejson.so
   - --loadmodule
   - /usr/lib/redis/modules/redisearch.so

注意

Azure Redis 托管服务不支持 RedisJson 模块，不能与查询一起使用。

按照 Redis 在 AWS 中部署的说明操作。

注意

对于查询支持，您需要启用 RediSearch 和 RedisJson。

注意

Memory Store 不支持模块，不能与查询一起使用。

Redis Enterprise Cloud

Alibaba Cloud

接下来是启动 Dapr 应用程序。请参阅此组件配置文件，其中包含查询索引模式。确保修改 redisHost 以反映 redislabs/rejson 使用的本地转发端口。

dapr run --app-id demo --dapr-http-port 3500 --resources-path query-api-examples/components/redis

现在使用员工数据集填充状态存储，以便您稍后查询它。

curl -X POST -H "Content-Type: application/json" -d @query-api-examples/dataset.json \
  http://localhost:3500/v1.0/state/querystatestore?metadata.contentType=application/json

为了确保数据已正确存储，您可以检索特定对象

curl http://localhost:3500/v1.0/state/querystatestore/1?metadata.contentType=application/json

结果将是：

{
  "city": "Seattle",
  "state": "WA",
  "person": {
    "org": "Dev Ops",
    "id": 1036
  }
}

现在，让我们查找加利福尼亚州的所有员工，并按其员工 ID 降序排序。

这是查询：

{
    "filter": {
        "EQ": { "state": "CA" }
    },
    "sort": [
        {
            "key": "person.id",
            "order": "DESC"
        }
    ]
}

使用以下命令执行查询：

curl -s -X POST -H "Content-Type: application/json" -d @query-api-examples/query1.json \
  'http://localhost:3500/v1.0-alpha1/state/querystatestore/query?metadata.contentType=application/json&metadata.queryIndexName=orgIndx'

结果将是：

{
  "results": [
    {
      "key": "3",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1071
        },
        "city": "Sacramento",
        "state": "CA"
      },
      "etag": "1"
    },
    {
      "key": "7",
      "data": {
        "person": {
          "org": "Dev Ops",
          "id": 1015
        },
        "city": "San Francisco",
        "state": "CA"
      },
      "etag": "1"
    },
    {
      "key": "5",
      "data": {
        "person": {
          "org": "Hardware",
          "id": 1007
        },
        "city": "Los Angeles",
        "state": "CA"
      },
      "etag": "1"
    },
    {
      "key": "9",
      "data": {
        "person": {
          "org": "Finance",
          "id": 1002
        },
        "city": "San Diego",
        "state": "CA"
      },
      "etag": "1"
    }
  ]
}

查询语法和文档可在此处找到

Redis Sentinel 配置

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: redis-pubsub
spec:
  type: pubsub.redis
  version: v1
  metadata:
  - name: redisHost
    value: "sentinel1:26379,sentinel2:26379,sentinel3:26379"
  - name: redisType
    value: "node"
  - name: failover
    value: "true"
  - name: sentinelMasterName
    value: "mymaster"
```

10.29 - RethinkDB

RethinkDB 状态存储组件的详细信息

组件格式

要设置 RethinkDB 状态存储，请创建一个类型为 state.rethinkdb 的组件。请参阅如何操作指南来创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.rethinkdb
  version: v1
  metadata:
  - name: address
    value: <REPLACE-RETHINKDB-ADDRESS> # 必填，例如 127.0.0.1:28015 或 rethinkdb.default.svc.cluster.local:28015。
  - name: database
    value: <REPLACE-RETHINKDB-DB-NAME> # 必填，例如 dapr（仅限字母数字）
  - name: table
    value: # 可选
  - name: username
    value: <USERNAME> # 可选
  - name: password
    value: <PASSWORD> # 可选
  - name: archive
    value: bool # 可选（存储是否应保留所有状态更改的归档表）

Warning

上述示例使用纯文本字符串作为密钥。建议使用密钥存储来管理密钥，如此处所述。

如果将可选的 archive 元数据设置为 true，则在每次状态更改时，RethinkDB 状态存储还会在 daprstate_archive 表中记录带有时间戳的状态更改。这允许对由 Dapr 管理的状态进行时间序列分析。

规范元数据字段

字段	必填	详情	示例
address	Y	RethinkDB 服务器的地址	`"127.0.0.1:28015"`, `"rethinkdb.default.svc.cluster.local:28015"`
database	Y	要使用的数据库。仅限字母数字	`"dapr"`
table	N	要使用的表名称	`"table"`
username	N	用于连接的用户名	`"user"`
password	N	用于连接的密码	`"password"`
archive	N	是否归档表	`"true"`, `"false"`

设置 RethinkDB

您可以使用 Docker 在本地运行 RethinkDB：

docker run --name rethinkdb -v "$PWD:/rethinkdb-data" -d rethinkdb:latest

要连接到管理 UI：

open "http://$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' rethinkdb):8080"

10.30 - SQLite

SQLite 状态存储组件的详细信息

该组件允许将 SQLite 3 用作 Dapr 的状态存储。

该组件目前使用 SQLite 版本 3.41.2 编译。

创建 Dapr 组件

创建一个名为 sqlite.yaml 的文件，粘贴以下内容，并将 <CONNECTION STRING> 值替换为你的连接字符串，即磁盘上文件的路径。

如果还想将 SQLite 配置为存储 actor，可以添加 actorStateStore 选项，如下所示。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.sqlite
  version: v1
  metadata:
  # 连接字符串
  - name: connectionString
    value: "data.db"
  # 数据库操作的超时时间，单位为秒（可选）
  #- name: timeoutInSeconds
  #  value: 20
  # 用于存储状态的表名（可选）
  #- name: tableName
  #  value: "state"
  # 清理间隔，单位为秒，用于删除过期行（可选）
  #- name: cleanupInterval
  #  value: "1h"
  # 为数据库操作设置 busy timeout
  #- name: busyTimeout
  #  value: "2s"
  # 如果你想将 SQLite 用作 actor 的状态存储，取消此行的注释（可选）
  #- name: actorStateStore
  #  value: "true"

规范元数据字段

字段	必填	详情	示例
`connectionString`	Y	SQLite 数据库的连接字符串。更多详情见下文。	`"path/to/data.db"`, `"file::memory:?cache=shared"`
`timeout`	N	数据库操作的超时时间，格式为 Go duration。整数将被解释为秒数。默认为 `20s`	`"30s"`, `30`
`tableName`	N	用于存储数据的表名。默认为 `state`。	`"state"`
`metadataTableName`	N	Dapr 用于存储组件元数据的表名。默认为 `metadata`。	`"metadata"`
`cleanupInterval`	N	清理具有过期 TTL 的行的间隔，格式为 Go duration。将此值设置为 <=0 会禁用定期清理。默认：`0`（即禁用）	`"2h"`, `"30m"`, `-1`
`busyTimeout`	N	当 SQLite 数据库正忙于处理另一个请求时，在返回"数据库忙碌"错误之前等待的间隔，格式为 Go duration。默认：`2s`	`"100ms"`, `"5s"`
`disableWAL`	N	如果设置为 true，则禁用 SQLite 数据库日志的预写式日志记录。如果数据库存储在网络文件系统上（例如，挂载为 SMB 或 NFS 共享的文件夹），应将其设置为 `false`。对于只读或内存数据库，此选项将被忽略。	`"true"`, `"false"`
`actorStateStore`	N	将此状态存储用于 actor。默认为 `"false"`	`"true"`, `"false"`

connectionString 参数配置如何打开 SQLite 数据库。

通常，这是磁盘上文件的路径，相对于当前工作目录或绝对路径。例如："data.db"（相对于工作目录）或 "/mnt/data/mydata.db"。
路径由 SQLite 库解释，因此如果路径以 file: 开头，可以使用"URI 选项"向 SQLite 驱动程序传递其他选项。例如："file:path/to/data.db?mode=ro" 以只读模式打开路径为 path/to/data.db 的数据库。有关所有支持的 URI 选项，请参阅 SQLite 文档。
特殊情况 ":memory:" 会启动由内存 SQLite 数据库支持的组件。此数据库不会持久化到磁盘，不会在多个 Dapr 实例之间共享，并且当 Dapr 边车停止时所有数据都会丢失。使用内存数据库时，Dapr 会自动设置 cache=shared URI 选项。

高级

TTL 和清理

此状态存储支持使用 Dapr 存储的记录的生存时间 (TTL)。使用 Dapr 存储数据时，可以设置 ttlInSeconds 元数据属性来指示数据何时应被视为"已过期"。

由于 SQLite 没有内置的 TTL 支持，这是在 Dapr 中通过在状态表中添加一个列来实现的，该列指示数据何时应被视为"已过期"。“已过期"的记录不会返回给调用者，即使它们仍然物理存储在数据库中。后台"垃圾收集器"会定期扫描状态表以查找过期行并删除它们。

cleanupInterval 元数据属性设置过期记录的删除间隔，默认情况下禁用。

较长的间隔需要较少的过期行扫描频率，但可能导致数据库存储过期记录的时间更长，可能需要更多的存储空间。如果你计划在状态表中存储许多记录，且 TTL 较短，可以考虑将 cleanupInterval 设置为较小的值，例如 5m。
如果你不打算使用 Dapr 和 SQLite 状态存储的 TTL，应考虑将 cleanupInterval 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库负载。这是默认行为。

状态表中存储记录过期日期的 expiration_time 列默认没有索引，因此每次定期清理都必须执行全表扫描。如果你的表有大量记录，并且只有其中一些使用 TTL，你可能会发现在该列上创建索引很有用。假设你的状态表名称是 state（默认值），你可以使用以下查询：

CREATE INDEX idx_expiration_time
  ON state (expiration_time);

Dapr 不会自动 vacuum SQLite 数据库。

共享 SQLite 数据库和使用网络文件系统

虽然你可以有多个 Dapr 实例访问同一个 SQLite 数据库（例如，因为你的应用程序水平扩展或你有多个应用程序访问同一个状态存储），但你应该记住一些注意事项。

当所有客户端访问同一本地安装磁盘上的数据库文件时，SQLite 工作效果最佳。使用从 SAN（存储区域网络）挂载的虚拟磁盘，这是虚拟化或云环境中的常见做法，是可以的。

但是，将 SQLite 数据库存储在网络文件系统（例如通过 NFS 或 SMB，但这些示例并非详尽列表）中应该小心。SQLite 官方文档有一个专门的页面，介绍在网络运行 SQLite 的建议和注意事项。

鉴于通过网络文件系统（例如通过 NFS 或 SMB）运行 SQLite 会带来数据损坏的风险，我们不建议在生产环境中对 Dapr 执行此操作。但是，如果你确实想这样做，你应该将 SQLite Dapr 组件配置为将 disableWAL 设置为 true。

10.31 - Zookeeper

Zookeeper 状态存储组件的详细信息

组件格式

要设置 Zookeeper 状态存储，请创建一个类型为 state.zookeeper 的组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.zookeeper
  version: v1
  metadata:
  - name: servers
    value: <REPLACE-WITH-COMMA-DELIMITED-SERVERS> # 必填。示例："zookeeper.default.svc.cluster.local:2181"
  - name: sessionTimeout
    value: <REPLACE-WITH-SESSION-TIMEOUT> # 必填。示例："5s"
  - name: maxBufferSize
    value: <REPLACE-WITH-MAX-BUFFER-SIZE> # 可选。默认值："1048576"
  - name: maxConnBufferSize
    value: <REPLACE-WITH-MAX-CONN-BUFFER-SIZE> # 可选。默认值："1048576"
  - name: keyPrefixPath
    value: <REPLACE-WITH-KEY-PREFIX-PATH> # 可选。

Warning

上述示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	详情	示例
servers	Y	服务器列表，以逗号分隔	`"zookeeper.default.svc.cluster.local:2181"`
sessionTimeout	Y	会话超时值	`"5s"`
maxBufferSize	N	缓冲区的最大大小。默认为 `"1048576"`	`"1048576"`
maxConnBufferSize	N	连接缓冲区的最大大小。默认为 `"1048576`"	`"1048576"`
keyPrefixPath	N	Zookeeper 中的键前缀路径。无默认值	`"dapr"`

设置 Zookeeper

您可以使用 Docker 在本地运行 Zookeeper：

docker run --name some-zookeeper --restart always -d zookeeper

然后您可以使用 localhost:2181 与服务器交互。

在 Kubernetes 上安装 Zookeeper 最简单的方法是使用 Helm chart：

helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
helm install zookeeper incubator/zookeeper

这会将 Zookeeper 安装到 default 命名空间中。要与 Zookeeper 交互，请使用以下命令查找服务：kubectl get svc zookeeper。

例如，如果使用上述示例安装，Zookeeper 主机地址将是：

zookeeper.default.svc.cluster.local:2181

字段	数据类型	可为空	详情
KEY	VARCHAR	N	保存配置属性的 `"Key"`
VALUE	VARCHAR	N	保存配置属性的 Value
VERSION	VARCHAR	N	保存配置属性的版本
METADATA	JSON	Y	将 Metadata 保存为 JSON

Dapr 组件参考

1 - 绑定组件规格

Generic

Alibaba Cloud

Amazon Web Services (AWS)

Cloudflare

Google Cloud Platform (GCP)

Microsoft Azure

Zeebe (Camunda Cloud)

1.1 - Alibaba Cloud DingTalk binding 规范

设置 Dapr 组件

Warning

规范元数据字段

Binding 支持

指定负载

相关链接

1.2 - Alibaba Cloud Tablestore binding 规范

组件格式

Warning

规范元数据字段

Binding 支持

创建对象

Note

删除对象

Note

列出对象

Note

获取对象

Note

相关链接

1.3 - Apple Push Notification Service 绑定规范

组件格式

规格元数据字段

私钥

绑定支持

推送通知格式

请求格式

响应格式

相关链接

1.4 - AWS DynamoDB 绑定规范

组件格式

Warning

规范元数据字段

Important

绑定支持

相关链接

1.5 - AWS Kinesis 绑定规范

组件格式

警告

规范元数据字段

重要

绑定支持

相关链接

1.6 - AWS S3 绑定规范

组件格式

警告

规范元数据字段

重要

S3 存储桶创建

与 Minio 一起使用

绑定支持

创建对象

使用预签名 URL 共享对象

响应

示例

将文本保存到随机生成的 UUID 文件

将文本保存到特定文件

将文件保存为对象

从文件路径上传

响应

预签名现有对象

响应

获取对象

示例

响应

删除对象

示例

删除对象

响应

列出对象