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

1.1 - Apache Kafka

Apache Kafka pubsub 组件的详细说明文档

组件格式

要设置 Apache Kafka 的发布/订阅功能，您需要创建一个类型为 pubsub.kafka 的组件。请参阅 pub/sub broker 组件文件了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南了解如何创建和应用发布/订阅配置。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需字段，Kafka broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "{namespace}"
  - name: consumerID # 可选字段。如果未提供，运行时将自动创建。
    value: "channel1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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 # 可选字段。高级设置。请求中要获取的最小消息字节数 - broker 将等待直到至少有这么多可用。
    value: 1
  - name: consumerFetchDefault # 可选字段。高级设置。每个请求中从 broker 获取的默认消息字节数。
    value: 2097152
  - name: channelBufferSize # 可选字段。高级设置。内部和外部通道中要缓冲的事件数量。
    value: 512
  - 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 序列化/反序列化时。启用模式缓存。
    value: true
  - name: schemaLatestVersionCacheTTL # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。发布具有最新模式的消息时的模式缓存 TTL。
    value: 5m
  - name: escapeHeaders # 可选字段。
    value: false

有关使用 secretKeyRef 的详细信息，请参阅如何在组件中引用 secrets 的指南。

规格元数据字段

字段	必需	详情	示例
brokers	Y	逗号分隔的 Kafka brokers 列表。	`"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 brokers，用于日志记录、调试和审计。默认为 Kubernetes 模式的 `"namespace.appID"` 或 Self-Hosted 模式的 `"appID"`。	`"my-namespace.my-dapr-app"`，`"my-dapr-app"`
authRequired	N	已弃用启用 SASL 认证与 Kafka brokers。	`"true"`，`"false"`
authType	Y	配置或禁用认证。支持的值：`none`，`password`，`mtls`，`oidc` 或 `awsiam`	`"password"`，`"none"`
saslUsername	N	用于认证的 SASL 用户名。仅在 `authType` 设置为 `"password"` 时需要。	`"adminuser"`
saslPassword	N	用于认证的 SASL 密码。可以是 `secretKeyRef` 以使用 secret 引用。仅在 `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 和 Kafka，则必须将其设置为 `1.0.0`。	`0.10.2.0`
caCert	N	证书颁发机构证书，使用 TLS 时需要。可以是 `secretKeyRef` 以使用 secret 引用	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	N	客户端证书，`authType` 为 `mtls` 时需要。可以是 `secretKeyRef` 以使用 secret 引用	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	N	客户端密钥，`authType` 为 `mtls` 时需要。可以是 `secretKeyRef` 以使用 secret 引用	`"-----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 客户端 secret：当 `authType` 设置为 `oidc` 时需要	`"KeFg23!"`
oidcScopes	N	用于请求访问令牌的 OAuth2/OIDC 范围的逗号分隔列表。当 `authType` 设置为 `oidc` 时推荐。默认为 `"openid"`	`"openid,kafka-prod"`
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’。与访问密钥关联的 secret 密钥。	`"secretKey"`
awsSessionToken	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅在使用临时安全凭证时需要会话令牌。	`"sessionToken"`
awsIamRoleArn	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘assumeRoleArn’。具有访问 AWS 管理的 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 Key。	`XYAXXAZ`
schemaRegistryAPISecret	N	使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API Secret。	`ABCDEFGMEADFF`
schemaCachingEnabled	N	使用 Schema Registry Avro 序列化/反序列化时。启用模式缓存。默认为 `true`	`true`
schemaLatestVersionCacheTTL	N	使用 Schema Registry Avro 序列化/反序列化时。发布具有最新模式的消息时的模式缓存 TTL。默认为 5 分钟	`5m`
clientConnectionTopicMetadataRefreshInterval	N	客户端连接的主题元数据与 broker 刷新的间隔，以 Go 持续时间表示。默认为 `9m`。	`"4m"`
clientConnectionKeepAliveInterval	N	客户端连接与 broker 保持活动的最长时间，以 Go 持续时间表示，然后关闭连接。零值（默认）表示无限期保持活动。	`"4m"`
consumerFetchMin	N	请求中要获取的最小消息字节数 - broker 将等待直到至少有这么多可用。默认值为 `1`，因为 `0` 会导致消费者在没有消息可用时旋转。相当于 JVM 的 `fetch.min.bytes`。	`"2"`
consumerFetchDefault	N	每个请求中从 broker 获取的默认消息字节数。默认值为 `"1048576"` 字节。	`"2097152"`
channelBufferSize	N	内部和外部通道中要缓冲的事件数量。这允许生产者和消费者在用户代码工作时继续在后台处理一些消息，从而大大提高吞吐量。默认为 `256`。	`"512"`
heartbeatInterval	N	向消费者协调器发送心跳的间隔。最多应将值设置为 `sessionTimeout` 值的 1/3。默认为 “3s”。	`"5s"`
sessionTimeout	N	使用 Kafka 的组管理功能时用于检测客户端故障的超时时间。如果 broker 在此会话超时之前未收到任何来自消费者的心跳，则消费者将被移除并启动重新平衡。默认为 “10s”。	`"20s"`
escapeHeaders	N	启用对消费者接收到的消息头值的 URL 转义。允许接收通常不允许在 HTTP 头中使用的特殊字符内容。默认为 `false`。	`true`

上面的 secretKeyRef 引用了一个 kubernetes secrets store 以访问 tls 信息。访问此处了解有关如何配置 secret store 组件的更多信息。

注意

使用 Azure EventHubs 和 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
awsiam

注意

authType 仅用于认证。授权仍在 Kafka 内配置，除了 awsiam，它还可以驱动在 AWS IAM 中配置的授权决策。

None

将 authType 设置为 none 将禁用任何认证。这在生产中不推荐。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub-noauth
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需字段，Kafka broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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 broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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

Mutual 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 broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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 broker 验证。如果不使用其他范围来缩小访问令牌的有效性，被破坏的 Kafka broker 可能会重放令牌以访问其他服务作为 Dapr clientID。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需字段，Kafka broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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

AWS IAM

支持使用 MSK 进行 AWS IAM 认证。将 authType 设置为 awsiam 使用 AWS SDK 生成认证令牌进行认证。

注意

唯一必需的元数据字段是 region。如果没有提供 acessKey 和 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 broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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 pubsub 组件示例：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: kafka-pubsub
spec:
  type: pubsub.kafka
  version: v1
  metadata:
  - name: brokers # 必需字段，Kafka broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 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>

从多个主题消费

当使用单个 pub/sub 组件从多个主题消费时，无法保证您的消费者组中的消费者如何在主题分区之间平衡。

例如，假设您订阅了两个主题，每个主题有 10 个分区，并且您有 20 个服务副本从这两个主题消费。无法保证 10 个将分配给第一个主题，10 个将分配给第二个主题。相反，分区可能会不均匀地划分，超过 10 个分配给第一个主题，其余分配给第二个主题。

这可能导致第一个主题的消费者空闲，而第二个主题的消费者过度扩展，反之亦然。当使用自动缩放器（如 HPA 或 KEDA）时，也可以观察到这种行为。

如果您遇到此特定问题，建议您为每个主题配置一个单独的 pub/sub 组件，并为每个组件定义唯一的消费者组。这可以确保您的服务的所有副本都完全分配给唯一的消费者组，其中每个消费者组针对一个特定主题。

例如，您可以定义两个 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 组件支持使用批量 Pub/sub API 在单个操作中发送和接收多条消息。

配置批量订阅

订阅主题时，您可以配置 bulkSubscribe 选项。有关更多详细信息，请参阅批量订阅消息。了解更多关于批量订阅 API 的信息。

Apache Kafka 支持以下批量元数据选项：

配置	默认值
`maxBulkAwaitDurationMs`	`10000` (10s)
`maxBulkSubCount`	`80`

每次调用的元数据字段

分区键

调用 Kafka pub/sub 时，可以通过在请求 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 Pubsub 在消费者端接收到的特殊消息头

消费消息时，特殊消息元数据会自动作为头传递。这些是：

__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 “反转义” 以获得原始值。

将 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 broker 连接设置
    value: "dapr-kafka.myapp.svc.cluster.local:9092"
  - name: consumerGroup # 可选字段，用于输入绑定。
    value: "group1"
  - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 ID。
    value: "my-dapr-app-id"
  - name: authType # 必需字段。
    value: "none"
  - name: escapeHeaders
    value: "true"

Avro Schema Registry 序列化/反序列化

您可以配置 pub/sub 以使用 Avro 二进制序列化发布或消费数据，利用 Apache Schema Registry（例如，Confluent Schema Registry，Apicurio）。

配置

重要

目前，仅支持消息值的序列化/反序列化。由于不支持云事件，发布 Avro 消息时必须传递 rawPayload=true 元数据。请注意，消费者不应设置 rawPayload=true，因为消息值将被包装到 CloudEvent 中并进行 base64 编码。将 rawPayload 保持为默认值（即 false）将以 JSON 负载的形式将 Avro 解码的消息发送到应用程序。

配置 Kafka pub/sub 组件元数据时，您必须定义：

Schema Registry URL
API key/secret（如果适用）

模式主题是根据主题名称自动派生的，使用标准命名约定。例如，对于名为 my-topic 的主题，模式主题将是 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 pub/sub 组件指示消息应使用 Avro 序列化，必须在 metadata 中设置 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
    }
    # 创建一个带有内容类型和主体的类型化消息
    resp = d.publish_event(
        pubsub_name='pubsub',
        topic_name='my-topic',
        data=json.dumps(req_data),
        publish_metadata={'rawPayload': 'true', 'valueSchemaType': 'Avro'}
    )
    # 打印请求
    print(req_data, flush=True)

订阅 Avro 主题

为了向 Kafka pub/sub 组件指示消息应使用 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)

创建一个 Kafka 实例

您可以使用这个 Docker 镜像在本地运行 Kafka。要在没有 Docker 的情况下运行，请参阅此处的入门指南。

要在 Kubernetes 上运行 Kafka，您可以使用任何 Kafka operator，例如 Strimzi。

1.2 - AWS SNS/SQS

关于AWS SNS/SQS pubsub组件的详细文档

组件格式

要设置AWS SNS/SQS pub/sub，创建一个类型为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"

警告

上述示例使用明文字符串作为secret。建议使用secret存储来存储secret。

规格元数据字段

字段	必需	详情	示例
accessKey	Y	具有适当权限的AWS账户/角色的ID，用于SNS和SQS（见下文）	`"AKIAIOSFODNN7EXAMPLE"`
secretKey	Y	AWS用户/角色的secret。如果使用`AssumeRole`访问，还需要提供`sessionToken`	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
region	Y	SNS/SQS资产所在或将创建的AWS区域。请参阅此页面以获取有效区域。确保SNS和SQS在该区域可用	`"us-east-1"`
consumerID	N	消费者ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者ID的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供`consumerID`，Dapr运行时将其设置为Dapr应用程序ID（`appID`）值。请参阅pub/sub broker组件文件以了解如何自动生成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为pubsub部署使用自定义消息组ID。这不是强制性的，因为Dapr为每个生产者创建一个自定义消息组ID，从而确保每个Dapr生产者的消息排序。默认值：`""`	`"app1-mgi"`
disableEntityManagement	N	当设置为true时，SNS主题、SQS队列和SQS到SNS的订阅不会自动创建。默认值：`"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组件行为

当pub/sub SNS/SQS组件配置SNS主题时，SQS队列和订阅在组件代表消息生产者（没有订阅者应用程序部署）操作的情况下，与存在订阅者应用程序（没有发布者部署）的情况下表现不同。

由于SNS在没有SQS订阅的情况下的工作方式_仅发布者设置_，SQS队列和订阅表现为依赖于订阅者监听主题消息的“经典”pub/sub系统。没有这些订阅者，消息：

无法传递并有效地丢弃
不可用于未来的订阅者（当订阅者最终订阅时没有消息重播）

SQS FIFO

根据AWS规范，使用SQS FIFO（fifo元数据字段设置为"true"）提供消息排序和去重，但会导致较低的SQS处理吞吐量，以及其他注意事项。

指定fifoMessageGroupID限制FIFO队列的并发消费者数量为1，但保证应用程序的Dapr sidecar发布的消息的全局排序。请参阅这篇AWS博客文章以更好地理解消息组ID和FIFO队列的主题。

为了避免丢失传递给消费者的消息顺序，SQS组件的FIFO配置要求将concurrencyMode元数据字段设置为"single"。

默认并行`concurrencyMode`

自v1.8.0以来，组件支持"parallel" concurrencyMode作为其默认模式。在之前的版本中，组件的默认行为是一次调用订阅者一个消息并等待其响应。

SQS死信队列

在使用SQS死信队列配置PubSub组件时，元数据字段messageReceiveLimit和sqsDeadLettersQueueName必须都设置为一个值。对于messageReceiveLimit，值必须大于0，而sqsDeadLettersQueueName不能是空字符串。

重要

当在EKS（AWS Kubernetes）节点/Pod上运行Dapr sidecar（daprd）时，已经附加了定义访问AWS资源的IAM策略，您不应在组件规格的定义中提供AWS访问密钥、秘密密钥和令牌。

SNS/SQS与Dapr的争用

从根本上说，SNS通过为这些主题创建SQS订阅，将来自多个发布者主题的消息聚合到一个SQS队列中。作为订阅者，SNS/SQS pub/sub组件从该唯一的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

为了在您的pub/sub绑定中使用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
    # 使用us-east-1或提供给localstack的任何其他区域，由"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:*"
      ]
    }
  ]
}

将AWS账户ID和AWS账户secret插入组件元数据中的accessKey和secretKey，使用Kubernetes secret和secretKeyRef。

或者，假设您希望使用自己的工具（例如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行为）。

1.3 - Azure Event Hubs

Azure Event Hubs pubsub 组件的详细文档

组件格式

要配置 Azure Event Hubs 的发布/订阅功能，请创建一个类型为 pubsub.azure.eventhubs 的组件。有关 ConsumerID 自动生成的详细信息，请参阅 pub/sub broker 组件文件。要了解如何创建和应用 pub/sub 配置，请阅读发布和订阅指南。

除了下文列出的配置元数据字段，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 # 可选。如果未提供，运行时将使用 Dapr 应用程序 ID (`appID`)。
      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`	是*	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`	是*	Event Hub 命名空间名称。 * 与 `connectionString` 字段互斥。 * 使用 Microsoft Entra ID 身份验证时必需	`"namespace"`
`consumerID`	否	消费者 ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID (`appID`) 值。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看可以在组件元数据中使用的所有模板标签。
`enableEntityManagement`	否	布尔值，允许管理 EventHub 命名空间和存储帐户。默认值：`false`	`"true", "false"`
`enableInOrderMessageDelivery`	否	布尔值，允许消息按发布顺序传递。这假设在发布或发布时设置了 `partitionKey` 以确保跨分区的顺序。默认值：`false`	`"true"`, `"false"`
`storageAccountName`	是	用于检查点存储的存储帐户名称。	`"myeventhubstorage"`
`storageAccountKey`	是*	检查点存储帐户的存储帐户密钥。 * 使用 Microsoft Entra ID 时，如果服务主体也有权访问存储帐户，则可以省略此项。	`"112233445566778899"`
`storageConnectionString`	是*	检查点存储的连接字符串，指定 `storageAccountKey` 的替代方法	`"DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>"`
`storageContainerName`	是	存储帐户名称的存储容器名称。	`"myeventhubstoragecontainer"`
`resourceGroupName`	否	Event Hub 命名空间所属的资源组名称。启用实体管理时必需	`"test-rg"`
`subscriptionID`	否	Azure 订阅 ID 值。启用实体管理时必需	`"azure subscription id"`
`partitionCount`	否	新 Event Hub 命名空间的分区数。仅在启用实体管理时使用。默认值：`"1"`	`"2"`
`messageRetentionInDays`	否	在新创建的 Event Hub 命名空间中保留消息的天数。仅在启用实体管理时使用。默认值：`"1"`	`"90"`

Microsoft Entra ID 身份验证

Azure Event Hubs pub/sub 组件支持使用所有 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 Eventhubs 支持使用批量 pub/sub 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 存储作为检查点存储，您还需要一个 Azure 存储帐户。按照文档中的说明管理存储帐户访问密钥。

请参阅文档了解如何获取 Event Hubs 连接字符串（注意这不是 Event Hubs 命名空间的连接字符串）。

为每个订阅者创建消费者组

对于每个想要订阅事件的 Dapr 应用程序，创建一个以 Dapr 应用程序 ID 命名的 Event Hubs 消费者组。例如，在 Kubernetes 上运行的 Dapr 应用程序，其 dapr.io/app-id: "myapp" 将需要一个名为 myapp 的 Event Hubs 消费者组。

注意：Dapr 将消费者组的名称传递给 Event Hub，因此这不在元数据中提供。

实体管理

当在元数据中启用实体管理时，只要应用程序具有操作 Event Hub 命名空间的正确角色和权限，Dapr 就可以自动为您创建 Event Hub 和消费者组。

Event Hub 名称是发布或订阅请求中的 topic 字段，而消费者组名称是订阅给定 Event Hub 的 Dapr 应用程序的名称。例如，在 Kubernetes 上运行的 Dapr 应用程序，其名称为 dapr.io/app-id: "myapp" 需要一个名为 myapp 的 Event Hubs 消费者组。

实体管理仅在使用 Microsoft Entra ID 身份验证且不使用连接字符串时才可能。

Dapr 将消费者组的名称传递给 Event Hub，因此这不在元数据中提供。

订阅 Azure IoT Hub 事件

Azure IoT Hub 提供了一个与 Event Hubs 兼容的端点，因此 Azure Event Hubs pubsub 组件也可以用于订阅 Azure IoT Hub 事件。

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

系统属性名称	描述和路由查询关键字
`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 订阅消息的头将包含：

{
  '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.4 - Azure Service Bus Topics

Azure Service Bus Topics pubsub 组件的详细文档

组件格式

要配置 Azure Service Bus Topics pub/sub，需创建一个类型为 pubsub.azure.servicebus.topics 的组件。请参考 pub/sub broker 组件文件了解 ConsumerID 的自动生成方式。阅读发布和订阅指南以获取创建和应用 pub/sub 配置的步骤。

此组件使用 Azure Service Bus 的主题功能；请查看官方文档了解主题和队列的区别。
如需使用队列，请参阅 Azure Service Bus Queues pubsub 组件。

连接字符串认证

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

注意： 上述设置适用于使用此组件的所有主题。

警告

上述示例中使用了明文字符串作为 secret。建议使用 secret 存储来保护 secret，具体方法请参阅此处。

规格元数据字段

字段	必需	详情	示例
`connectionString`	是	Service Bus 的共享访问策略连接字符串。除非使用 Microsoft Entra ID 认证，否则必需。	见上例
`namespaceName`	否	设置 Service Bus 命名空间地址的参数，作为完全限定的域名。使用 Microsoft Entra ID 认证时必需。	`"namespace.servicebus.windows.net"`
`consumerID`	否	消费者 ID 用于将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID (`appID`) 值。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
`timeoutInSec`	否	发送消息和管理操作的超时时间。默认：`60`	`30`
`handlerTimeoutInSec`	否	调用应用程序处理程序的超时时间。默认：`60`	`30`
`lockRenewalInSec`	否	定义缓冲消息锁将被续订的频率。默认：`20`。	`20`
`maxActiveMessages`	否	定义一次处理或缓冲的最大消息数。此值应至少与最大并发处理程序一样大。默认：`1000`	`2000`
`maxConcurrentHandlers`	否	定义最大并发消息处理程序数。默认：`0`（无限制）	`10`
`disableEntityManagement`	否	设置为 true 时，队列和订阅不会自动创建。默认：`"false"`	`"true"`，`"false"`
`defaultMessageTimeToLiveInSec`	否	默认消息生存时间，以秒为单位。仅在订阅创建期间使用。	`10`
`autoDeleteOnIdleInSec`	否	在自动删除空闲订阅之前等待的时间，以秒为单位。仅在订阅创建期间使用。必须为 300 秒或更长。默认：`0`（禁用）	`3600`
`maxDeliveryCount`	否	定义服务器尝试传递消息的次数。仅在订阅创建期间使用。由服务器设置默认值。	`10`
`lockDurationInSec`	否	定义消息在过期前被锁定的时间长度，以秒为单位。仅在订阅创建期间使用。由服务器设置默认值。	`30`
`minConnectionRecoveryInSec`	否	在连接失败的情况下，尝试重新连接到 Azure Service Bus 之前等待的最小间隔（以秒为单位）。默认：`2`	`5`
`maxConnectionRecoveryInSec`	否	在连接失败的情况下，尝试重新连接到 Azure Service Bus 之前等待的最大间隔（以秒为单位）。每次尝试后，组件在最小和最大之间等待一个随机秒数，每次增加。默认：`300`（5 分钟）	`600`
`maxRetriableErrorsPerSec`	否	每秒处理的最大可重试错误数。如果消息因可重试错误而无法处理，组件会在开始处理另一条消息之前添加延迟，以避免立即重新处理失败的消息。默认：`10`	`10`
`publishMaxRetries`	否	当 Azure Service Bus 响应“过于繁忙”以限制消息时的最大重试次数。默认：`5`	`5`
`publishInitialRetryIntervalInMs`	否	当 Azure Service Bus 限制消息时，初始指数退避的时间（以毫秒为单位）。默认：`500`	`500`

Microsoft Entra ID 认证

Azure Service Bus Topics pubsub 组件支持使用所有 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 返回的云事件的 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 broker

请按照此处的说明设置 Azure Service Bus Topics。

1.5 - Azure Service Bus 队列

关于 Azure Service Bus 队列发布/订阅组件的详细文档

组件格式

要配置 Azure Service Bus 队列的发布/订阅功能，创建一个类型为 pubsub.azure.servicebus.queues 的组件。请参考发布/订阅代理组件文件了解 ConsumerID 是如何自动生成的。请阅读发布和订阅指南了解如何创建和应用发布/订阅配置。

该组件在 Azure Service Bus 上使用队列；请查看官方文档了解主题和队列之间的区别。若要使用主题，请参阅 Azure Service Bus 主题发布/订阅组件。

连接字符串认证

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（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者 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 返回的云事件的 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 发布的主题名称相同。例如，如果您在发布/订阅 "myPubsub" 上发布到主题 "orders"，则您的队列必须命名为 "orders"。如果您使用共享访问策略连接到队列，则该策略必须能够“管理”队列。要使用死信队列，该策略必须位于包含主队列和死信队列的 Service Bus 命名空间中。

重试策略和死信队列

默认情况下，Azure Service Bus 队列有一个死信队列。消息会根据 maxDeliveryCount 的值进行重试。默认的 maxDeliveryCount 值为 10，但可以设置为最多 2000。这些重试发生得非常迅速，如果没有成功返回，消息将被放入死信队列。

Dapr 发布/订阅提供了自己的死信队列概念，允许您控制重试策略并通过 Dapr 订阅死信队列。

在 Azure Service Bus 命名空间中设置一个单独的队列作为死信队列，并定义一个弹性策略来定义如何重试。
订阅主题以获取失败的消息并处理它们。

例如，在订阅中设置一个死信队列 orders-dlq 和一个弹性策略，允许您订阅主题 orders-dlq 以处理失败的消息。

有关设置死信队列的更多详细信息，请参阅死信文章。

1.6 - GCP

关于 GCP Pub/Sub 组件的详细文档

创建 Dapr 组件

要配置 GCP pub/sub，需创建一个类型为 pubsub.gcp.pubsub 的组件。参考 pub/sub broker 组件文件了解 ConsumerID 的自动生成方式。查看发布和订阅指南了解如何创建和应用 pub/sub 配置。

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> # 替换
  - name: endpoint # 可选
    value: "http://localhost:8085"
  - name: consumerID # 可选 - 默认为应用程序自身的 ID
    value: <CONSUMER_ID>
  - name: identityProjectId
    value: <IDENTITY_PROJECT_ID> # 替换
  - name: privateKeyId
    value: <PRIVATE_KEY_ID> # 替换
  - name: clientEmail
    value: <CLIENT_EMAIL> # 替换
  - name: clientId
    value: <CLIENT_ID> # 替换
  - 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 # 替换 PROJECT_NAME
  - name: privateKey
    value: <PRIVATE_KEY> # 替换 x509 证书
  - name: disableEntityManagement
    value: "false"
  - name: enableMessageOrdering
    value: "false"
  - name: orderingKey # 可选
    value: <ORDERING_KEY>
  - name: maxReconnectionAttempts # 可选
    value: 30
  - name: connectionRecoveryInSec # 可选
    value: 2
  - name: deadLetterTopic # 可选
    value: <EXISTING_PUBSUB_TOPIC>
  - name: maxDeliveryAttempts # 可选
    value: 5
  - name: maxOutstandingMessages # 可选
    value: 1000
  - name: maxOutstandingBytes # 可选
    value: 1000000000
  - name: maxConcurrentConnections # 可选
    value: 10

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，具体方法请参考这里。

规格元数据字段

字段	必需	详情	示例
projectId	Y	GCP 项目 ID	`myproject-123`
endpoint	N	组件使用的 GCP 端点。仅用于本地开发（例如）与 GCP Pub/Sub Emulator 一起使用。运行 GCP 生产 API 时不需要 `endpoint`。	`"http://localhost:8085"`
`consumerID`	N	Consumer ID 将一个或多个消费者组织成一个组。具有相同 consumer ID 的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID (`appID`) 值。`consumerID` 与请求中提供的 `topic` 一起用于构建 Pub/Sub 订阅 ID	可以设置为字符串值（例如 `"channel1"`）或字符串格式值（例如 `"{podName}"` 等）。查看可以在组件元数据中使用的所有模板标签。
identityProjectId	N	如果 GCP pubsub 项目与身份项目不同，使用此属性指定身份项目	`"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	给定 streaming-pull 连接可以拥有的最大未完成消息数。默认值：`1000`	`50`
maxOutstandingBytes	N	给定 streaming-pull 连接可以拥有的最大未完成字节数。默认值：`1000000000`	`1000000000`
maxConcurrentConnections	N	要维护的最大并发 streaming-pull 连接数。默认值：`10`	`2`
ackDeadline	N	消息确认持续时间截止时间。默认值：`20s`	`1m`

警告

如果 enableMessageOrdering 设置为 “true”，则需要在服务账户上授予 roles/viewer 或 roles/pubsub.viewer 角色，以确保在消息中未嵌入顺序令牌的情况下保证顺序。如果未授予此角色，或调用 Subscription.Config() 失败的任何其他原因，嵌入顺序令牌的排序仍将正常工作。

GCP 凭据

由于 GCP Pub/Sub 组件使用 GCP Go 客户端库，默认情况下它使用 应用程序默认凭据 进行身份验证。这在使用客户端库对 GCP 云服务进行身份验证指南中有进一步解释。

创建 GCP Pub/Sub

对于本地开发，使用 GCP Pub/Sub Emulator 来测试 GCP Pub/Sub 组件。按照这些说明运行 GCP Pub/Sub Emulator。

要在本地使用 Docker 运行 GCP Pub/Sub Emulator，请使用以下 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 Emulator 与您的 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 pubsub 实例的访问。如果使用显式，大多数字段是必需的。隐式依赖于 dapr 在映射到具有访问 pubsub 所需权限的 Google 服务账户 (GSA) 的 Kubernetes 服务账户 (KSA) 下运行。在隐式模式下，只需要 projectId 属性，其他所有都是可选的。

按照此处的说明设置 Google Cloud Pub/Sub 系统。

1.7 - JetStream

NATS JetStream 组件的详细说明文档

组件格式

要配置 JetStream 的发布/订阅功能，需要创建一个类型为 pubsub.jetstream 的组件。请参考 pubsub broker 组件文件以了解 ConsumerID 的自动生成方式。阅读发布和订阅指南以获取创建和应用 pubsub 配置的步骤。

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 # 可选。用于基于令牌的认证。
    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	是	NATS 服务器地址 URL	`"nats://localhost:4222"`
jwt	否	NATS 分布式认证 JWT	`"eyJhbGciOiJ...6yJV_adQssw5c"`
seedKey	否	NATS 分布式认证种子密钥	`"SUACS34K232O...5Z3POU7BNIL4Y"`
tls_client_cert	否	NATS TLS 客户端认证证书	`"/path/to/tls.crt"`
tls_client_key	否	NATS TLS 客户端认证密钥	`"/path/to/tls.key"`
token	否	NATS 基于令牌的认证	`"my-token"`
name	否	NATS 连接名称	`"my-conn-name"`
streamName	否	要绑定的 JetStream 流名称	`"my-stream"`
durableName	否	持久名称	`"my-durable"`
queueGroupName	否	队列组名称	`"my-queue"`
startSequence	否	开始序列	`1`
startTime	否	开始时间，Unix 时间戳格式	`1630349391`
flowControl	否	流量控制	`true`
ackWait	否	确认等待	`10s`
maxDeliver	否	最大投递次数	`15`
backOff	否	退避	`"50ms, 1s, 5s, 10s"`
maxAckPending	否	最大确认待处理	`5000`
replicas	否	副本	`3`
memoryStorage	否	内存存储	`false`
rateLimit	否	速率限制	`1024`
heartbeat	否	心跳	`10s`
ackPolicy	否	确认策略	`explicit`
deliverPolicy	否	其中之一：all, last, new, sequence, time	`all`
domain	否	JetStream Leafonodes	`HUB`
apiPrefix	否	[JetStream Leafnodes]	`PREFIX`

创建 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 --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"

1.8 - KubeMQ

KubeMQ pubsub 组件的详细说明

组件格式

要配置 KubeMQ pub/sub，需创建一个类型为 pubsub.kubemq 的组件。请参阅 pub/sub broker 组件文件了解 ConsumerID 是如何自动生成的。阅读如何发布和订阅指南以了解如何创建和应用 pub/sub 配置。

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	pubsub 类型，true: pubsub 持久化 (EventsStore)，false: pubsub 内存中 (Events)	`true` 或 `false` (默认是 `false`)
consumerID	N	消费者 ID（消费者标签）用于将一个或多个消费者组织成一个组。具有相同消费者 ID 的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供 `consumerID`，Dapr 运行时将其设置为 Dapr 应用程序 ID (`appID`) 值。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看可以在组件元数据中使用的所有模板标签。
clientID	N	客户端 ID 连接的名称	`sub-client-12345`
authToken	N	连接的 Auth JWT 令牌查看 KubeMQ 认证	`ew...`
group	N	用于负载均衡的订阅者组	`g1`
disableReDelivery	N	设置是否在应用程序出错时重新传递消息	`true` 或 `false` (默认是 `false`)

创建 KubeMQ broker

获取 KubeMQ 密钥。
等待电子邮件确认您的密钥

您可以使用 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 密钥。
等待电子邮件确认您的密钥

然后运行以下 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 后，运行端口转发命令：

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

KubeMQ 文档

访问 KubeMQ 文档了解更多信息。

1.9 - MQTT

MQTT pubsub组件的详细文档

组件格式

要配置MQTT pub/sub，您需要创建一个类型为pubsub.mqtt的组件。请参阅pub/sub broker组件文件以了解ConsumerID的自动生成方式。阅读操作指南：发布和订阅指南以了解如何创建和应用pub/sub配置。

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	Y	MQTT broker的地址。可以使用`secretKeyRef`来引用密钥。对于非TLS通信，使用`tcp://` URI方案。对于TLS通信，使用`ssl://` URI方案。	`"tcp://[username][:password]@host.domain[:port]"`
consumerID	N	用于连接到MQTT broker的消费者连接的客户端ID。默认为Dapr应用ID。注意：如果未设置`producerID`，则在此值后附加`-consumer`用于消费者连接	可以设置为字符串值（如上例中的`"channel1"`）或字符串格式值（如`"{podName}"`等）。查看可以在组件元数据中使用的所有模板标签。
producerID	N	用于连接到MQTT broker的生产者连接的客户端ID。默认为`{consumerID}-producer`。	`"myMqttProducerApp"`
qos	N	表示消息的服务质量级别（QoS）（更多信息）。默认为`1`。	`0`, `1`, `2`
retain	N	定义broker是否将消息保存为指定主题的最后已知良好值。默认为`"false"`。	`"true"`, `"false"`
cleanSession	N	如果为`"true"`，则在连接消息中设置`clean_session`标志到MQTT broker（更多信息）。默认为`"false"`。	`"true"`, `"false"`
caCert	使用TLS时必需	用于验证服务器TLS证书的证书颁发机构（CA）证书，格式为PEM。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	使用TLS时必需	TLS客户端证书，格式为PEM。必须与`clientKey`一起使用。	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	使用TLS时必需	TLS客户端密钥，格式为PEM。必须与`clientCert`一起使用。可以使用`secretKeyRef`来引用密钥。	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`

启用消息传递重试

MQTT pub/sub组件不支持内置的重试策略。这意味着sidecar只会向服务发送一次消息。如果服务标记消息为未处理，则消息不会被确认回broker。只有当broker重新发送消息时，才会重试。

要使Dapr使用更复杂的重试策略，可以将重试弹性策略应用于MQTT pub/sub组件。

两种重试方式之间有一个关键区别：

未确认消息的重新传递完全依赖于broker。Dapr不保证这一点。一些broker如emqx、vernemq等支持它，但它不是MQTT3规范的一部分。
使用重试弹性策略使得同一个Dapr sidecar重试重新传递消息。因此是同一个Dapr sidecar和同一个应用接收相同的消息。

使用TLS进行通信

要配置使用TLS进行通信，请确保MQTT broker（例如，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用于唯一标识每个消费者和发布者。在selfhost模式下，调用每个dapr run时使用不同的应用ID即可使它们从同一个共享主题中消费。然而，在Kubernetes上，应用pod的多个实例将共享相同的应用ID，禁止所有实例消费同一个主题。为了解决这个问题，配置组件的consumerID元数据为{uuid}标签，这将在启动时为每个实例提供一个随机生成的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重启时，consumer ID的值都是随机的，因此我们也将cleanSession设置为true。

创建MQTT broker

您可以使用Docker本地运行MQTT broker：

docker run -d -p 1883:1883 -p 9001:9001 --name mqtt eclipse-mosquitto:1.6

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

您可以在kubernetes中使用以下yaml运行MQTT broker：

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

1.10 - 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]"
    # 可选
    - name: retain
      value: "false"
    - name: cleanSession
      value: "false"
    - name: qos
      value: "1"
    - name: consumerID
      value: "channel1"

警告

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

规格元数据字段

字段	必需	详情	示例
`url`	Y	MQTT broker的地址。可以使用`secretKeyRef`来引用密钥。对于非TLS通信，使用`tcp://` URI方案。对于TLS通信，使用`ssl://` URI方案。	`"tcp://[username][:password]@host.domain[:port]"`
`consumerID`	N	用于连接到MQTT broker的客户端ID。默认为Dapr应用ID。	可以设置为字符串值（如上例中的`"channel1"`）或字符串格式值（如`"{podName}"`等）。查看您可以在组件元数据中使用的所有模板标签。
`retain`	N	定义消息是否由broker保存为指定主题的最后已知良好值。默认为`"false"`。	`"true"`，`"false"`
`cleanSession`	N	如果为`"true"`，则在连接消息中设置`clean_session`标志到MQTT broker（更多信息）。默认为`"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 broker（例如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配置
    - 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: qos
      value: 1

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

消费共享主题

在消费共享主题时，每个消费者必须有一个唯一标识符。默认情况下，应用ID用于唯一标识每个消费者和发布者。在selfhost模式下，调用每个dapr run时使用不同的应用ID即可让它们从同一个共享主题中消费。然而，在Kubernetes上，应用Pod的多个实例将共享相同的应用ID，禁止所有实例消费相同的主题。为了解决这个问题，可以在组件的consumerID元数据中配置一个{uuid}标签（这将在启动时为每个实例生成一个随机值）或{podName}（这将在Kubernetes上使用Pod的名称）。例如：

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"

警告

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

请注意，在这种情况下，每次Dapr重启时，consumer ID的值都是随机的，因此您也应该将cleanSession设置为true。

建议使用StatefulSets进行共享订阅。

创建一个MQTT3 broker

您可以使用Docker在本地运行一个像emqx这样的MQTT broker：

docker run -d -p 1883:1883 --name mqtt emqx:latest

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

您可以使用以下yaml在Kubernetes中运行一个MQTT3 broker：

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

1.11 - Pulsar

关于 Pulsar 发布/订阅组件的详细文档

组件格式

要配置 Apache Pulsar 的发布/订阅(pub/sub)功能，需要创建一个类型为 pubsub.pulsar 的组件。请参阅 pub/sub broker 组件文件以了解 ConsumerID 的自动生成方式。阅读操作指南：发布和订阅以了解如何创建和应用 pub/sub 配置。

有关 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"}
        ]
      }

警告

上面的示例使用了明文字符串作为 secret。建议使用 secret 存储来存储 secret。此组件支持将 token 参数和其他敏感数据存储为 Kubernetes Secrets。

规格元数据字段

字段	必需	详情	示例
host	Y	Pulsar broker 的地址。默认值为 `"localhost:6650"`	`"localhost:6650"` 或 `"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 支持两种类型的主题：持久化和非持久化。持久化主题的所有消息都存储在磁盘上，而非持久化主题的数据不会存储到磁盘。
disableBatching	N	是否禁用批处理。启用批处理时，默认批处理延迟为 10 毫秒，默认批处理大小为 1000 条消息，设置 `disableBatching: true` 将使生产者单独发送消息。默认值: `"false"`	`"true"`, `"false"`
receiverQueueSize	N	设置消费者接收队列的大小。控制消费者在被 Dapr 显式调用读取消息之前可以累积多少消息。默认值: `"1000"`	`"1000"`
batchingMaxPublishDelay	N	设置消息发送的批处理时间段（如果启用了批处理消息）。如果设置为非零值，消息将排队直到此时间间隔或 batchingMaxMessages（见下文）或 batchingMaxSize（见下文）。有两种有效格式，一种是带单位后缀的分数格式，另一种是纯数字格式，处理为毫秒。有效的时间单位有 “ns”, “us” (或 “µs”), “ms”, “s”, “m”, “h”。默认值: `"10ms"`	`"10ms"`, `"10"`
batchingMaxMessages	N	设置批处理中允许的最大消息数。如果设置为大于 1 的值，消息将排队直到达到此阈值或 batchingMaxSize（见下文）或批处理间隔已过。默认值: `"1000"`	`"1000"`
batchingMaxSize	N	设置批处理中允许的最大字节数。如果设置为大于 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"`
partitionKey	N	设置消息的路由策略键。默认值: `""`
`maxConcurrentHandlers`	N	定义并发消息处理程序的最大数量。默认值: `100`	`10`

使用 Token 进行身份验证

要使用静态 JWT token 进行 Pulsar 身份验证，可以使用以下元数据字段：

字段	必需	详情	示例
token	N	用于身份验证的 token。	如何创建 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 身份验证结合使用。建议您使用 secret 引用来获取客户端 secret。 Pulsar 的 OAuth2 身份验证器不完全符合 OIDC，因此您有责任确保字段符合要求。例如，发行者 URL 必须使用 https 协议，请求的范围包括 openid 等。如果省略 oauth2TokenCAPEM 字段，则系统的证书池将用于连接到 OAuth2 发行者（如果使用 https）。

字段	必需	详情	示例
oauth2TokenURL	N	请求 OIDC client_credentials token 的 URL。不能为空。	“https://oauth.example.com/o/oauth2/token"`
oauth2TokenCAPEM	N	连接到 OAuth2 发行者的 CA PEM 证书包。如果未定义，将使用系统的证书池。	`"---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"`
oauth2ClientID	N	OIDC 客户端 ID。不能为空。	`"my-client-id"`
oauth2ClientSecret	N	OIDC 客户端 secret。不能为空。	`"my-client-secret"`
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"

启用消息传递重试

Pulsar pub/sub 组件没有内置的重试策略支持。这意味着 sidecar 仅向服务发送一次消息，失败时不会重试。要使 Dapr 使用更复杂的重试策略，您可以将重试弹性策略应用于 Pulsar pub/sub 组件。请注意，这将是同一个 Dapr sidecar 重试将消息重新传递到同一个应用实例，而不是其他实例。

延迟队列

在调用 Pulsar pub/sub 时，可以通过请求 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"
        }
      }'

端到端加密

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

从值启用发布者加密

注意：建议从 secret 引用公钥。

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

从值启用消费者加密

注意：建议从 secret 引用公钥和私钥。

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 pub/sub 时，可以通过请求 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 文档。

1.12 - RabbitMQ

RabbitMQ pubsub 组件的详细说明文档

组件格式

要设置 RabbitMQ 的发布/订阅功能，请创建一个类型为 pubsub.rabbitmq 的组件。请参阅 pub/sub broker 组件文件以了解消费者ID（ConsumerID）是如何自动生成的。阅读 How-to: 发布和订阅指南以了解如何创建和应用 pub/sub 配置。

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 # 可选，是否启用死信
    value: true
  - name: maxLen # 可选，队列中的最大消息数
    value: 3000
  - name: maxLenBytes # 可选，队列的最大字节长度
    value: 10485760
  - name: exchangeKind
    value: fanout
  - name: saslExternal
    value: false
  - name: ttlInSeconds
    value: 60
  - name: clientName
    value: {podName}
  - name: heartBeat
    value: 10s

警告

上述示例使用明文字符串作为 secrets。建议使用 secret 存储来存储 secrets，如此处所述。

规格元数据字段

字段	必需	详情	示例
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` 以使用 secret 引用。	`"-----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"`

使用 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 # 可选，是否启用死信
    value: true
  - name: maxLen # 可选，队列中的最大消息数
    value: 3000
  - name: maxLenBytes # 可选，队列的最大字节长度
    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 值可能不是 secrets，但为了方便起见，它们也可以从 Dapr secret 存储中引用。

启用消息传递重试

RabbitMQ pub/sub 组件不支持内置的重试策略。这意味着 sidecar 仅将消息发送到服务一次。当服务返回结果时，无论消息是否正确处理，消息都将被标记为已消费。请注意，这在所有 Dapr PubSub 组件中都是常见的，而不仅仅是 RabbitMQ。当 autoAck 设置为 false 且 requeueInFailure 设置为 true 时，Dapr 可以尝试第二次重新传递消息。

要使 Dapr 使用更复杂的重试策略，您可以将重试弹性策略应用于 RabbitMQ pub/sub 组件。

两种重试消息的方法之间有一个关键区别：

使用 autoAck = false 和 requeueInFailure = true 时，RabbitMQ 负责重新传递消息，任何订阅者都可以获取重新传递的消息。如果您的消费者有多个实例，那么可能会有另一个消费者获取它。这通常是更好的方法，因为如果存在瞬态故障，另一个工作者更有可能成功处理消息。
使用 Resiliency 使同一个 Dapr sidecar 重试重新传递消息。因此，将是同一个 Dapr sidecar 和同一个应用程序接收相同的消息。

创建 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 交换。

使用优先级队列

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"`
}

// 处理 /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 创建 经典 队列。要创建 仲裁 队列，请将以下元数据添加到您的 pub/sub 订阅

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 运行时必须探测应用程序的健康状况并从 pub/sub 组件中取消订阅。

注意

这种模式将阻止应用程序扩展，因为只有一个实例可以处理负载。虽然对于 Dapr 与遗留或敏感应用程序的集成可能很有趣，但如果您需要可扩展性，您应该考虑允许分布式处理的设计。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: pubsub
spec:
  topic: orders
  routes:
    default: /orders
  pubsubname: order-pub-sub
  metadata:
    singleActiveConsumer: "true"

1.13 - Redis Streams

关于 Redis Streams pubsub 组件的详细文档

组件格式

要设置 Redis Streams pub/sub，创建一个类型为 pubsub.redis 的组件。请参阅 pub/sub broker 组件文件了解 ConsumerID 是如何自动生成的。阅读操作指南：发布和订阅指南了解如何创建和应用 pub/sub 配置。

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"`，可以是多个主机用逗号分隔，或仅一个主机	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`
redisPassword	N	Redis 主机的密码。无默认值。可以是 `secretKeyRef` 以使用密钥引用	`""`, `"KeFg23!"`
redisUsername	N	Redis 主机的用户名。默认为空。确保您的 Redis 服务器版本为 6 或更高，并正确创建了 ACL 规则。	`""`, `"default"`
consumerID	N	消费者组 ID。	可以设置为字符串值（如上例中的 `"channel1"`）或字符串格式值（如 `"{podName}"` 等）。查看您可以在组件元数据中使用的所有模板标签。
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..."`
redeliverInterval	N	检查待处理消息以重新传递的间隔。可以使用 Go duration 字符串（例如 “ms”, “s”, “m”）或毫秒数。默认为 `"60s"`。`"0"` 禁用重新传递。	`"30s"`, `"5000"`
processingTimeout	N	消息在尝试重新传递之前必须挂起的时间量。可以使用 Go duration 字符串（例如 “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	套接字读取的超时时间。如果达到，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"`
failover	N	启用故障转移配置的属性。需要设置 sentinalMasterName。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	Sentinel 主名称。参见 Redis Sentinel 文档	`""`, `"127.0.0.1:6379"`
maxLenApprox	N	流内的最大项目数。当达到指定长度时，旧条目会自动被驱逐，以便流保持恒定大小。默认为无限制。	`"10000"`

创建 Redis 实例

Dapr 可以使用任何 Redis 实例 - 无论是容器化的、在本地开发机器上运行的，还是托管的云服务，只要 Redis 的版本是 5.x 或 6.x。

Dapr CLI 会自动为您创建并设置一个 Redis Streams 实例。当您运行 dapr init 时，Redis 实例将通过 Docker 安装，并且组件文件将创建在默认目录中。($HOME/.dapr/components 目录 (Mac/Linux) 或 %USERPROFILE%\.dapr\components 在 Windows 上)。

您可以使用 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）或 SystemAssigned 托管身份具有 RedisDataOwner 角色权限。如果使用用户分配的身份，您需要指定 azureClientID 属性。

GCP Cloud MemoryStore

注意

Dapr CLI 在 selfhost 模式下作为 dapr init 命令的一部分自动部署本地 redis 实例。

1.14 - RocketMQ

关于 RocketMQ pubsub 组件的详细文档

组件格式

要设置 RocketMQ pub/sub，创建一个类型为 pubsub.rocketmq 的组件。请参阅 pub/sub broker 组件文件了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南了解如何创建和应用 pub/sub 配置。

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

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来存储 secret，如此处所述。

规格元数据字段

字段	必需	详情	默认值	示例
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	向 broker 发送消息的重试次数	`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` 表示 2013 年 12 月 23 日 17:12:01	`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	套接字超时时间，单位为毫秒
pullInterval	N	消息拉取间隔	`100`	`100`
pullBatchSize	N	一次从 broker 拉取的消息数量。如果 `pullBatchSize` 为 `null`，使用 `ConsumerBatchSize`。`pullBatchSize` 范围 `[1, 1024]`	`32`	`10`
pullThresholdForQueue	N	队列级别的流量控制阈值。默认情况下，每个消息队列将缓存最多 1000 条消息。考虑 `PullBatchSize` - 瞬时值可能超过限制。范围：`[1, 65535]`	`1024`	`1000`
pullThresholdForTopic	N	主题级别的流量控制阈值。如果 `pullThresholdForQueue` 不是无限制的，将被 `pullThresholdForTopic` 的值覆盖并计算。例如，如果 `pullThresholdForTopic` 的值为 1000，并且为此消费者分配了 10 个消息队列，则 `pullThresholdForQueue` 将设置为 100。范围：`[1, 6553500]`	`-1(无限制)`	`10`
pullThresholdSizeForQueue	N	限制队列级别的缓存消息大小。考虑 `pullBatchSize` - 瞬时值可能超过限制。消息的大小仅通过消息体测量，因此不准确。范围：`[1, 1024]`	`100`	`100`
pullThresholdSizeForTopic	N	限制主题级别的缓存消息大小。如果 `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 的 broker 发送消息超时，以纳秒为单位。已弃用。	3 秒	`10000000000`
sendTimeOutSec	N	发布消息的超时时间，以秒为单位。如果 `sendTimeOutSec` 为 `null`，则使用 `sendTimeOut`。	3 秒	`3`
mspProperties	N	RocketMQ 消息属性集合中的属性传递给应用程序，数据用 “,” 分隔多个属性		`key,mkey`

出于向后兼容的原因，元数据中的以下值仍然支持，尽管不推荐使用。

字段（支持但已弃用）	必需	详情	示例
groupName	N	RocketMQ 发布者的生产者组名称	`"my_unique_group_name"`
sendTimeOut	N	发布消息的超时时间，以纳秒为单位	`0`
consumerBatchSize	N	一次从 broker 拉取的消息数量	`32`

设置 RocketMQ

请参阅 https://rocketmq.apache.org/docs/quick-start/ 以设置本地 RocketMQ 实例。

每次调用的元数据字段

分区键

在调用 RocketMQ pub/sub 时，可以通过在请求 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"
        }
      }'

队列选择器

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。

1.15 - 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` 引用密钥。使用 `amqp://` URI 方案进行非 TLS 通信。使用 `amqps://` URI 方案进行 TLS 通信。	`"amqp://host.domain[:port]"`
username	Y	连接到代理的用户名。仅在未启用匿名连接或设置为 `false` 时需要。	`default`
password	Y	连接到代理的密码。仅在未启用匿名连接或设置为 `false` 时需要。	`default`
consumerID	N	消费者 ID（消费者标签）用于将一个或多个消费者组织成一个组。具有相同消费者 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 代理。

1.16 - 内存

关于内存 pubsub 组件的详细文档

内存 pub/sub 组件运行在单个 Dapr sidecar 中。这主要用于开发目的。状态不会在多个 sidecar 之间复制，并且在 Dapr sidecar 重启时会丢失。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: pubsub
spec:
  type: pubsub.in-memory
  version: v1
  metadata: []

注意：内存组件不需要特定的元数据即可工作，但 spec.metadata 是必填字段。

2 - 工作流后端组件规范

支持的工作流后端，用于编排和保存工作流状态

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

2.1 - Actor 工作流后端

Actor 工作流后端组件的详细信息

组件格式

在 Dapr 中，Actor 工作流后端是默认的后端。如果没有明确指定工作流后端，系统将自动使用 Actor 后端。

使用 Actor 工作流后端无需定义任何组件，它可以直接使用。

不过，如果您想将 Actor 工作流后端显式定义为一个组件，可以参考以下示例：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: actorbackend
spec:
  type: workflowbackend.actor
  version: v1

3 - Bindings 组件规格

支持与 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	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

3.1 - Apple 推送通知服务绑定说明

关于 Apple 推送通知服务绑定组件的详细文档

组件格式

要配置 Apple 推送通知绑定，请创建一个类型为 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	输出	指定使用哪个 APNs 服务。设置为 `"true"` 使用开发服务，或 `"false"` 使用生产服务。默认值：`"true"`	`"true"`
`key-id`	Y	输出	来自 Apple 开发者门户的私钥标识符	`"private-key-id`"
`team-id`	Y	输出	来自 Apple 开发者门户的组织或作者标识符	`"team-id"`
`private-key`	Y	输出	这是一个 PKCS #8 格式的私钥。建议将私钥存储在 secret 存储中，而不是直接在配置中暴露。详情请参见此处	`"pem file"`

私钥

APNS 绑定需要一个加密私钥来生成 APNS 服务的身份验证令牌。私钥可以从 Apple 开发者门户生成，并以 PKCS #8 文件形式提供，存储在 PEM 格式中。建议将私钥存储在 Dapr 的 secret 存储中，而不是直接在绑定的配置文件中。

以下是 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 推送通知服务的直接接口。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"
}

3.2 - 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: "*****************"

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，详情请参阅此处。

规范元数据字段

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

重要

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

绑定支持

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

create

3.3 - 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" # 请替换为实际的 AWS 区域
  - name: accessKey
    value: "AWS_ACCESS_KEY" # 请替换为实际的 AWS 访问密钥
  - name: secretKey
    value: "AWS_SECRET_KEY" # 请替换为实际的 AWS 秘密访问密钥
  - name: sessionToken
    value: "*****************"
  - name: direction
    value: "input, output"

警告

上述示例中使用了明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`mode`	否	输入	Kinesis 流模式。`shared`- 共享吞吐量，`extended` - 扩展/增强扇出方法。更多详情请参阅此处。默认为 `"shared"`	`"shared"`, `"extended"`
`streamName`	是	输入/输出	AWS Kinesis 流名称	`"stream"`
`consumerName`	是	输入	AWS Kinesis 消费者名称	`"myconsumer"`
`region`	是	输出	部署 AWS Kinesis 实例的特定 AWS 区域	`"us-east-1"`
`accessKey`	是	输出	访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	是	输出	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出	使用的 AWS 会话令牌	`"sessionToken"`
`direction`	否	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

重要

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

绑定支持

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

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

create

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

重要

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

S3 Bucket 创建

使用 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"  # 初始化钩子
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

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

要使用 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 组件，您需要使用现有的 bucket。请按照 AWS 文档创建 bucket。

绑定支持

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

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

创建对象

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

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

{
  "operation": "create",
  "data": "YOUR_CONTENT",
  "metadata": { 
    "storageClass": "STANDARD_IA"
  }
}

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

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

使用预签名 URL 共享对象

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

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 持续时间字符串。

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 - （可选）标记是您希望 Amazon S3 开始列出的位置。Amazon S3 从此指定键之后开始列出。标记可以是 bucket 中的任何键。标记值可以在后续调用中用于请求下一组列表项。
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": ""
}

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

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，详情请参阅此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`region`	否	输出	AWS 区域	`"eu-west-1"`
`accessKey`	否	输出	访问资源的 AWS 访问密钥	`"key"`
`secretKey`	否	输出	访问资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出	使用的 AWS 会话令牌	`"sessionToken"`
`emailFrom`	否	输出	发件人的电子邮件地址	`"me@example.com"`
`emailTo`	否	输出	收件人的电子邮件地址	`"me@example.com"`
`emailCc`	否	输出	抄送的电子邮件地址	`"me@example.com"`
`emailBcc`	否	输出	密送的电子邮件地址	`"me@example.com"`
`subject`	否	输出	电子邮件的主题	`"subject of mail"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规范中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

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

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 字段可以包含多个用分号分隔的电子邮件地址。

3.6 - 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`	是	输出绑定	SNS 主题的 ARN（Amazon Resource Name）	`"arn:::topicarn"`
`region`	是	输出绑定	AWS 的特定区域	`"us-east-1"`
`endpoint`	否	输出绑定	AWS 的特定端点	`"sns.us-east-1.amazonaws.com"`
`accessKey`	是	输出绑定	访问资源的 AWS 访问密钥	`"key"`
`secretKey`	是	输出绑定	访问资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出绑定	使用的 AWS 会话令牌	`"sessionToken"`

重要

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

绑定支持

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

create

3.7 - 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: accessKey
    value: "*****************"
  - name: secretKey
    value: "*****************"
  - name: sessionToken
    value: "*****************"
  - name: direction 
    value: "input, output"

警告

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

规范元数据字段

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

重要

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

绑定支持

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

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

create

3.8 - 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>

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护 secret，具体方法请参见此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`accountName`	Y	输入/输出	Azure 存储账户的名称	`"myexmapleaccount"`
`accountKey`	Y*	输入/输出	Azure 存储账户的访问密钥。仅在不使用 Microsoft Entra ID 认证时需要。	`"access-key"`
`containerName`	Y	输出	要写入的 Blob Storage 容器的名称	`myexamplecontainer`
`endpoint`	N	输入/输出	可选的自定义端点 URL。这在使用 Azurite 模拟器或使用 Azure 存储的自定义域时很有用（尽管这不是官方支持的）。端点必须是完整的基本 URL，包括协议（`http://` 或 `https://`）、IP 或 FQDN，以及可选端口。	`"http://127.0.0.1:10000"`
`decodeBase64`	N	输出	配置在保存到 Blob Storage 之前解码 base64 文件内容。（在保存具有二进制内容的文件时）。默认为 `false`	`true`, `false`
`getBlobRetryCount`	N	输出	指定在从 RetryReader 读取时将进行的最大 HTTP GET 请求次数。默认为 `10`	`1`, `2`
`publicAccessLevel`	N	输出	指定容器中的数据是否可以公开访问以及访问级别（仅在容器由 Dapr 创建时使用）。默认为 `none`	`blob`, `container`, `none`

Microsoft Entra ID 认证

Azure Blob Storage 绑定组件支持使用所有 Microsoft Entra ID 机制进行认证。有关更多信息以及根据选择的 Microsoft Entra ID 认证机制提供的相关组件元数据字段，请参阅认证到 Azure 的文档。

绑定支持

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

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

Blob 存储组件的输入绑定使用 Azure Event Grid触发和推送事件。

请参考响应 Blob 存储事件指南以获取更多设置和信息。

创建 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 并让绑定知道要反序列化它：

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（无内容）和空正文。

列出 blobs

要执行列出 blobs 操作，请使用 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
    }
  }
}

数据参数为：

maxResults - （可选）指定要返回的最大 blob 数量，包括所有 BlobPrefix 元素。如果请求未指定 maxresults，服务器将返回最多 5,000 个项目。
prefix - （可选）过滤结果以仅返回名称以指定前缀开头的 blob。
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 - 下一个标记，可在后续调用中使用以请求下一组列表项。请参阅绑定输入的数据属性上的标记描述。
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"
}

3.9 - 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>"`

绑定支持

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

query

请求示例负载

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

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

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`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 身份认证

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

您可以在下面的部分阅读有关使用 Azure AD 认证设置 Cosmos DB 的更多信息。

绑定支持

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

create

生产环境最佳实践

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

因此，必须采取一些策略来避免同时建立新的 Azure Cosmos DB 连接：

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

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

数据格式

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

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

设置 Cosmos DB 以使用 Azure AD 进行认证

使用 Dapr Cosmos DB 绑定并使用 Azure AD 进行认证时，您需要执行一些额外步骤来设置您的环境。

先决条件：

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

使用 Cosmos DB 绑定时，您不需要像在 Cosmos DB state 存储的情况下那样创建存储过程。

授予您的 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"

3.11 - 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	输出	用于向自定义主题发布 Event Grid 事件的访问密钥	`"accessKey"`
`topicEndpoint`	Y	输出	此输出绑定应发布事件的主题端点	`"topic-endpoint"`
`azureTenantId`	Y	输入	Event Grid 资源的 Azure 租户 ID	`"tenentID"`
`azureSubscriptionId`	Y	输入	Event Grid 资源的 Azure 订阅 ID	`"subscriptionId"`
`azureClientId`	Y	输入	绑定用于创建或更新 Event Grid 事件订阅并验证传入消息的客户端 ID	`"clientId"`
`azureClientSecret`	Y	输入	绑定用于创建或更新 Event Grid 事件订阅并验证传入消息的客户端密钥	`"clientSecret"`
`subscriberEndpoint`	Y	输入	Webhook 的 HTTPS 端点，Event Grid 将事件（格式化为 Cloud Events）发送到此处。如果您不在入口处重写 URL，则应采用以下格式：`"https://[YOUR HOSTNAME]/<path>"` 如果在本地计算机上进行测试，可以使用类似 ngrok 的工具创建公共端点。	`"https://[YOUR HOSTNAME]/<path>"`
`handshakePort`	Y	输入	输入绑定在接收 Webhook 事件时监听的容器端口	`"9000"`
`scope`	Y	输入	需要创建或更新事件订阅的资源标识符。有关更多详细信息，请参阅范围部分	`"/subscriptions/{subscriptionId}/"`
`eventSubscriptionName`	N	输入	事件订阅的名称。事件订阅名称必须在 3 到 64 个字符之间，并且只能使用字母数字字符	`"name"`
`direction`	N	输入/输出	绑定的方向	`"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 存储	Azure Blob 存储绑定 Azure Blob 存储状态存储
Azure Redis 缓存	Redis 绑定 Redis pub/sub
Azure Event Hubs	Azure Event Hubs pub/sub Azure Event Hubs 绑定
Azure IoT Hub	Azure Event Hubs pub/sub Azure Event Hubs 绑定
Azure Service Bus	Azure Service Bus 绑定 Azure Service Bus pub/sub 主题和队列
Azure SignalR 服务	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="..."

# 首先确保 Azure 资源管理器提供程序已为 Event Grid 注册
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 端点用于自定义 webhooks；不接受自签名证书。为了启用从公共互联网到您应用程序的 Dapr sidecar 的流量，您需要启用 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 ingress 控制器安装到您的 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 服务，您可以按照官方 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

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

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

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

排查 Nginx 控制器可能出现的问题

初始部署后，“Dapr 化”的 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..

3.12 - 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: direction
      value: "input, output"

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`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"`
`direction`	N	输入/输出	绑定的方向。	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID 认证

Azure Event Hubs pub/sub 组件支持使用所有 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'
}

3.13 - Azure OpenAI 绑定组件规范

关于 Azure OpenAI 绑定组件的详细文档

组件格式

要设置 Azure OpenAI 绑定组件，请创建一个类型为 bindings.azure.openai 的组件。请参阅本指南了解如何创建和应用绑定配置。有关 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 被直接用作字符串。建议使用密钥存储来保存敏感信息，具体方法请参阅此处。

规范元数据字段

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

Microsoft Entra ID 认证

Azure OpenAI 绑定组件支持使用所有 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: "***"

绑定功能支持

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

completion : Completion API
chat-completion : Chat Completion API
get-embedding : Embedding API

Completion API

要使用提示调用 Completion API，请使用 POST 方法调用 Azure OpenAI 绑定，并使用以下 JSON 正文：

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

数据参数为：

deploymentId - 指定要使用的模型部署 ID 的字符串。
prompt - 指定要生成完成的提示的字符串。
maxTokens - （可选）定义要生成的最大令牌数。Completion API 默认为 16。
temperature - （可选）定义采样温度，范围为 0 到 2。较高的值如 0.8 使输出更随机，而较低的值如 0.2 使其更集中和确定。Completion API 默认为 1.0。
topP - （可选）定义采样温度。Completion API 默认为 1.0。
n - （可选）定义要生成的完成数。Completion API 默认为 1。
presencePenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值根据它们是否出现在文本中对新令牌进行惩罚，从而增加模型谈论新主题的可能性。Completion API 默认为 0.0。
frequencyPenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值根据它们在文本中的现有频率对新令牌进行惩罚，从而减少模型逐字重复同一行的可能性。Completion 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

要执行 chat-completion 操作，请使用 POST 方法调用 Azure OpenAI 绑定，并使用以下 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 - （可选）定义要生成的最大令牌数。Chat Completion API 默认为 16。
temperature - （可选）定义采样温度，范围为 0 到 2。较高的值如 0.8 使输出更随机，而较低的值如 0.2 使其更集中和确定。Chat Completion API 默认为 1.0。
topP - （可选）定义采样温度。Chat Completion API 默认为 1.0。
n - （可选）定义要生成的完成数。Chat Completion API 默认为 1。
presencePenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值根据它们是否出现在文本中对新令牌进行惩罚，从而增加模型谈论新主题的可能性。Chat Completion API 默认为 0.0。
frequencyPenalty - （可选）介于 -2.0 和 2.0 之间的数字。正值根据它们在文本中的现有频率对新令牌进行惩罚，从而减少模型逐字重复同一行的可能性。Chat Completion 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"
    }
  }
]

获取嵌入 API

get-embedding 操作返回给定输入的向量表示，可以被机器学习模型和其他算法轻松使用。要执行 get-embedding 操作，请使用 POST 方法调用 Azure OpenAI 绑定，并使用以下 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,.... (1536 floats total for ada)]

了解更多关于 Azure OpenAI 输出绑定的信息

观看以下社区电话演示以了解更多关于 Azure OpenAI 输出绑定的信息。

3.14 - 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 绑定调用使用 create 操作发布消息时由客户端设置。

发送带有元数据的消息

要在发送消息时设置 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 返回的云事件的 id 属性，应单独处理。
metadata.ScheduledEnqueueTimeUtc 属性支持 RFC1123 和 RFC3339 时间戳格式。

接收带有元数据的消息

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

3.15 - 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  # 可选
    value: "<hub name>"

警告

上述示例使用了明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`connectionString`	Y	输出	Azure SignalR 连接字符串	`"Endpoint=https://<your-azure-signalr>.service.signalr.net;AccessKey=<your-access-key>;Version=1.0;"`
`hub`	N	输出	定义消息将发送到的 hub。hub 可以在发布到输出绑定时动态定义为元数据值（键为 “hub”）	`"myhub"`
`endpoint`	N	输出	Azure SignalR 的端点；如果未包含在 `connectionString` 中或使用 Microsoft Entra ID，则必需	`"https://<your-azure-signalr>.service.signalr.net"`
`accessKey`	N	输出	访问密钥	`"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 集成到解决方案中的更多信息，请查看文档

3.16 - Azure Storage Queues 绑定规范

关于 Azure Storage Queues 绑定组件的详细文档

组件格式

要配置 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: direction 
#   value: "input, output"

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储，如此处所述。

元数据字段说明

字段	必需	绑定支持	详情	示例
`accountName`	Y	输入/输出	Azure Storage 帐户的名称	`"account1"`
`accountKey`	Y*	输入/输出	Azure Storage 帐户的访问密钥。仅在不使用 Microsoft Entra ID 身份验证时需要。	`"access-key"`
`queueName`	Y	输入/输出	Azure Storage 队列的名称	`"myqueue"`
`pollingInterval`	N	输出	设置轮询 Azure Storage Queues 以获取新消息的间隔，作为 Go 持续时间值。默认值：`"10s"`	`"30s"`
`ttlInSeconds`	N	输出	设置默认消息生存时间的参数。如果省略此参数，消息将在 10 分钟后过期。参见此处	`"60"`
`decodeBase64`	N	输入	配置将从 Storage Queue 接收到的 base64 内容解码为字符串。默认为 `false`	`true`, `false`
`encodeBase64`	N	输出	如果启用，则在上传到 Azure storage queues 之前对数据负载进行 base64 编码。默认 `false`。	`true`, `false`
`endpoint`	N	输入/输出	可选的自定义端点 URL。这在使用 Azurite 模拟器或使用 Azure Storage 的自定义域时很有用（尽管这不是官方支持的）。端点必须是完整的基本 URL，包括协议（`http://` 或 `https://`）、IP 或 FQDN，以及可选端口。	`"http://127.0.0.1:10001"` 或 `"https://accountName.queue.example.com"`
`visibilityTimeout`	N	输入	允许设置自定义队列可见性超时，以避免最近失败消息的立即重试。默认为 30 秒。	`"100s"`
`direction`	N	输入/输出	绑定的方向。	`"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"
      }'

3.17 - 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（如果 Worker 是在 Dapr 之外预创建的，则必需）
    - name: workerUrl
      value: ""

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`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。如果 Worker 是在 Dapr 之外预配置的，则必需。	`"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，ID 是 dash.cloudflare.com 之后的十六进制字符串。例如，如果 URL 是 https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef，则 cfAccountID 的值为 456789abcdef8b5588f3d134f74acdef。
cfAPIToken：具有创建和编辑 Workers 权限的 API 令牌。您可以在 Cloudflare 仪表板的 “我的个人资料” 部分的 “API 令牌” 页面中创建它：
1. 点击 “创建令牌”。
2. 选择 “编辑 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 = ""

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

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

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

# 设置为您正在使用的 Dapr 版本
DAPR_VERSION="release-1.15"
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 命令将向您显示完整的 URL，例如 https://mydaprqueue.mydomain.workers.dev。

生成 Ed25519 密钥对

所有 Cloudflare Workers 都在公共互联网监听，因此 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，或者从 Homebrew 安装 OpenSSL 3.0，使用 brew install openssl@3，然后在以下命令中将 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 时需要它（如上一节中的说明）。

警告

保护密钥的私有部分，并将其视为 secret 值！

3.18 - 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

3.19 - 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	输入	使用的有效 cron 调度。详见此处	`"@every 15m"`
`direction`	N	输入	绑定的方向	`"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 点之间，每小时的半点执行一次
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 端点每十五分钟由 Dapr sidecar 调用。

绑定支持

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

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

警告

上述示例使用了明文字符串作为密钥。建议使用密钥存储来保护这些信息，详情请参阅此处。

元数据字段说明

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

绑定支持

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

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

create

3.21 - GCP 存储桶绑定指南

关于 GCP 存储桶绑定组件的详细文档

组件格式

要配置 GCP 存储桶绑定，请创建一个类型为 bindings.gcp.bucket 的组件。请参阅本指南了解如何创建和应用绑定配置。

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

警告

上述示例中使用了明文字符串来存储密钥。建议使用密钥存储来保护这些信息，具体方法请参阅此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`bucket`	Y	输出	存储桶名称	`"mybucket"`
`type`	Y	输出	GCP 凭证类型	`"service_account"`
`project_id`	Y	输出	GCP 项目 ID	`projectId`
`private_key_id`	Y	输出	GCP 私钥 ID	`"privateKeyId"`
`private_key`	Y	输出	GCP 凭证私钥。替换为 x509 证书	`12345-12345`
`client_email`	Y	输出	GCP 客户端邮箱	`"client@email.com"`
`client_id`	Y	输出	GCP 客户端 ID	`0123456789-0123456789`
`auth_uri`	Y	输出	Google 账户 OAuth 端点	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	Y	输出	Google 账户令牌 URI	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	Y	输出	GCP 凭证证书 URL	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	Y	输出	GCP 凭证项目 x509 证书 URL	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`
`decodeBase64`	N	输出	在保存到存储桶之前解码 base64 文件内容的配置。适用于保存二进制内容的文件。`true` 是唯一允许的正值。其他正值变体如 `"True", "1"` 不可接受。默认为 `false`	`true`, `false`
`encodeBase64`	N	输出	在返回内容之前编码 base64 文件内容的配置。适用于打开二进制内容的文件。`true` 是唯一允许的正值。其他正值变体如 `"True", "1"` 不可接受。默认为 `false`	`true`, `false`

绑定支持

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

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

创建文件

要执行创建操作，请使用 POST 方法调用 GCP 存储桶绑定，并使用以下 JSON 正文：

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

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

元数据参数为：

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

示例

将文本保存到随机生成的 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 以处理二进制内容。

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

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

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

响应

响应正文将包含以下 JSON：

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

获取对象

要执行获取文件操作，请使用 POST 方法调用 GCP 存储桶绑定，并使用以下 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>

响应

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

删除对象

要执行删除对象操作，请使用 POST 方法调用 GCP 存储桶绑定，并使用以下 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",
    "delimiter": "i0FvxAn2EOEL6"
  }
}

数据参数为：

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

响应

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

对象列表将作为 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="
	}
]

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

警告

上述示例中使用了明文字符串来存储 secret。建议使用 secret 存储来保护 secret，详情请参阅此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`endpoint`	Y	输出	GraphQL endpoint 字符串，详情见此处	`"http://localhost:4000/graphql/graphql"`
`header:[HEADERKEY]`	N	输出	GraphQL header。在 `name` 中指定 header 键，在 `value` 中指定 header 值。	`"no-cache"` (见上文)
`variable:[VARIABLEKEY]`	N	输出	GraphQL 查询变量。在 `name` 中指定变量名，在 `value` 中指定变量值。	`"123"` (见下文)

GraphQL 绑定内部使用 GraphQL 客户端。

绑定支持

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

query
mutation

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",
}

3.23 - HTTP 绑定规范

关于 HTTP 绑定组件的详细文档

替代方法

服务调用 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" # 可选

元数据字段说明

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

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

Secret 存储引用：

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 用于配置 (m)TLS 认证。使用 mTLS 认证时，必须提供这三个字段。有关更多详细信息，请参阅 mTLS。您也可以仅提供 MTLSRootCA，以启用与自定义 CA 签名证书的 HTTPS 连接。有关更多详细信息，请参阅 HTTPS 部分。

绑定支持

此组件支持具有以下 HTTP 方法/动词的 输出绑定：

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

请求

操作元数据字段

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

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

检索数据

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

{
  "operation": "get"
}

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

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

响应

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

字段	必需	详情	示例
`statusCode`	是	HTTP 状态码	`200`, `404`, `503`
`status`	是	状态描述	`"200 OK"`, `"201 Created"`
首字母大写的字段	否	任何首字母大写的字段都作为请求头发送	`"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 绑定，并使用以下 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 sidecar 信任服务器的 SSL 证书，HTTP 绑定也可以与 HTTPS 端点一起使用。

将绑定 URL 更新为使用 https 而不是 http。
如果需要添加自定义 TLS 证书，请参考如何：在 Dapr sidecar 中安装证书，在 sidecar 中安装 TLS 证书。

示例

更新绑定组件

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

在 sidecar 中安装 TLS 证书

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

以下是 sidecar 作为容器运行时的示例。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" # 将证书文件夹挂载到 sidecar 容器的 /certificates
    environment:
      - "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    depends_on:
      - my-app

sidecar 可以从多种来源读取 TLS 证书。请参阅如何：将 Pod 卷挂载到 Dapr sidecar 以了解更多信息。在此示例中，我们将 TLS 证书存储为 Kubernetes secret。

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

下面的 YAML 是一个 Kubernetes 部署示例，将上述 secret 挂载到 sidecar 并设置 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" # 将证书文件夹挂载到 sidecar 容器的 /certificates
        dapr.io/env: "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    spec:
      volumes:
        - name: cert-vol
          secret:
            secretName: myapp-cert
...

安全地调用绑定

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>

注意

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

使用 mTLS 或启用客户端 TLS 认证以及 HTTPS

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

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

如果提供了文件路径，则读取文件并使用其内容。
如果提供了 PEM 编码字符串，则直接使用该字符串。

当这些字段被配置时，Dapr sidecar 在 TLS 握手过程中使用提供的证书来认证自己。

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

RenegotiateNever
RenegotiateOnceAsClient
RenegotiateFreelyAsClient

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

当服务器需要 mTLS 或客户端 TLS 认证时，可以使用此功能。

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

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来保护这些信息，具体方法请参见此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`url`	Y	输出	InfluxDB 实例的 URL	`"http://localhost:8086"`
`token`	Y	输出	InfluxDB 的授权令牌	`"mytoken"`
`org`	Y	输出	InfluxDB 组织	`"myorg"`
`bucket`	Y	输出	要写入的桶名称	`"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\"
      }"

3.25 - Kafka 绑定规范

关于 Kafka 绑定组件的详细文档

组件格式

要配置 Kafka 绑定，需创建一个 bindings.kafka 类型的组件。请参考本指南了解如何创建和应用绑定配置。有关使用 secretKeyRef 的详细信息，请查看如何在组件中引用 secret的指南。

所有组件的元数据字段值可以使用模板化的元数据值，这些值会在 Dapr sidecar 启动时进行解析。例如，您可以选择使用 {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 的缓存 TTL。
    value: 5m
  - name: escapeHeaders # 可选。
    value: false

规范元数据字段

字段	必需	绑定支持	详情	示例
`topics`	N	输入	逗号分隔的主题字符串。	`"mytopic1,topic2"`
`brokers`	Y	输入/输出	逗号分隔的 Kafka brokers 字符串。	`"localhost:9092,dapr-kafka.myapp.svc.cluster.local:9093"`
`clientID`	N	输入/输出	用户提供的字符串，随每个请求发送到 Kafka brokers 以用于日志记录、调试和审计。	`"my-dapr-app"`
`consumerGroup`	N	输入	监听的 kafka 消费者组。发布到主题的每条记录都会传递给订阅该主题的每个消费者组中的一个消费者。	`"group1"`
`consumeRetryEnabled`	N	输入/输出	通过设置为 `"true"` 启用消费重试。在 Kafka 绑定组件中默认为 `false`。	`"true"`, `"false"`
`publishTopic`	Y	输出	要发布到的主题。	`"mytopic"`
`authRequired`	N	已弃用	启用与 Kafka brokers 的 SASL 认证。	`"true"`, `"false"`
`authType`	Y	输入/输出	配置或禁用认证。支持的值：`none`、`password`、`mtls` 或 `oidc`	`"password"`, `"none"`
`saslUsername`	N	输入/输出	用于认证的 SASL 用户名。仅当 `authRequired` 设置为 `"true"` 时需要。	`"adminuser"`
`saslPassword`	N	输入/输出	用于认证的 SASL 密码。可以是 `secretKeyRef` 以使用secret 引用。仅当 `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` 时需要	“https://identity.example.com/v1/token"
`oidcClientID`	N	输入/输出	在身份提供者中配置的 OAuth2 客户端 ID。当 `authType` 设置为 `oidc` 时需要	`"dapr-kafka"`
`oidcClientSecret`	N	输入/输出	在身份提供者中配置的 OAuth2 客户端 secret：当 `authType` 设置为 `oidc` 时需要	`"KeFg23!"`
`oidcScopes`	N	输入/输出	逗号分隔的 OAuth2/OIDC 范围列表，用于请求访问令牌。当 `authType` 设置为 `oidc` 时推荐。默认为 `"openid"`	`"openid,kafka-prod"`
`version`	N	输入/输出	Kafka 集群版本。默认为 2.0.0。请注意，对于使用 Kafka 的 EventHubs，必须将其设置为 `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 的缓存 TTL。默认为 5 分钟	`5m`
`clientConnectionTopicMetadataRefreshInterval`	N	输入/输出	客户端连接的主题元数据与 broker 刷新的间隔，以 Go 持续时间表示。默认为 `9m`。	`"4m"`
`clientConnectionKeepAliveInterval`	N	输入/输出	客户端连接与 broker 保持活动的最长时间，以 Go 持续时间表示，然后关闭连接。零值（默认）表示无限期保持活动。	`"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 和 Kafka 时，元数据 version 必须设置为 1.0.0。

绑定支持

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

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

create

认证

Kafka 支持多种认证方案，Dapr 支持几种：SASL 密码、mTLS、OIDC/OAuth2。了解更多关于 Kafka 绑定和 Kafka pub/sub 组件的认证方法。

指定分区键

调用 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（无内容）和空响应体。

3.26 - Kitex

Kitex 绑定组件的详细文档

概述

Kitex 绑定主要利用其通用调用功能。可以从官方文档中了解更多关于 Kitex 通用调用的详细信息。目前，Kitex 仅支持 Thrift 通用调用。集成到 components-contrib 的实现采用了二进制通用调用方式。

组件格式

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

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

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

绑定支持

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

get

示例

使用 Kitex 绑定时：

客户端需要传入经过 Thrift 编码的二进制数据
服务器需要是一个 Thrift 服务器。

可以参考 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
}

3.27 - 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	连接的 Auth JWT 令牌。请参阅 KubeMQ 认证	`"ew..."`
`autoAcknowledged`	N	设置是否自动确认接收到的队列消息	`"true"` 或 `"false"` (默认是 `"false"`)
`pollMaxItems`	N	设置每次连接轮询的消息数量	`"1"`
`pollTimeoutSeconds`	N	设置每个轮询间隔的时间（秒）	`"3600"`
`direction`	N	绑定的方向	`"input"`, `"output"`, `"input, output"`

绑定支持

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

创建 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 后，运行端口转发命令：

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

KubeMQ 文档

访问 KubeMQ 文档了解更多信息。

3.28 - 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`	是	输入	要读取事件的 Kubernetes 命名空间	`"default"`
`resyncPeriodInSec`	否	输入	从 Kubernetes API 服务器刷新事件列表的时间间隔，默认为 `"10"` 秒	`"15"`
`direction`	否	输入	绑定的方向	`"input"`
`kubeconfigPath`	否	输入	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",
     ...
   }
 }

事件类型有三种：

Add : 只有 newVal 字段有值，oldVal 字段为空的 v1.Event，event 为 add
Delete : 只有 oldVal 字段有值，newVal 字段为空的 v1.Event，event 为 delete
Update : oldVal 和 newVal 字段都有值，event 为 update

所需权限

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

角色

需要以下形式的规则之一来授予 get, watch 和 list events 的权限。API 组可以根据需要进行限制。

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

角色绑定

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: <NAME>
subjects:
- kind: ServiceAccount
  name: default # 或根据需要更改
roleRef:
  kind: Role
  name: <ROLENAME> # 与上面相同
  apiGroup: ""

3.29 - MQTT3 绑定规范

关于 MQTT3 绑定组件的详细文档

组件格式

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

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"

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护这些信息，具体方法请参见此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`url`	Y	输入/输出	MQTT broker 的地址。可以使用 `secretKeyRef` 来引用 secret。对于非 TLS 通信，使用 `tcp://` URI 方案。对于 TLS 通信，使用 `ssl://` URI 方案。	`"tcp://[username][:password]@host.domain[:port]"`
`topic`	Y	输入/输出	要监听或发送事件的主题。	`"mytopic"`
`consumerID`	Y	输入/输出	用于连接到 MQTT broker 的客户端 ID。	`"myMqttClientApp"`
`retain`	N	输入/输出	定义消息是否由 broker 保存为指定主题的最后已知良好值。默认为 `"false"`。	`"true"`, `"false"`
`cleanSession`	N	输入/输出	如果为 `"true"`，则在连接消息中设置 `clean_session` 标志到 MQTT broker。默认为 `"false"`。	`"true"`, `"false"`
`caCert`	使用 TLS 时必需	输入/输出	用于验证服务器 TLS 证书的 PEM 格式的证书颁发机构 (CA) 证书。	见下例
`clientCert`	使用 TLS 时必需	输入/输出	PEM 格式的 TLS 客户端证书。必须与 `clientKey` 一起使用。	见下例
`clientKey`	使用 TLS 时必需	输入/输出	PEM 格式的 TLS 客户端密钥。必须与 `clientCert` 一起使用。可以使用 `secretKeyRef` 来引用 secret。	见下例
`backOffMaxRetries`	N	输入	在返回错误之前处理消息的最大重试次数。默认为 `"0"`，表示不会尝试重试。可以指定 `"-1"` 表示消息应无限期重试，直到成功处理或应用程序关闭。组件将在重试之间等待 5 秒。	`"3"`
`direction`	N	输入/输出	绑定的方向	`"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 的值可能不是 secret，但为了方便起见，它们也可以从 Dapr secret 存储中引用。

消费共享主题

在消费共享主题时，每个消费者必须有一个唯一的标识符。如果运行多个应用程序实例，可以在组件的 consumerID 元数据中配置一个 {uuid} 标签，这将在启动时为每个实例提供一个随机生成的 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"

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护这些信息，具体方法请参见此处。

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

绑定支持

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

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

create: 发布新消息

每次请求设置主题

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

{
  "operation": "create",
  "metadata": {
    "topic": "myTopic"
  },
  "data": "<h1>测试 Dapr 绑定</h1>这是一个测试。<br>再见！"
}

每次请求设置保留属性

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

{
  "operation": "create",
  "metadata": {
    "retain": "true"
  },
  "data": "<h1>测试 Dapr 绑定</h1>这是一个测试。<br>再见！"
}

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

警告

上面的示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。请注意，您不能仅为用户名/密码使用 secret。如果使用 secret，必须用于完整的连接字符串。

规范元数据字段

字段	必需	绑定支持	详情	示例
`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"`	`"12s"`
`connMaxIdleTime`	N	输出	最大连接空闲时间。格式为持续时间字符串，例如 `"12s"`	`"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 驱动仅支持每个查询/命令一个 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"
}

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

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保存 secret，具体方法请参见此处。

规范元数据字段

通过连接字符串进行身份验证

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

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

通过 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	客户端 secret（应用程序密码）	`"Ecy3X…"`

通过 AWS IAM 进行身份验证

在所有版本的 PostgreSQL 类型组件中支持通过 AWS IAM 进行身份验证。连接字符串中指定的用户必须是数据库中已存在的用户，并且是授予 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’。与访问密钥关联的 secret 密钥	`"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 连接池，因此 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"
}

3.32 - Postmark 绑定说明

关于 Postmark 绑定组件的详细文档

组件格式指南

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

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!" # 可选

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

元数据字段说明

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

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

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

绑定支持

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

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

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

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储，如此处所述。

规范元数据字段

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

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

3.34 - Redis 绑定规范

关于 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>"

警告

上述示例使用了明文字符串作为秘密。建议使用秘密存储，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`redisHost`	Y	输出	Redis 主机地址	`"localhost:6379"`
`redisPassword`	N	输出	Redis 密码	`"password"`
`redisUsername`	N	输出	Redis 主机的用户名。默认为空。确保您的 Redis 服务器版本为 6 或更高，并已正确创建 ACL 规则。	`"username"`
`useEntraID`	N	输出	实现 Azure Cache for Redis 的 EntraID 支持。启用此功能之前：必须以 `"server:port"` 的形式指定 `redisHost` 名称必须启用 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	输出	启用故障转移配置的属性。需要设置 sentinalMasterName。默认为 `"false"`	`"true"`, `"false"`
`sentinelMasterName`	N	输出	哨兵主名称。参见 Redis Sentinel 文档	`""`, `"127.0.0.1:6379"`
`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"
  }
}

带删除标志的请求

{
  "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) 或 %USERPROFILE%\.dapr\components 在 Windows 上)。

您可以使用 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 键设置为 [HOST NAME FROM PREVIOUS STEP]: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

注意

Dapr CLI 在自托管模式下作为 dapr init 命令的一部分自动部署本地 redis 实例。

3.35 - RethinkDB 绑定规范

关于 RethinkDB 绑定组件的详细文档

组件格式

RethinkDB 状态存储支持事务，因此可以用于支持 Dapr actor。Dapr 仅持久化 actor 的当前状态，因此用户无法跟踪 actor 状态随时间的变化。

为了让用户能够跟踪 actor 状态的变化，此绑定利用 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	输入	RethinkDB 服务器地址	`"27.0.0.1:28015"`，`"rethinkdb.default.svc.cluster.local:28015"`
`database`	Y	输入	RethinkDB 数据库名称	`"dapr"`
`direction`	N	输入	绑定的方向	`"input"`

绑定支持

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

3.36 - SFTP 绑定规范

关于安全文件传输协议（SFTP）绑定组件的详细文档

组件格式

要配置 SFTP 绑定，创建一个类型为 bindings.sftp 的组件。请参阅[本指南]({{ ref bindings-overview.md }})以了解如何创建和应用绑定配置。

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

元数据字段说明

字段	必需	绑定支持	详情	示例
`rootPath`	Y	输出	默认工作目录的根路径	`"/path"`
`address`	Y	输出	SFTP 服务器地址	`"localhost:22"`
`username`	Y	输出	用于身份验证的用户名	`"username"`
`password`	N	输出	用户名/密码身份验证的密码	`"password"`
`privateKey`	N	输出	公钥身份验证的私钥	"\|- —–BEGIN OPENSSH PRIVATE KEY—– ***************** —–END OPENSSH PRIVATE KEY—–"
`privateKeyPassphrase`	N	输出	公钥身份验证的私钥密码	`"passphrase"`
`hostPublicKey`	N	输出	主机验证的主机公钥	`"ecdsa-sha2-nistp256 *** root@openssh-server"`
`knownHostsFile`	N	输出	主机验证的已知主机文件	`"/path/file"`
`insecureIgnoreHostKey`	N	输出	允许跳过主机验证。默认为 `"false"`	`"true"`, `"false"`

绑定功能支持

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

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

创建文件

要执行创建文件操作，请使用 POST 方法调用 SFTP 绑定，并提供以下 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 绑定，并提供以下 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 绑定，并提供以下 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 绑定，并提供以下 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（无内容）和空响应正文。

3.37 - 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 存储来保护这些信息，详情请参阅此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`host`	Y	输出	SMTP 服务器的主机地址	`"smtphost"`
`port`	Y	输出	SMTP 服务器的端口号	`"9999"`
`user`	Y	输出	用于认证的用户名	`"user"`
`password`	Y	输出	用户的密码	`"password"`
`skipTLSVerify`	N	输出	如果设置为 true，将跳过对 SMTP 服务器 TLS 证书的验证。默认为 `"false"`	`"true"`, `"false"`
`emailFrom`	N	输出	如果设置，将指定发件人的电子邮件地址。参见示例请求	`"me@example.com"`
`emailTo`	N	输出	如果设置，将指定收件人的电子邮件地址。参见示例请求	`"me@example.com"`
`emailCc`	N	输出	如果设置，将指定抄送的电子邮件地址。参见示例请求	`"me@example.com"`
`emailBcc`	N	输出	如果设置，将指定密送的电子邮件地址。参见示例请求	`"me@example.com"`
`subject`	N	输出	如果设置，将指定电子邮件的主题。参见示例请求	`"subject of mail"`
`priority`	N	输出	如果设置，将指定电子邮件的优先级 (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": "Email subject",
    "priority": "1"
  },
  "data": "Testing Dapr SMTP Binding"
}

3.38 - Twilio SendGrid 绑定规范

关于 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" # 可选
  - name: emailFromName
    value: "test app" # 可选
  - name: emailTo
    value: "dave@dapr.io" # 可选
  - name: emailToName
    value: "dave" # 可选
  - name: subject
    value: "Hello!" # 可选
  - name: emailCc
    value: "jill@dapr.io" # 可选
  - name: emailBcc
    value: "bob@dapr.io" # 可选
  - name: dynamicTemplateId
    value: "d-123456789" # 可选
  - name: dynamicTemplateData
    value: '{"customer":{"name":"John Smith"}}' # 可选
  - name: apiKey
    value: "YOUR_API_KEY" # 必需，这是您的 SendGrid 密钥

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，具体方法请参见此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`apiKey`	Y	输出	SendGrid API 密钥，应视为敏感信息	`"apikey"`
`emailFrom`	N	输出	若设置，指定电子邮件的“发件人”地址。仅允许一个电子邮件地址。可选字段，参见下文	`"me@example.com"`
`emailFromName`	N	输出	若设置，指定电子邮件的“发件人”名称。可选字段，参见下文	`"me"`
`emailTo`	N	输出	若设置，指定电子邮件的“收件人”地址。仅允许一个电子邮件地址。可选字段，参见下文	`"me@example.com"`
`emailToName`	N	输出	若设置，指定电子邮件的“收件人”名称。可选字段，参见下文	`"me"`
`emailCc`	N	输出	若设置，指定电子邮件的“抄送”地址。仅允许一个电子邮件地址。可选字段，参见下文	`"me@example.com"`
`emailBcc`	N	输出	若设置，指定电子邮件的“密件抄送”地址。仅允许一个电子邮件地址。可选字段，参见下文	`"me@example.com"`
`subject`	N	输出	若设置，指定电子邮件的主题。可选字段，参见下文	`"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\"}}"
  }
}

3.39 - 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 # 必需。
    value: "111-111-1111"
  - name: fromNumber # 必需。
    value: "222-222-2222"
  - name: accountSid # 必需。
    value: "*****************"
  - name: authToken # 必需。
    value: "*****************"

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，如此处所述。

元数据字段说明

字段	必需	绑定支持	详情	示例
`toNumber`	Y	输出	发送短信的目标号码	`"111-111-1111"`
`fromNumber`	Y	输出	发送者的电话号码	`"222-222-2222"`
`accountSid`	Y	输出	Twilio 账户 SID	`"account sid"`
`authToken`	Y	输出	Twilio 认证令牌	`"auth token"`

支持的绑定功能

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

create

3.40 - 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 语言运行时分发已经编译为 WASI 的解释器（包括 PHP、Python 和 Ruby）。

Wasm 二进制文件可以从 URL 加载。例如，URL file://rewrite.wasm 会从进程的当前目录加载 rewrite.wasm。在 Kubernetes 上，请参阅如何：将 Pod 卷挂载到 Dapr sidecar以配置可以包含 Wasm 二进制文件的文件系统挂载。也可以从远程 URL 获取 Wasm 二进制文件。在这种情况下，URL 必须准确指向一个 Wasm 二进制文件。例如：

http://example.com/rewrite.wasm，或
https://example.com/rewrite.wasm。

Dapr 使用 wazero 来运行这些二进制文件，因为它没有依赖项。这允许使用 WebAssembly 而无需安装过程，除了 Dapr 本身。

Wasm 输出绑定支持使用 wasi-http 规范进行 HTTP 客户端调用。您可以在此处找到用多种语言进行 HTTP 调用的示例代码：

注意

如果您只想进行 HTTP 调用，使用 service-invocation 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"
}'

3.41 - 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	输入	Zeebe 网关地址	`"localhost:26500"`
`gatewayKeepAlive`	N	输入	设置发送到网关的保活消息频率，默认为 45 秒	`"45s"`
`usePlainTextConnection`	N	输入	是否使用纯文本连接	`"true"`, `"false"`
`caCertificatePath`	N	输入	CA 证书的路径	`"/path/to/ca-cert"`
`workerName`	N	输入	激活作业的 worker 名称，主要用于日志记录	`"products-worker"`
`workerTimeout`	N	输入	在此调用后返回的作业在超时之前不会被另一个调用激活，默认为 5 分钟	`"5m"`
`requestTimeout`	N	输入	请求将在至少一个作业被激活或达到 requestTimeout 后完成。如果 requestTimeout = 0，则使用默认超时。如果 requestTimeout < 0，则禁用长轮询，即使没有作业被激活，请求也会立即完成。默认为 10 秒	`"30s"`
`jobType`	Y	输入	在 BPMN 流程中定义的作业类型（例如 `<zeebe:taskDefinition type="fetch-products" />`）	`"fetch-products"`
`maxJobsActive`	N	输入	设置此 worker 同时激活的最大作业数，默认为 32	`"32"`
`concurrency`	N	输入	完成作业的最大并发 goroutines 数量，默认为 4	`"4"`
`pollInterval`	N	输入	设置轮询新作业的最大间隔，默认为 100 毫秒	`"100ms"`
`pollThreshold`	N	输入	设置缓冲激活作业的阈值以便轮询新作业，即阈值 * maxJobsActive，默认为 0.3	`"0.3"`
`fetchVariables`	N	输入	要获取的作业变量列表；如果为空，则在作业激活时返回作用域内的所有可见变量	`"productId"`, `"productName"`, `"productKey"`
`autocomplete`	N	输入	指示作业是否应自动完成。如果未设置，默认情况下所有作业将自动完成。如果 worker 应手动完成或因业务错误或事件而失败作业，请禁用此选项	`"true"`, `"false"`
`retryBackOff`	N	输入	作业失败时下次重试的回退超时	`15s`
`direction`	N	输入	绑定的方向	`"input"`

绑定支持

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

输入绑定

变量

Zeebe 流程引擎处理流程状态，并可以在流程实例化时传递或在流程执行期间更新或创建流程变量。这些变量可以通过在 fetchVariables 元数据字段中定义变量名称的逗号分隔列表传递给注册的作业 worker。然后，流程引擎将这些变量及其当前值传递给作业 worker 实现。

如果绑定注册了三个变量 productId、productName 和 productKey，则 worker 将接收到以下 JSON 主体：

{
  "productId": "some-product-id",
  "productName": "some-product-name",
  "productKey": "some-product-key"
}

注意：如果未传递 fetchVariables 元数据字段，则所有流程变量将传递给 worker。

头信息

Zeebe 流程引擎能够将自定义任务头信息传递给作业 worker。这些头信息可以为每个服务任务定义。任务头信息将作为元数据（HTTP 头信息）由绑定传递给作业 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 纪元时间戳发送
X-Zeebe-Autocomplete	bool	在绑定元数据中定义的自动完成状态

3.42 - Zeebe 命令绑定说明

关于 Zeebe 命令绑定组件的详细文档

组件格式说明

要配置 Zeebe 命令绑定，请创建一个类型为 bindings.zeebe.command 的组件。请参考本指南了解如何创建和应用绑定配置。

有关 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"

元数据字段说明

字段	必需	绑定支持	详情	示例
`gatewayAddr`	Y	输出	Zeebe 网关地址	`"localhost:26500"`
`gatewayKeepAlive`	N	输出	设置发送到网关的保活消息的频率。默认为 45 秒	`"45s"`
`usePlainTextConnection`	N	输出	是否使用纯文本连接	`"true"`, `"false"`
`caCertificatePath`	N	输出	CA 证书的路径	`"/path/to/ca-cert"`

绑定支持

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

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

输出绑定

Zeebe 在此绑定中使用的客户端底层依赖 gRPC。请查阅 gRPC API 参考以获取更多信息。

topology

topology 操作用于获取网关所属集群的当前拓扑。

要执行 topology 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {},
  "operation": "topology"
}

响应

绑定返回一个包含以下信息的 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 的端口
- partitions - 此 broker 管理或复制的分区列表
  - partitionId - 分区的唯一 ID
  - role - broker 在此分区中的角色
  - health - 分区的健康状况
- version - broker 版本
clusterSize - 集群中的节点数量
partitionsCount - 集群中分布的分区数量
replicationFactor - 集群配置的复制因子
gatewayVersion - 网关版本

deploy-process

deploy-process 的弃用别名为 ‘deploy-resource’。

deploy-resource

deploy-resource 操作用于将单个资源部署到 Zeebe。资源可以是流程（BPMN）或决策和决策需求（DMN）。

要执行 deploy-resource 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": "YOUR_FILE_CONTENT",
  "metadata": {
    "fileName": "products-process.bpmn"
  },
  "operation": "deploy-resource"
}

元数据参数为：

fileName - 资源文件的名称

响应

绑定返回一个包含以下信息的 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 命令绑定，并使用以下 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，则使用网关中配置的通用 requestTimeout。
fetchVariables - （可选，仅在 withResult=true 时使用）要包含在响应的 variables 属性中的变量名称列表。如果为空，将返回根范围内的所有可见变量。

响应

绑定返回一个包含以下信息的 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 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "processInstanceKey": 2251799813687851
  },
  "operation": "cancel-instance"
}

数据参数为：

processInstanceKey - 流程实例键

响应

绑定不返回响应正文。

set-variables

set-variables 操作用于为元素实例（例如流程实例、流程元素实例）创建或更新变量。

要执行 set-variables 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 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，变量 { "foo" : 5 }，并且 local 为 true，那么范围 1 将保持不变，范围 2 将变为 { "bar" : 1, "foo" 5 }。然而，如果 local 为 false，那么范围 1 将为 { "foo": 5 }，范围 2 将为 { "bar" : 1 }
variables - 描述变量的键值对的 JSON 序列化文档；文档的根必须是一个对象

响应

绑定返回一个包含以下信息的 JSON：

{
  "key": 2251799813687896
}

响应值为：

key - 设置变量命令的唯一键

resolve-incident

resolve-incident 操作用于解决一个事件。

要执行 resolve-incident 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "incidentKey": 2251799813686123
  },
  "operation": "resolve-incident"
}

数据参数为：

incidentKey - 要解决的事件的唯一 ID

响应

绑定不返回响应正文。

publish-message

publish-message 操作用于发布一条消息。消息发布到从其关联键计算出的特定分区。

要执行 publish-message 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 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” ] 将不是有效的

响应

绑定返回一个包含以下信息的 JSON：

{
  "key": 2251799813688225
}

响应值为：

key - 发布的消息的唯一 ID

activate-jobs

activate-jobs 操作以轮询方式遍历所有已知分区并激活最多请求的最大数量，并在激活时将其流式传输回客户端。

要执行 activate-jobs 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 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，则禁用长轮询，并且请求立即完成，即使没有作业被激活。

响应

绑定返回一个包含以下信息的 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 纪元时间戳发送
variables - 在激活时计算，由任务范围内的所有可见变量组成；作为序列化的 JSON 文档返回

complete-job

complete-job 操作使用给定的负载完成作业，从而允许完成关联的服务任务。

要执行 complete-job 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813686172,
    "variables": {
      "productId": "some-product-id",
      "productName": "some-product-name",
      "productKey": "some-product-key"
    }
  },
  "operation": "complete-job"
}

数据参数为：

jobKey - 唯一的作业标识符，从激活作业响应中获得
variables - （可选）表示当前任务范围内变量的 JSON 文档

响应

绑定不返回响应正文。

fail-job

fail-job 操作将作业标记为失败；如果重试参数为正，则作业将立即可再次激活，并且工作者可以再次尝试处理它。然而，如果为零或负数，则会引发事件，并标记为给定的错误消息，并且作业在事件解决之前不会被激活。

要执行 fail-job 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 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 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

update-job-retries

update-job-retries 操作用于更新作业剩余的重试次数。这对于作业用尽重试次数的情况特别有用，假设底层问题已解决。

要执行 update-job-retries 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 JSON 正文：

{
  "data": {
    "jobKey": 2251799813686172,
    "retries": 10
  },
  "operation": "update-job-retries"
}

数据参数为：

jobKey - 通过 activate-jobs 操作获得的唯一作业标识符
retries - 作业的新重试次数；必须为正

响应

绑定不返回响应正文。

throw-error

throw-error 操作用于抛出一个错误，以指示在处理作业时发生了业务错误。错误由错误代码标识，并由流程中具有相同错误代码的错误捕获事件处理。

要执行 throw-error 操作，请通过 POST 方法调用 Zeebe 命令绑定，并使用以下 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 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

3.43 - 阿里云 Tablestore 绑定组件规范

关于阿里云 Tablestore 绑定组件的详细文档

组件格式

要配置阿里云 Tablestore 绑定组件，请创建一个类型为 bindings.alicloud.tablestore 的组件。请参阅本指南了解如何创建和应用 secretstore 配置。有关如何引用 secrets以获取和使用 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]"

警告

上述示例中使用了明文字符串作为机密信息。建议使用 secret store 来存储机密信息，详情请参阅此处。

元数据字段说明

字段	必需	绑定支持	说明	示例
`endpoint`	是	输出	阿里云 Tablestore 的访问端点。	https://tablestore-cn-hangzhou.aliyuncs.com
`accessKeyID`	是	输出	访问密钥 ID。
`accessKey`	是	输出	访问密钥。
`instanceName`	是	输出	实例名称。
`tableName`	是	输出	表名称。

绑定功能支持

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

create: 创建对象

创建对象

要执行创建对象操作，请使用 POST 方法调用绑定，并提供以下 JSON 正文：

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

注意

请确保 metadata.primaryKeys 字段是必填项。

删除对象

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

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

注意

请确保 metadata.primaryKeys 字段是必填项。

列出对象

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

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

注意

请确保 metadata.primaryKeys 字段是必填项。

获取对象

要执行获取对象操作，请使用 POST 方法调用绑定，并提供以下 JSON 正文：

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

注意

请确保 metadata.primaryKeys 字段是必填项。

3.44 - 阿里云钉钉绑定组件规范

关于阿里云钉钉绑定组件的详细文档

配置 Dapr 组件

要配置阿里云钉钉绑定组件，请创建一个类型为 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"

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来存储密钥，详情请参阅此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`id`	是	输入/输出	唯一标识符	`"test_webhook_id"`
`url`	是	输入/输出	钉钉的 Webhook 地址	`"https://oapi.dingtalk.com/robot/send?access_token=******"`
`secret`	否	输入/输出	钉钉 Webhook 的密钥	`"****************"`
`direction`	否	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

绑定支持

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

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

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

3.45 - 阿里云对象存储服务绑定指南

关于阿里云对象存储绑定组件的详细文档

组件格式

要配置阿里云对象存储绑定，请创建一个类型为 bindings.alicloud.oss 的组件。请参阅本指南了解如何创建和应用secretstore配置。有关如何引用secrets以检索和使用Dapr组件的secret，请参阅此指南。

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

警告

上述示例中使用了明文字符串作为secrets。建议使用secret store来存储secrets，详情请见此处。

元数据字段说明

字段	必需	绑定功能	详情	示例
`endpoint`	是	输出	阿里云OSS端点。	https://oss-cn-hangzhou.aliyuncs.com
`accessKeyID`	是	输出	访问密钥ID凭证。
`accessKey`	是	输出	访问密钥凭证。
`bucket`	是	输出	存储桶的名称。

绑定功能

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

create: 创建对象

创建对象

要执行创建对象操作，请使用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"
}

3.46 - 阿里云日志存储服务绑定指南

关于阿里云日志存储绑定组件的详细文档

组件配置格式

要配置一个阿里云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`	是	输出	访问密钥ID凭证。
`AccessKeySecret`	是	输出	访问密钥凭证secret
`Endpoint`	是	输出	阿里云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生产者API是异步的，因此此绑定没有直接响应（没有回调接口来接收成功或失败的响应，只有在失败时会记录到控制台日志）。

3.47 - 本地存储绑定规范

关于本地存储绑定组件的详细文档

组件格式

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

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

元数据字段规范

字段	必需	绑定支持	详情	示例
`rootPath`	Y	输出	文件可读写的根路径	`"/temp/files"`

绑定支持

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

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

创建文件

要执行创建文件操作，使用 POST 方法调用本地存储绑定，并使用以下 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\": { \"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 方法调用本地存储绑定，并使用以下 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 方法调用本地存储绑定，并使用以下 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 方法调用本地存储绑定，并使用以下 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（无内容）和空正文。

元数据信息

默认情况下，本地存储输出绑定会自动生成一个 UUID 作为文件名。您可以在消息的元数据属性中自定义文件名。

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

3.48 - 华为 OBS 绑定规范

关于华为 OBS 绑定组件的详细文档

组件格式

要配置华为对象存储服务（OBS）的输出绑定，创建一个类型为 bindings.huawei.obs 的组件。请参阅本指南以了解如何创建和应用绑定配置。

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

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`bucket`	Y	输出	要写入的华为 OBS 存储桶名称	`"My-OBS-Bucket"`
`endpoint`	Y	输出	特定的华为 OBS 端点	`"obs.cn-north-4.myhuaweicloud.com"`
`accessKey`	Y	输出	访问此资源的华为访问密钥（AK）	`"************"`
`secretKey`	Y	输出	访问此资源的华为密钥（SK）	`"************"`
`region`	N	输出	存储桶的特定华为区域	`"cn-north-4"`

绑定功能

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

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

创建文件

要执行创建操作，请使用 POST 方法调用华为 OBS 绑定，并使用以下 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 字段。只有在启用存储桶版本控制时，versionId 才会返回值，否则为空字符串。

上传文件

要上传二进制文件（例如，.jpg，.zip），请使用 POST 方法调用华为 OBS 绑定，并使用以下 JSON 正文：

注意：默认情况下，会生成一个随机 UUID，如果您不指定 key。请参阅下面的示例以获取元数据支持以设置目标文件名。此 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 字段。只有在启用存储桶版本控制时，versionId 才会返回值，否则为空字符串。

获取对象

要执行获取文件操作，请使用 POST 方法调用华为 OBS 绑定，并使用以下 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 方法调用华为 OBS 绑定，并使用以下 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 方法调用华为 OBS 绑定，并使用以下 JSON 正文：

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

数据参数为：

maxResults - （可选）设置响应中返回的最大键数。默认情况下，操作最多返回 1,000 个键名。响应可能包含更少的键，但绝不会包含更多。
prefix - （可选）限制响应为以指定前缀开头的键。
marker - （可选）标记是您希望华为 OBS 开始列出的位置。华为 OBS 从此指定键之后开始列出。标记可以是存储桶中的任何键。然后可以在后续调用中使用标记值来请求下一组列表项。
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>

响应

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

4 - 状态存储组件说明

支持与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，则可以用于Dapr的actor模型。

Generic

Component	CRUD	Transactional	ETag	TTL	Actors	Query	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
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	Query	Status	Component version	Since runtime version
AliCloud TableStore	✅		✅				Alpha	v1	1.3

Amazon Web Services (AWS)

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
AWS DynamoDB	✅	✅	✅	✅	✅		Stable	v1	1.10

Cloudflare

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
Cloudflare Workers KV	✅			✅			Beta	v1	1.10

Google Cloud Platform (GCP)

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
GCP Firestore	✅						Stable	v1	1.11

Microsoft Azure

Component	CRUD	Transactional	ETag	TTL	Actors	Query	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	✅	✅	✅	✅	✅		Stable	v1	1.5

Oracle Cloud

Component	CRUD	Transactional	ETag	TTL	Actors	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

4.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> # 可选

警告

上述示例使用未加密的字符串作为 secret。建议使用 secret 存储来保护 secret，如此处所述。

配置元数据字段

字段	必需	详情	示例
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

4.2 - 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: partitionKey
    value: "ContractID" # 可选
  # 如果希望将 AWS DynamoDB 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

主键

要将 DynamoDB 用作 Dapr 状态存储，表必须有一个名为 key 的主键。请参考分区键部分以了解如何更改此设置。

规格元数据字段

字段	必需	详情	示例
table	Y	要使用的 DynamoDB 表的名称	`"Contracts"`
accessKey	N	具有适当权限的 AWS 账户的 ID，可使用 `secretKeyRef` 来引用 secret	`"AKIAIOSFODNN7EXAMPLE"`
secretKey	N	AWS 用户的 secret，可使用 `secretKeyRef` 来引用 secret	`"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"`
partitionKey	N	表的主键或分区键属性名称。此字段用于替换默认的主键属性名称 `"key"`。请参阅分区键部分。	`"ContractID"`
actorStateStore	N	将此状态存储视为 actor 的状态存储。默认为 “false”	`"true"`, `"false"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规格中提供 AWS 访问密钥、secret 密钥和令牌。

设置 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"
        }
    }
}

4.3 - Azure Blob 存储

有关 Azure Blob 存储状态存储组件的详细信息

组件格式

要设置 Azure Blob 存储状态存储，请创建一个类型为 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]"

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来存储 secret，如此处所述。

版本控制

Dapr 提供了两个版本的 Azure Blob 存储状态存储组件：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 状态的容器名称。如果不存在，Blob 存储状态提供者会自动为您创建	`"container"`
`azureEnvironment`	N	如果使用不同的 Azure 云，则为 Azure 环境的可选名称	`"AZUREPUBLICCLOUD"` (默认值), `"AZURECHINACLOUD"`, `"AZUREUSGOVERNMENTCLOUD"`
`endpoint`	N	可选的自定义端点 URL。这在使用 Azurite 模拟器或使用 Azure 存储的自定义域时很有用（尽管这不是官方支持的）。端点必须是完整的基本 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 存储

按照 Azure 文档中的说明创建 Azure 存储帐户。

如果您希望为 Dapr 创建一个容器，可以事先进行。然而，如果不存在，Blob 存储状态提供者会自动为您创建。

为了将 Azure Blob 存储设置为状态存储，您将需要以下属性：

accountName: 存储帐户名称。例如：mystorageaccount。
accountKey: 主存储或辅助存储帐户密钥。
containerName: 用于 Dapr 状态的容器名称。如果不存在，Blob 存储状态提供者会自动为您创建。

使用 Microsoft Entra ID 进行身份验证

此组件支持使用 Microsoft Entra ID 进行身份验证，作为使用帐户密钥的替代方案。无论何时可能，建议您在生产系统中使用 Microsoft Entra ID 进行身份验证，以利用更好的安全性、精细的访问控制以及在 Azure 上运行的应用程序中使用托管身份的能力。

以下脚本针对 bash 或 zsh shell 进行了优化，并需要安装以下应用程序：
Azure CLI
jq
您还必须在 Azure CLI 中通过 Azure 进行身份验证。

要开始使用 Microsoft Entra ID 进行 Blob 存储状态存储组件的身份验证，请确保您已创建 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，为我们的服务主体分配一个角色，以便它可以访问存储帐户内的数据。
在这种情况下，您正在分配“存储 Blob 数据贡献者”角色，该角色具有广泛的访问权限；根据您的应用程序，也可以使用其他更具限制性的角色。

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 存储状态存储应用于 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"
        }
      ]'

这将在容器中创建一个以 key 为文件名、value 为文件内容的 Blob 文件。

并发

Azure Blob 存储状态并发是通过使用 ETag 实现的，具体请参见 Azure Blob 存储文档。

4.4 - 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 建立新连接：

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

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 来满足负载。

注意

此特定优化仅在您保存大型对象到状态时才有意义。执行压缩和解压缩的性能和内存权衡需要对您的用例有意义。此外，一旦数据保存到状态，它就不可读，也不可查询。仅当您将大型状态对象保存为键值对时，才应采用此优化。

4.5 - Azure 表存储

详细介绍 Azure 表存储状态组件，该组件可用于连接到 Cosmos DB 表 API 和 Azure 表

组件格式

要配置 Azure 表存储状态组件，请创建一个类型为 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

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护 secret，详情请参阅此处。

元数据字段说明

字段	必需	详情	示例
`accountName`	是	存储帐户名称	`"mystorageaccount"`
`accountKey`	是	主存储或辅助存储密钥	`"key"`
`tableName`	是	用于 Dapr 状态的表名。如果不存在，将自动创建	`"table"`
`cosmosDbMode`	否	启用后，将连接到 Cosmos DB 表 API 而非 Azure 表。默认为 `false`	`"false"`
`serviceURL`	否	完整的存储服务端点 URL，适用于非公共云的 Azure 环境	`"https://mystorageaccount.table.core.windows.net/"`
`skipCreateTable`	否	跳过检查并在必要时创建指定的存储表，适用于最低权限的活动目录身份验证。默认为 `false`	`"true"`

Microsoft Entra ID 认证

Azure Cosmos DB 状态组件支持所有 Microsoft Entra ID 认证机制。有关更多信息以及如何选择适合的组件元数据字段，请参阅Azure 认证文档。

您可以在下面的部分了解更多关于使用 Microsoft Entra ID 认证设置 Cosmos DB 的信息。

选项 1：设置 Azure 表存储

按照说明从 Azure 文档中了解如何创建 Azure 存储帐户。

如果您希望为 Dapr 创建一个表，可以提前进行。然而，表存储状态组件会自动为您创建一个表（如果它不存在），除非启用了 skipCreateTable 选项。

要将 Azure 表存储设置为状态存储，您需要以下属性：

AccountName：存储帐户名称，例如：mystorageaccount。
AccountKey：主存储或辅助存储密钥。如果使用 Microsoft Entra ID 认证，请跳过此步骤。
TableName：用于 Dapr 状态的表名。如果不存在，将自动创建，除非启用了 skipCreateTable 选项。
cosmosDbMode：设置为 false 以连接到 Azure 表。

选项 2：设置 Azure Cosmos DB 表 API

按照说明从 Azure 文档中了解如何使用表 API 创建 Cosmos DB 帐户。

如果您希望为 Dapr 创建一个表，可以提前进行。然而，表存储状态组件会自动为您创建一个表（如果它不存在），除非启用了 skipCreateTable 选项。

要将 Azure Cosmos DB 表 API 设置为状态存储，您需要以下属性：

AccountName：Cosmos DB 帐户名称，例如：mycosmosaccount。
AccountKey：Cosmos DB 主密钥。如果使用 Microsoft Entra ID 认证，请跳过此步骤。
TableName：用于 Dapr 状态的表名。如果不存在，将自动创建，除非启用了 skipCreateTable 选项。
cosmosDbMode：设置为 true 以连接到 Cosmos DB 表 API。

分区

Azure 表存储状态组件使用请求中提供的 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 表存储状态的并发通过使用 ETag 实现，具体请参阅官方文档。

4.6 - Cassandra

Cassandra 状态存储组件的详细信息

组件格式

要配置 Cassandra 状态存储组件，请创建一个类型为 state.cassandra 的组件。请参阅本指南以了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cassandra
  version: v1
  metadata:
  - name: hosts
    value: <用逗号分隔的主机列表> # 必需。示例：cassandra.cassandra.svc.cluster.local
  - name: username
    value: <用户名> # 可选。默认值：""
  - name: password
    value: <密码> # 可选。默认值：""
  - name: consistency
    value: <一致性级别> # 可选。默认值："All"
  - name: table
    value: <表名> # 可选。默认值："items"
  - name: keyspace
    value: <键空间> # 可选。默认值："dapr"
  - name: protoVersion
    value: <协议版本> # 可选。默认值："4"
  - name: replicationFactor
    value: <复制因子> # 可选。默认值："1"

警告

上述示例中使用了明文字符串来存储秘密信息。建议使用秘密存储来保护这些信息，详情请参阅此处。

规格元数据字段

字段	必需	说明	示例
hosts	是	用逗号分隔的主机列表	`"cassandra.cassandra.svc.cluster.local"`。
port	否	通信端口。默认值为 `"9042"`	`"9042"`
username	是	数据库用户的用户名。无默认值	`"user"`
password	是	用户的密码	`"password"`
consistency	否	一致性级别	`"All"`，`"Quorum"`
table	否	表名。默认值为 `"items"`	`"items"`，`"tab"`
keyspace	否	要使用的 Cassandra 键空间。默认值为 `"dapr"`	`"dapr"`
protoVersion	否	客户端的协议版本。默认值为 `"4"`	`"3"`，`"4"`
replicationFactor	否	复制因子。默认值为 `"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

4.7 - 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（如果 Worker 已在 Dapr 外部预创建，则必需）
    - name: workerUrl
      value: ""

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规格元数据字段

字段	必需	详情	示例
`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。如果 Worker 已在 Dapr 外部预配置，则必需。	`"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 仪表板后在浏览器的 URL 栏中找到此 ID，ID 是 dash.cloudflare.com 之后的十六进制字符串。例如，如果 URL 是 https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef，则 cfAccountID 的值为 456789abcdef8b5588f3d134f74acdef。
cfAPIToken: 具有创建和编辑 Workers 和 Workers KV 命名空间权限的 API 令牌。您可以在 Cloudflare 仪表板的 “我的个人资料” 部分的 “API 令牌” 页面中创建它：
1. 点击 “创建令牌”。
2. 选择 “编辑 Cloudflare Workers” 模板。
3. 按照屏幕上的说明生成新的 API 令牌。

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

如果您不希望授予 Dapr 为您部署 Worker 脚本的权限，您可以手动预配置一个 Worker 供 Dapr 使用。请注意，如果您有多个通过 Worker 与 Cloudflare 服务交互的 Dapr 组件，您需要为每个组件创建一个单独的 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.15"
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 命令将向您显示完整的 URL，例如 https://mydaprkv.mydomain.workers.dev。

生成 Ed25519 密钥对

所有 Cloudflare Workers 都在公共互联网监听，因此 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，或者从 Homebrew 安装 OpenSSL 3.0，使用 brew install openssl@3，然后在下面的命令中将 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 时需要它（如上一节中的说明）。

警告

保护您的密钥的私有部分，并将其视为 secret 值！

附加说明

请注意，Cloudflare Workers KV 不保证强数据一致性。虽然更改通常会立即对同一 Cloudflare 数据中心的请求可见，但更改在所有 Cloudflare 区域之间复制可能需要一定时间（通常最多一分钟）。
此状态存储支持 Dapr 的 TTL，但 TTL 的最小值为 1 分钟。

4.8 - 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:
  # 连接字符串
  - name: connectionString
    value: "<CONNECTION STRING>"
  # 数据库操作的超时时间，以秒为单位（可选）
  #- name: timeoutInSeconds
  #  value: 20
  # 存储状态的表名（可选）
  #- name: tableName
  #  value: "state"
  # Dapr 使用的元数据存储表名（可选）
  #- name: metadataTableName
  #  value: "dapr_metadata"
  # 清理过期行的间隔时间，以秒为单位（可选）
  #- name: cleanupIntervalInSeconds
  #  value: 3600
  # 连接关闭前的最大空闲时间（可选）
  #- name: connectionMaxIdleTime
  #  value: 0
  # 如果希望使用 CockroachDB 作为 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例中使用了明文字符串来存储 secret。建议使用 secret 存储来保护 secret，如此处所述。

规格元数据字段

字段	必需	详情	示例
`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 存储记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性，以指示数据在多少秒后应被视为“过期”。

由于 CockroachDB 没有内置的 TTL 支持，您可以通过在状态表中添加一列来实现这一点，该列指示数据何时应被视为“过期”。即使“过期”记录仍然物理存储在数据库中，也不会返回给调用者。后台“垃圾收集器”定期扫描状态表以删除过期的行。

您可以使用 cleanupIntervalInSeconds 元数据属性设置删除过期记录的间隔时间，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupIntervalInSeconds 设置为较小的值，例如 300（300 秒或 5 分钟）。
如果您不打算在 Dapr 和 CockroachDB 状态存储中使用 TTL，您应考虑将 cleanupIntervalInSeconds 设置为 <= 0（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

4.9 - 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> # 必填。

警告

上述示例中，secret 是以明文字符串形式使用的。建议使用 secret 存储来保护这些信息，具体方法请参阅此处。

配置元数据字段

字段	必填	详情	示例
couchbaseURL	Y	Couchbase 服务器的 URL	`"http://localhost:8091"`
username	Y	数据库的用户名	`"user"`
password	Y	访问的密码	`"password"`
bucketName	Y	要写入的桶名称	`"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

4.10 - Etcd

Etcd 状态存储组件的详细介绍

组件格式

要配置 Etcd 状态存储，需创建一个类型为 state.etcd 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.etcd
  # 支持 v1 和 v2。建议默认使用 v2。请注意，v1 和 v2 之间没有直接的迁移路径，详情请参见下文的 `版本控制`。
  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"

警告

上述示例使用明文字符串作为 secret。建议按照此处的说明使用 secret 存储。

版本控制

Dapr 提供了两个版本的 Etcd 状态存储组件：v1 和 v2。建议使用 v2，因为 v1 已被弃用。

虽然 v1 和 v2 使用相同的元数据字段，但在使用 Dapr v1.12 的 actor TTLs 时，v1 可能会导致应用程序中的数据不一致。 v1 和 v2 之间不兼容，且在现有的 Etcd 集群和 keyPrefixPath 上没有从 v1 到 v2 的数据迁移路径。如果您当前使用的是 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	是否启用 TLS 连接到 Etcd。	`"false"`
`ca`	N	连接到 Etcd 的 CA 证书，PEM 编码。可以是 `secretKeyRef` 以使用secret 引用。	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
`cert`	N	连接到 Etcd 的 TLS 证书，PEM 编码。可以是 `secretKeyRef` 以使用secret 引用。	`"-----BEGIN CERTIFICATE-----\nMIIDUTCC..."`
`key`	N	连接到 Etcd 的 TLS 密钥，PEM 编码。可以是 `secretKeyRef` 以使用secret 引用。	`"-----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。

4.11 - 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: 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"
  - name: type 
    value: <REPLACE-WITH-CREDENTIALS-TYPE> # 已弃用。

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护这些信息，具体方法请参阅此处。

规格元数据字段

字段	必填	说明	示例
project_id	Y	使用的 GCP 项目的 ID	`"project-id"`
endpoint	N	组件使用的 GCP 端点，仅用于本地开发（例如使用 GCP Datastore Emulator）。在生产环境中不需要设置 `endpoint`。	`"localhost:8432"`
private_key_id	N	使用的私钥 ID	`"private-key-id"`
private_key	N	如果使用显式凭据，此字段应包含服务账户 JSON 中的 `private_key` 字段	`-----BEGIN PRIVATE KEY-----MIIBVgIBADANBgkqhkiG9w0B`
client_email	N	客户端的电子邮件地址	`"example@example.com"`
client_id	N	用于身份验证的客户端 ID	`"client-id"`
auth_uri	N	使用的身份验证 URI	`"https://accounts.google.com/o/oauth2/auth"`
token_uri	N	用于获取 Auth 令牌的 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	Filestore 中的实体名称，默认为 `"DaprState"`	`"DaprState"`
noindex	N	是否禁用状态实体的索引。如果遇到 Firestore 索引大小限制，可以启用此设置。默认为 `"false"`	`"true"`
type	N	已弃用凭据类型	`"serviceaccount"`

GCP 凭据

由于 GCP Firestore 组件使用 GCP Go 客户端库，默认情况下会使用 应用程序默认凭据 进行身份验证。详细信息请参阅使用客户端库对 GCP 云服务进行身份验证指南。

设置 GCP Firestore

您可以使用 GCP Datastore 模拟器在本地运行，具体步骤请参阅此处。

然后，您可以通过 http://localhost:8432 与服务器交互。

按照此处的说明在 Google Cloud 上设置 Firestore。

4.12 - 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> # 可选。默认: ""

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来保护 secret，如此处所述。

规范元数据字段

字段	必需	详情	示例
datacenter	Y	使用的数据中心	`"dc1"`
httpAddr	Y	Consul 服务器的地址	`"consul.default.svc.cluster.local:8500"`
aclToken	N	每个请求的 ACL 令牌。默认是 `""`	`"token"`
scheme	N	Consul 服务器的 URI 方案。默认是 `"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

4.13 - 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> # 必需。服务器地址的逗号分隔字符串。例如："hazelcast:3000,hazelcast2:3000"
  - name: hazelcastMap
    value: <REPLACE-WITH-MAP> # 必需。Hazelcast map 的配置。

警告

上述示例中使用了明文字符串来表示 secret。建议使用 secret 存储来保护这些信息，具体方法请参阅此处。

规格元数据字段

字段	必需	详情	示例
hazelcastServers	是	服务器地址的逗号分隔字符串	`"hazelcast:3000,hazelcast2:3000"`
hazelcastMap	是	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。

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

警告

上述示例中使用了明文字符串作为 secret。建议使用 secret 存储来保护这些信息，具体方法请参阅此处。

规格元数据字段说明

字段	必需	详情	示例
natsURL	是	NATS 服务器地址 URL	“`nats://localhost:4222`”
jwt	否	用于分布式认证的 NATS JWT	“`eyJhbGciOiJ...6yJV_adQssw5c`”
seedKey	否	用于分布式认证的 NATS 种子密钥	“`SUACS34K232O...5Z3POU7BNIL4Y`”
bucket	是	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>

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

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保护密钥，详情请参阅此处。

规格元数据字段

字段	必需	详情	示例
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

4.16 - 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 进行身份验证

使用 Microsoft Entra ID 进行身份验证仅在 Azure SQL 上受支持。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 分钟）。
如果您不打算在 Dapr 和 SQL Server 状态存储中使用 TTL，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

状态存储在 ExpireDate 列上没有索引，这意味着每次清理操作都必须执行全表扫描。如果您打算在表中写入大量使用 TTL 的记录，您应该考虑在 ExpireDate 列上创建索引。索引使查询更快，但使用更多的存储空间并略微减慢写入速度。

CREATE CLUSTERED INDEX expiredate_idx ON state(ExpireDate ASC)

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

警告

上述示例中，secret以明文字符串形式使用。建议按照此处所述使用secret存储。

actor状态存储和事务支持

当MongoDB用作actor状态存储或需要事务支持时，必须在副本集中运行。

如果希望将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，请将参数指定为?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创建3节点副本集，请参阅官方文档。

您可以使用Bitnami打包的Helm chart方便地在Kubernetes上安装MongoDB。请参阅Helm chart文档以了解如何部署MongoDB，无论是作为独立服务器还是与副本集（使用事务和actor所需）一起。这会将MongoDB安装到default命名空间中。要与MongoDB交互，请使用：kubectl get svc mongo-mongodb查找服务。例如，如果使用上述Helm默认值安装，MongoDB主机地址将是： mongo-mongodb.default.svc.cluster.local:27017 按照屏幕上的说明获取MongoDB的root密码。用户名通常默认为admin。

TTL和清理

此状态存储支持Dapr存储记录的生存时间（TTL）。使用Dapr存储数据时，您可以设置ttlInSeconds元数据属性以指示数据何时应被视为“过期”。

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

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来存储 secret，如此处所述。

如果希望将 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 实例、在本地开发机器上运行的，还是云服务提供的 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 将需要最低 TLS 版本为 1.2。

TTL 和清理

此状态存储支持 Dapr 存储的记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以指示数据何时应被视为 “过期”。

由于 MySQL 没有内置的 TTL 支持，这在 Dapr 中通过在状态表中添加一列来实现，指示数据何时应被视为 “过期”。即使数据仍然物理存储在数据库中，“过期” 的记录也不会返回给调用者。后台 “垃圾收集器” 定期扫描状态表以删除过期的行。

删除过期记录的间隔时间由 cleanupIntervalInSeconds 元数据属性设置，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupIntervalInSeconds 设置为较小的值，例如 300（300 秒或 5 分钟）。
如果您不打算在 Dapr 和 MySQL 状态存储中使用 TTL，您应考虑将 cleanupIntervalInSeconds 设置为 <= 0（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

4.19 - 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" 或 "false">  # 可选。默认值："false"
 - name: configFileAuthentication
   value: <"true" 或 "false">  # 可选。默认值："false"。当 instancePrincipalAuthentication 为 "true" 时不使用
 - name: configFilePath
   value: <配置文件的完整路径>  # 可选。无默认值。仅在 configFileAuthentication 为 "true" 时使用
 - name: configFileProfile
   value: <配置文件中的配置名称>  # 可选。默认值："DEFAULT"。仅在 configFileAuthentication 为 "true" 时使用
 - name: tenancyOCID
   value: <租户的 OCID>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: userOCID
   value: <用户的 OCID>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: fingerPrint
   value: <公钥的指纹>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: privateKey  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
   value: |
          -----BEGIN RSA PRIVATE KEY-----
          私钥内容
          -----END RSA PRIVATE KEY-----
 - name: region
   value: <OCI 区域>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: bucketName
   value: <桶的名称>
 - name: compartmentOCID
   value: <隔间的 OCID>

警告

上述示例使用明文字符串作为密钥。建议使用密钥存储来保护密钥，如此处所述。

规格元数据字段

字段	必需	详细信息	示例
instancePrincipalAuthentication	否	布尔值，指示是否使用实例主体认证。默认值：“false”	`"true"` 或 `"false"`。
configFileAuthentication	否	布尔值，指示是否通过配置文件提供身份凭证。默认值：“false”。当 instancePrincipalAuthentication 为 true 时不使用。	`"true"` 或 `"false"`。
configFilePath	否	OCI 配置文件的完整路径。无默认值。当 instancePrincipalAuthentication 为 true 时不使用。请注意：不支持 ~/ 前缀。	`"/home/apps/configuration-files/myOCIConfig.txt"`。
configFileProfile	否	配置文件中的配置名称。默认值：“DEFAULT”。当 instancePrincipalAuthentication 为 true 时不使用。	`"DEFAULT"` 或 `"PRODUCTION"`。
tenancyOCID	是	OCI 租户标识符。当 instancePrincipalAuthentication 为 true 时不使用。	`"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`。
userOCID	是	OCI 用户的 OCID（需要访问 OCI 对象存储的权限）。当 instancePrincipalAuthentication 为 true 时不使用。	`"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"`
fingerPrint	是	公钥的指纹。当 instancePrincipalAuthentication 为 true 时不使用。	`"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"`
privateKey	是	RSA 密钥对的私钥。当 instancePrincipalAuthentication 为 true 时不使用。	`"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"`
region	是	OCI 区域。当 instancePrincipalAuthentication 为 true 时不使用。	`"us-ashburn-1"`
bucketName	是	用于读写的桶的名称（如果需要则创建）	`"application-state-store-bucket"`
compartmentOCID	是	包含桶的隔间的 OCID	`"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"`

设置 OCI 对象存储

OCI 对象存储状态存储需要与 Oracle 云基础设施交互。状态存储支持两种认证方法：基于身份（用户或服务账户）的认证和实例主体认证。请注意，资源主体认证（用于非实例的资源，如无服务器函数）目前不支持。

在 Oracle 云基础设施上运行的 Dapr 应用程序（无论是在计算实例中还是作为 Kubernetes 上的容器）可以使用实例主体认证。有关更多信息，请参阅 OCI 文档关于从实例调用 OCI 服务。简而言之：实例需要是动态组的成员，并且该动态组需要通过 IAM 策略获得与对象存储服务交互的权限。在这种情况下，设置 instancePrincipalAuthentication 为 "true"。您无需配置 tenancyOCID、userOCID、region、fingerPrint 和 privateKey 属性——如果您为它们定义了值，这些将被忽略。

基于身份的认证通过具有权限的 OCI 账户与 OCI 交互，以在指定的桶中创建、读取和删除对象，并允许在指定的隔间中创建桶（如果桶未事先创建）。OCI 文档描述了如何创建 OCI 账户。状态存储通过使用为 OCI 账户生成的 RSA 密钥对的公钥指纹和私钥进行交互。OCI 文档中提供了生成密钥对和获取所需信息的说明。

身份和身份凭证的详细信息可以直接在 Dapr 组件属性文件中提供——使用属性 tenancyOCID、userOCID、fingerPrint、privateKey 和 region——或者可以从配置文件中提供，这在许多 OCI 相关工具（如 CLI 和 Terraform）和 SDK 中很常见。在后一种情况下，必须通过属性 configFilePath 提供确切的文件名和完整路径。请注意：路径中不支持 ~/ 前缀。配置文件可以包含多个配置；可以通过属性 configFileProfile 指定所需的配置。如果未提供值，则使用 DEFAULT 作为要使用的配置名称。请注意：如果未找到指定的配置，则使用 DEFAULT 配置（如果存在）。OCI SDK 文档提供了关于配置文件定义的详细信息。

如果您希望为 Dapr 使用创建桶，可以事先进行。然而，如果不存在，对象存储状态提供者将在指定的隔间中自动为您创建一个。

为了将 OCI 对象存储设置为状态存储，您需要以下属性：

instancePrincipalAuthentication：指示是否应使用基于实例主体的认证的标志。
configFileAuthentication：指示是否通过配置文件提供 OCI 身份凭证的标志。当 instancePrincipalAuthentication 为 true 时不使用。
configFilePath：OCI 配置文件的完整路径。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 不为 true 时不使用。
configFileProfile：配置文件中的配置名称。默认值：“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 的生存时间逻辑，确保状态在过期后无法检索。有关详细信息，请参阅此设置状态生存时间的操作指南。

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。

4.20 - Oracle 数据库

Oracle 数据库状态存储组件的详细信息

组件格式

创建一个组件属性的 yaml 文件，例如 oracle.yaml（名称可以随意），然后粘贴以下内容，并将 <CONNECTION STRING> 替换为您的连接字符串。连接字符串是标准的 Oracle 数据库连接字符串，格式为："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 数据库作为 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

警告

上述示例中使用了明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规格元数据字段

字段	必需	详细信息	示例
connectionString	Y	Oracle 数据库的连接字符串	`"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 数据库并检查是否存在指定 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 使用固定的键方案和复合键来跨应用程序分区状态。对于一般状态，键格式为：App-ID||state key。Oracle 数据库状态存储将此键完整映射到 KEY 列。

您可以通过对 tableName 表（例如 STATE 表）进行 SQL 查询轻松检查所有存储的状态。

生存时间和状态过期

Oracle 数据库状态存储组件支持 Dapr 的生存时间逻辑，确保状态在过期后无法检索。有关详细信息，请参阅此处关于设置状态生存时间的指南。

Oracle 数据库本身不支持生存时间设置。此组件的实现使用名为 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 秒）的时间戳。

请注意，此组件不会从状态存储中删除过期的状态。应用程序操作员可以决定运行一个定期的 job，以某种形式的垃圾收集来显式删除所有具有过去 EXPIRATION_TIME 的状态记录。用于收集过期垃圾记录的 SQL 语句：

 delete dapr_state 
 where  expiration_time < SYS_EXTRACT_UTC(SYSTIMESTAMP);

并发

Oracle 数据库状态存储中的并发通过使用 ETag 实现。每个记录在 Oracle 数据库状态存储中的状态都在创建或更新时分配一个唯一的 ETag - 一个存储在 ETag 列中的生成的唯一字符串。注意：每当对现有记录执行 Set 操作时，UPDATE_TIME 列也会更新。

只有当此状态存储的 Set 和 Delete 请求指定 FirstWrite 并发策略时，请求才需要提供要写入或删除的状态的实际 ETag 值，以使请求成功。如果指定了不同的或没有并发策略，则不会对 ETag 值进行检查。

一致性

Oracle 数据库状态存储支持事务。多个 Set 和 Delete 命令可以组合在一个请求中，该请求作为单个原子事务处理。

注意：简单的 Set 和 Delete 操作本身就是一个事务；当 Set 或 Delete 请求返回 HTTP-20X 结果时，数据库事务已成功提交。

查询

Oracle 数据库状态存储当前不支持查询 API。

创建 Oracle 数据库和用户模式

运行一个 Oracle 数据库实例。您可以使用以下命令在 Docker CE 中运行一个本地 Oracle 数据库实例 - 或者当然使用现有的 Oracle 数据库：
```
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 数据库中创建一个新的用户模式，运行以下 SQL 命令：
```
create user dapr identified by DaprPassword4239 default tablespace users quota unlimited on users;
grant create session, create table to dapr;
```
（可选）创建用于存储状态记录的表。 Oracle 数据库状态存储组件会检查连接到的数据库用户模式中是否已经存在用于存储状态的表，如果不存在，它会创建该表。然而，您也可以在运行时之前创建用于存储状态记录的表。这使您 - 或数据库管理员 - 可以更好地控制表的物理配置。这也意味着您不必授予用户模式 create table 权限。
运行以下 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 云基础设施上创建一个免费的（或付费的）Autonomous Transaction Processing (ATP) 或 ADW (Autonomous Data Warehouse) 实例，如 OCI 文档中的始终免费自治数据库所述。
您需要为用户 ADMIN 提供密码。您使用此帐户（至少最初）进行数据库管理活动。您可以在基于 Web 的 SQL Developer 工具中工作，也可以在其桌面版本或众多数据库开发工具中工作。
为状态数据创建一个模式。在 Oracle 数据库中创建一个新的用户模式以存储状态数据 - 例如使用 ADMIN 帐户。授予此新用户（模式）创建表和在关联表空间中存储数据的权限。
要在 Oracle 数据库中创建一个新的用户模式，运行以下 SQL 命令：
```
create user dapr identified by DaprPassword4239 default tablespace users quota unlimited on users;
grant create session, create table to dapr;
```
（可选）创建用于存储状态记录的表。 Oracle 数据库状态存储组件会检查连接到的数据库用户模式中是否已经存在用于存储状态的表，如果不存在，它会创建该表。然而，您也可以在运行时之前创建用于存储状态记录的表。这使您 - 或数据库管理员 - 可以更好地控制表的物理配置。这也意味着您不必授予用户模式 create table 权限。
运行以下 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
  )
```

4.21 - 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>"
    # 数据库操作的超时时间，作为 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 或 workflow 的状态存储，请取消注释此项（可选）
    #- name: actorStateStore
    #  value: "true"

警告

上述示例使用明文字符串作为 secret。建议按照此处所述使用 secret 存储。

规格元数据字段

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

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

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

使用 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	客户端 secret（应用程序密码）	`"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 关系数据库服务部署到的 AWS 区域。	`"us-east-1"`
`awsAccessKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中弃用。请改用 ‘accessKey’。与 IAM 帐户关联的 AWS 访问密钥	`"AKIAIOSFODNN7EXAMPLE"`
`awsSecretKey`	N	这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中弃用。请改用 ‘secretKey’。与访问密钥关联的 secret 密钥	`"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	间隔时间，作为 Go duration 或秒数，用于清理具有过期 TTL 的行。默认值：`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 组件中，ETags 现在是随机 UUID，这确保了与其他 PostgreSQL 兼容数据库（如 CockroachDB）的更好兼容性。

由于这些更改，v1 和 v2 组件无法从同一个表中读取或写入数据。在此阶段，也无法在两个版本的组件之间迁移数据。

以人类可读格式显示数据

PostgreSQL v2 组件将状态的值存储在 value 列中，该列是 BYTEA 类型。大多数 PostgreSQL 工具，包括 pgAdmin，默认将值视为二进制，并不以人类可读的形式显示。

如果您想检查状态存储中的值，并且知道它不是二进制的（例如，JSON 数据），您可以使用如下查询以人类可读的形式显示值：

-- 将 "state" 替换为您环境中的状态表名称
SELECT *, convert_from(value, 'utf-8') FROM state;

TTL 和清理

由于 PostgreSQL 没有内置的 TTL 支持，这在 Dapr 中通过在状态表中添加一列来实现，该列指示数据何时应被视为 “过期”。即使它们仍然物理存储在数据库中，“过期” 的记录也不会返回给调用者。后台 “垃圾收集器” 定期扫描状态表以查找过期的行并删除它们。

您可以使用 cleanupInterval 元数据属性设置过期记录的删除间隔，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupInterval 设置为较小的值；例如，5m（5 分钟）。
如果您不打算在 Dapr 和 PostgreSQL 状态存储中使用 TTL，您应该考虑将 cleanupInterval 设置为 <= 0 的值（例如，0 或 -1）以禁用定期清理并减少数据库的负载。

4.22 - 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>"
    # 数据库操作的超时时间，作为 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 或 workflow 的状态存储，请取消注释此项（可选）
    #- name: actorStateStore
    #  value: "true"

警告

上述示例使用明文字符串作为 secret。建议按照此处所述使用 secret 存储。

规格元数据字段

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

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

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

使用 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	客户端 secret（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

字段	必需	详情	示例
`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	与访问密钥关联的 secret 密钥	`"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	间隔时间，作为 Go duration 或秒数，用于清理具有过期 TTL 的行。默认值：`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 存储的记录的生存时间 (TTL)。在使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以指示数据在多少秒后应被视为 “过期”。

由于 PostgreSQL 没有内置的 TTL 支持，这在 Dapr 中通过在状态表中添加一列来实现，该列指示数据何时应被视为 “过期”。即使记录仍然物理存储在数据库中，“过期” 的记录也不会返回给调用者。后台 “垃圾收集器” 定期扫描状态表以查找过期行并删除它们。

您可以使用 cleanupInterval 元数据属性设置过期记录的删除间隔，默认为 3600 秒（即 1 小时）。

较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupInterval 设置为较小的值；例如，5m（5 分钟）。
如果您不打算在 Dapr 和 PostgreSQL 状态存储中使用 TTL，您应该考虑将 cleanupInterval 设置为 <= 0 的值（例如，0 或 -1）以禁用定期清理并减少数据库的负载。

状态表中存储记录过期日期的列 expiredate 默认没有索引，因此每次定期清理都必须执行全表扫描。如果您有一个包含大量记录的表，并且只有其中一些使用 TTL，您可能会发现为该列创建索引很有用。假设您的状态表名为 state（默认），您可以使用此查询：

CREATE INDEX expiredate_idx
    ON state
    USING btree (expiredate ASC NULLS LAST);

4.23 - 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: 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"

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

如果希望将 Redis 用作 actor 存储，请在 yaml 中添加以下内容。

  - name: actorStateStore
    value: "true"

规格元数据字段

字段	必需	详细信息	示例
redisHost	Y	Redis 主机的连接字符串	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`
redisPassword	N	Redis 主机的密码。无默认值。可以使用 `secretKeyRef` 来使用 secret 引用	`""`, `"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。建议使用 secret 存储，如此处所述	`"----BEGIN CERTIFICATE-----\nMIIC..."`
clientKey	N	客户端私钥的内容，与 `clientCert` 一起用于身份验证。建议使用 secret 存储，如此处所述	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
maxRetries	N	放弃之前的最大重试次数。默认为 `3`	`5`, `10`
maxRetryBackoff	N	每次重试之间的最大退避时间。默认为 `2` 秒；`"-1"` 禁用退避。	`3000000000`
failover	N	启用故障转移配置的属性。需要设置 sentinelMasterName。redisHost 应为哨兵主机地址。请参阅 Redis Sentinel 文档。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	哨兵主名称。请参阅 Redis Sentinel 文档	`""`, `"127.0.0.1:6379"`
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 的 pub/sub 功能所需的。如果您打算仅将 Redis 用作状态存储（而不是用于 pub/sub），则无需设置镜像版本。
```
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis
```
运行 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 并复制输出的密码。
将此密码添加为您的 redis.yaml 文件中的 redisPassword 值。例如：
```
    metadata:
    - name: redisPassword
      value: lhDOkwTlp0
```

AWS Redis

使用官方 Microsoft 文档创建 Azure Cache for Redis 实例。
创建实例后，从 Azure 门户获取主机名（FQDN）和访问密钥。
- 对于主机名：
  - 导航到资源的概览页面。
  - 复制主机名值。
- 对于访问密钥：
  - 导航到设置 > 访问密钥。
  - 复制并保存您的密钥。
将您的密钥和主机名添加到 Dapr 可以应用于您的集群的 redis.yaml 文件中。
- 如果您正在运行示例，请将主机和密钥添加到提供的 redis.yaml 中。
- 如果您从头开始创建项目，请按照组件格式部分中指定的方式创建 redis.yaml 文件。
将 redisHost 键设置为 [HOST NAME FROM PREVIOUS STEP]: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

查询 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

按照在 Kubernetes 中部署 Redis的说明进行操作，并添加一个额外的细节。

安装 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 模块，无法用于查询。

按照在 AWS 中部署 Redis的说明进行操作。

注意

要支持查询，您需要启用 RediSearch 和 RedisJson。

注意

Memory Store 不支持模块，无法用于查询。

Redis Enterprise 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"
    }
  ]
}

查询语法和文档可在此处找到。

4.24 - 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 # 可选（是否保留所有状态更改的存档表）

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，如此处所述。

如果可选的 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"

4.25 - 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"
  # 设置数据库操作的忙等待时间
  #- 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 下的数据库。请参阅 SQLite 文档以获取所有支持的 URI 选项。
特殊情况 ":memory:" 启动由内存 SQLite 数据库支持的组件。此数据库不会持久化到磁盘，不会在多个 Dapr 实例之间共享，并且当 Dapr sidecar 停止时，所有数据都会丢失。使用内存数据库时，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。

4.26 - 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> # 可选。

警告

上述示例中使用了明文字符串来表示 secret。建议使用 secret 存储来安全地管理这些 secret，详情请参阅此处。

规格元数据字段

字段	必需	详情	示例
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

4.27 - 内存

关于内存状态组件的详细文档

内存状态存储组件在Dapr sidecar中维护状态，主要用于开发目的。状态不会在多个sidecar之间共享，并且在Dapr sidecar重启时会丢失。

组件格式

要设置内存状态存储，创建一个类型为state.in-memory的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.in-memory
  version: v1
  metadata: 
  # 如果希望将内存用作actor模型的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

注意：虽然内存组件不需要特定的元数据，但spec.metadata字段仍然是必填的。

5 - Secret 存储组件规范

与 Dapr 接口兼容的 Secret 存储支持

下表列出了 Dapr Secret 构建块所支持的 Secret 存储。了解如何为 Dapr 的 Secret 管理设置不同的 Secret 存储。

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

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

5.1 - AWS Secrets Manager

关于密钥存储组件的详细信息

组件格式

要设置 AWS Secrets Manager 的密钥存储，需创建一个类型为 secretstores.aws.secretmanager 的组件。请参阅本指南了解如何创建和应用密钥存储配置。请参阅本指南以引用 secrets以检索和使用 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]"

警告

上述示例中使用了明文形式的字符串作为密钥。建议使用本地密钥存储，例如Kubernetes 密钥存储或本地文件来安全地存储密钥。

规格元数据字段

字段	必需	详情	示例
region	Y	部署 AWS Secrets Manager 实例的特定 AWS 区域	`"us-east-1"`
accessKey	Y	访问此资源的 AWS 访问密钥	`"key"`
secretKey	Y	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`

重要

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

可选的每请求元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	指定密钥的版本。
`metadata.version_stage`	指定密钥的版本阶段。

创建 AWS Secrets Manager 实例

请参考 AWS 文档以设置 AWS Secrets Manager：https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html。

5.2 - AWS SSM 参数存储

有关 AWS SSM 参数存储 - 机密存储组件的详细信息

组件格式

要设置 AWS SSM 参数存储的机密存储，需创建一个 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]"

警告

上述示例使用了明文字符串作为机密。建议使用本地机密存储，例如 Kubernetes 机密存储或本地文件来安全地存储密钥。

规格元数据字段

字段	必需	详细信息	示例
region	Y	部署 AWS SSM 参数存储实例的特定 AWS 区域	`"us-east-1"`
accessKey	Y	访问此资源的 AWS 访问密钥	`"key"`
secretKey	Y	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`
prefix	N	用于指定多个 SSM 参数存储机密存储组件的前缀。	`"prefix"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规格中提供 AWS 访问密钥、秘密密钥和令牌。

创建 AWS SSM 参数存储实例

请参考 AWS 文档以设置 AWS SSM 参数存储：https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html。

5.3 - Azure Key Vault 密钥存储

有关 Azure Key Vault 密钥存储组件的详细信息

组件格式

要设置 Azure Key Vault 密钥存储，创建一个类型为 secretstores.azure.keyvault 的组件。

请参阅密钥存储组件指南以了解如何创建和应用密钥存储配置。
请参阅引用密钥的指南以使用 Dapr 组件检索和使用密钥。
请参阅下面的配置组件部分。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName # 必需
    value: [your_keyvault_name]
  - 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]"

通过 Microsoft Entra ID 进行身份验证

Azure Key Vault 密钥存储组件仅支持通过 Microsoft Entra ID 进行身份验证。在启用此组件之前，请确保：

阅读Azure 身份验证文档。
创建一个 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为您的应用程序平台创建一个托管身份。

规范元数据字段

字段	必需	详细信息	示例
`vaultName`	Y	Azure Key Vault 的名称	`"mykeyvault"`
`azureEnvironment`	N	如果使用不同的 Azure 云，则为 Azure 环境的可选名称	`"AZUREPUBLICCLOUD"`（默认值），`"AZURECHINACLOUD"`，`"AZUREUSGOVERNMENTCLOUD"`，`"AZUREGERMANCLOUD"`
身份验证元数据		有关更多信息，请参阅Azure 身份验证

此外，您必须提供Azure 身份验证文档中解释的身份验证字段。

可选的每请求元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	给定密钥的版本。
`metadata.maxresults`	（仅适用于批量请求）要返回的密钥数量，超过此数量后请求将被截断。

示例

先决条件

Azure 订阅
Azure CLI
jq
您正在使用 bash 或 zsh shell
您已根据Azure 身份验证中的说明创建了一个 Microsoft Entra ID 应用程序（服务主体）。您将需要以下值：
值描述
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 的“获取密钥”权限。

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”。有关 Key Vault 的 Azure 内置角色的更多信息，请参阅 Microsoft 文档。

配置组件

使用客户端密钥

要使用客户端密钥，请在组件目录中创建一个名为 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 密钥存储中，然后在 YAML 文件中引用它们。在开始之前，您需要您创建的 Microsoft Entra ID 应用程序的详细信息。

使用客户端密钥

使用以下命令创建一个 Kubernetes 密钥：
```
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 密钥存储中的密钥名称
- [your_k8s_secret_key] 是 Kubernetes 密钥存储中的密钥键

创建一个 azurekeyvault.yaml 组件文件。

组件 yaml 使用 auth 属性引用 Kubernetes 密钥存储，并且 secretKeyRef 引用存储在 Kubernetes 密钥存储中的客户端密钥。

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 密钥：
```
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 密钥存储中的密钥名称
- [your_k8s_secret_key] 是 Kubernetes 密钥存储中的密钥键

创建一个 azurekeyvault.yaml 组件文件。

组件 yaml 使用 auth 属性引用 Kubernetes 密钥存储，并且 secretKeyRef 引用存储在 Kubernetes 密钥存储中的证书。

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
```
通过以下方式在 pod 级别创建并分配托管身份：
- Microsoft Entra ID 工作负载身份（首选方法）
- Microsoft Entra ID pod 身份
重要：虽然 Microsoft Entra ID pod 身份和工作负载身份都处于预览状态，但目前计划将 Microsoft Entra ID 工作负载身份推向普遍可用（稳定状态）。
创建工作负载身份后，授予其 read 权限：
- 在您期望的 KeyVault 实例上
- 在您的应用程序部署中。通过标签注释注入 pod 身份，并通过指定与期望的工作负载身份关联的 Kubernetes 服务帐户
```
apiVersion: v1
kind: Pod
metadata:
  name: mydaprdemoapp
  labels:
    aadpodidbinding: $POD_IDENTITY_NAME
```

直接使用 Azure 托管身份与通过 Microsoft Entra ID 工作负载身份

当直接使用托管身份时，您可以为应用程序关联多个身份，需要 azureClientId 来指定应使用哪个身份。

然而，当通过 Microsoft Entra ID 工作负载身份使用托管身份时，azureClientId 是不必要的且无效。要使用的 Azure 身份是从与 Azure 身份关联的服务帐户推断出来的。

参考

5.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>

警告

上述示例中使用了明文字符串来存储机密。建议使用本地机密存储，例如 Kubernetes 机密存储或本地文件来安全地管理密钥。

规格元数据字段

字段	必需	详细信息	示例
type	Y	账户类型。	`"service_account"`
project_id	Y	与此组件关联的项目 ID。	`"project_id"`
private_key_id	N	私钥 ID	`"privatekey"`
client_email	Y	客户端电子邮件地址	`"client@example.com"`
client_id	N	客户端 ID	`"11111111"`
auth_uri	N	认证 URI	`"https://accounts.google.com/o/oauth2/auth"`
token_uri	N	认证令牌 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/<project-name>.iam.gserviceaccount.com"`
private_key	Y	用于认证的私钥	`"privateKey"`

可选的每请求元数据属性

GCP Secret Manager 组件支持以下可选查询参数：

查询参数	描述
`metadata.version_id`	指定机密键的版本。

设置 GCP Secret Manager 实例

请参考 GCP 文档以设置 GCP Secret Manager：https://cloud.google.com/secret-manager/docs/quickstart。

5.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"

警告

上述示例中，密钥以明文形式使用。建议使用本地密钥存储，如Kubernetes 密钥存储或本地文件来引导安全密钥存储。

规格元数据字段

字段	必需	详细信息	示例
vaultAddr	否	Vault 服务器的地址。默认为 `"https://127.0.0.1:8200"`	`"https://127.0.0.1:8200"`
caPem	否	要使用的 CA 证书的内联内容，PEM 格式。如果定义，则优先于 `caPath` 和 `caCert`。	见下文
caPath	否	要使用的 CA 证书文件所在文件夹的路径，PEM 格式。如果文件夹包含多个文件，则仅使用找到的第一个文件。如果定义，则优先于 `caCert`。	`"path/to/cacert/holding/folder"`
caCert	否	要使用的 CA 证书的路径，PEM 格式。	`""path/to/cacert.pem"`
skipVerify	否	跳过 TLS 验证。默认为 `"false"`	`"true"`, `"false"`
tlsServerName	否	在 TLS 握手期间请求的服务器名称，以支持虚拟主机。此值还用于验证 Vault 服务器提供的 TLS 证书。	`"tls-server"`
vaultTokenMountPath	是	包含令牌的文件路径	`"path/to/file"`
vaultToken	是	令牌用于在 Vault 中进行身份验证。	`"tokenValue"`
vaultKVPrefix	否	Vault 中的前缀。默认为 `"dapr"`	`"dapr"`, `"myprefix"`
vaultKVUsePrefix	否	如果为 false，则强制 vaultKVPrefix 为空。如果未给出值或设置为 true，则在访问 Vault 时使用 vaultKVPrefix。将其设置为 false 是为了能够使用存储的 BulkGetSecret 方法。	`"true"`, `"false"`
enginePath	否	Vault 中的引擎路径。默认为 `"secret"`	`"kv"`, `"any"`
vaultValueType	否	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-----

5.6 - Kubernetes secrets

详细介绍 Kubernetes secret 存储组件

默认 Kubernetes secret 存储组件

在 Dapr 部署到 Kubernetes 集群时，系统会自动配置一个名为 kubernetes 的 secret 存储。这个预配置的 secret 存储允许开发人员直接使用 Kubernetes 的原生 secret 存储，而无需编写、部署或维护额外的组件配置文件，这对于希望简单地访问 Kubernetes 集群中 secret 的开发人员非常有用。

您仍然可以配置一个自定义的 Kubernetes secret 存储组件定义文件（详见下文）。通过自定义定义，您可以将代码中对 secret 存储的引用与托管平台解耦，因为存储名称可以自定义，不是固定的，这样可以使代码更通用和可移植。此外，通过显式定义 Kubernetes secret 存储组件，您可以从本地 Dapr 自托管安装连接到 Kubernetes secret 存储。这需要一个有效的 kubeconfig 文件。

限制 secret 存储访问

当使用 secret 范围限制应用程序中对 secret 的访问时，重要的是在范围定义中包含默认的 secret 存储以进行限制。

创建自定义 Kubernetes secret 存储组件

要设置 Kubernetes secret 存储，请创建一个类型为 secretstores.kubernetes 的组件。请参阅本指南了解如何创建和应用 secretstore 配置。请参阅本指南了解如何引用 secret以检索和使用 Dapr 组件的 secret。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mycustomsecretstore
spec:
  type: secretstores.kubernetes
  version: v1
  metadata:[]

配置元数据字段

字段	必需	详情	示例
`defaultNamespace`	否	默认命名空间以检索 secret。如果未设置，则必须在每个请求元数据中或通过环境变量 `NAMESPACE` 指定 `namespace`	`"default-ns"`
`kubeconfigPath`	否	kubeconfig 文件的路径。如果未指定，存储将使用默认的集群内配置值	`"/path/to/kubeconfig"`

可选的每请求元数据参数

可以为 Kubernetes secret 存储组件提供以下可选查询参数：

查询参数	描述
`metadata.namespace`	secret 的命名空间。如果未指定，则使用 pod 的命名空间。

5.7 - 阿里云 OOS 参数存储

详细介绍阿里云 OOS 参数存储的密钥存储组件

组件格式

要配置阿里云 OOS 参数存储的密钥存储，需创建一个类型为 secretstores.alicloud.parameterstore 的组件。请参阅本指南了解如何创建和应用密钥存储配置。请参阅本指南，了解如何在 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]"

警告

上述示例中，secret 以明文字符串形式使用。建议使用本地密钥存储，例如 Kubernetes 密钥存储或本地文件来安全地存储密钥。

规格元数据字段

字段	必需	详细信息	示例
regionId	Y	部署阿里云 OOS 参数存储实例的特定区域	`"cn-hangzhou"`
accessKeyId	Y	访问此资源的阿里云访问密钥 ID	`"accessKeyId"`
accessKeySecret	Y	访问此资源的阿里云访问密钥 Secret	`"accessKeySecret"`
securityToken	N	使用的阿里云安全令牌	`"securityToken"`

可选的每请求元数据属性

在从此密钥存储检索 secret 时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	指定 secret 密钥的版本
`metadata.path`	（仅用于批量请求）元数据中的路径。如果未设置，默认为根路径（所有 secret）。

创建阿里云 OOS 参数存储实例

请参考阿里云文档，了解如何设置阿里云 OOS 参数存储：https://www.alibabacloud.com/help/en/doc-detail/186828.html。

5.8 - 本地环境变量（用于开发）

本地环境 secret 存储组件的详细信息

此 Dapr secret 存储组件使用本地定义的环境变量，并且不使用身份验证。

警告

这种 secret 管理方法不建议用于生产环境。

组件格式

要配置本地环境变量 secret 存储，需要创建一个类型为 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_ 前缀开头的变量

5.9 - 本地文件（用于开发）

详细介绍本地文件 secret 存储组件

此 Dapr secret 存储组件从指定文件读取纯文本 JSON，并且不使用身份验证。

警告

不建议在生产环境中使用这种 secret 管理方法。

组件格式

要设置基于本地文件的 secret 存储，请创建一个类型为 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"

规格元数据字段

字段	必需	详细信息	示例
secretsFile	Y	存储 secret 的文件路径	`"path/to/file.json"`
nestedSeparator	N	用于展平 JSON 层次结构时的分隔符，默认为 `":"`	`":"`
multiValued	N	`"true"` 启用 `multipleKeyValuesPerSecret` 行为，允许在展平 JSON 层次结构前有一级多值键/值对。默认为 `"false"`	`"true"`

设置 JSON 文件以保存 secret

假设从 secretsFile 加载的 JSON 如下：

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "sql": "your sql connection string",
        "mysql": "your mysql connection string"
    }
}

multiValued 标志决定 secret 存储是采用名称/值行为还是每个 secret 的多个键值行为。

名称/值语义

如果 multiValued 为 false，存储将加载 JSON 文件并创建一个包含以下键值对的映射：

展平的键	值
“redisPassword”	`"your redis password"`
“connectionStrings:sql”	`"your sql connection string"`
“connectionStrings:mysql”	`"your mysql connection string"`

如果 multiValued 设置为 true，尝试获取 connectionStrings 键将导致 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"
}

多键值行为

如果 multiValued 为 true，secret 存储将启用每个 secret 的多个键值行为：

顶层之后的嵌套结构将被展平。
它将相同的 JSON 文件解析为此表：

键	值
“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 请求会成功返回，类似于以下内容：

$ 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"
}

处理更深的嵌套级别

注意，如规格元数据字段表中所述，multiValued 仅处理单个嵌套级别。

假设您有一个启用了 multiValued 的本地文件 secret 存储，指向一个 secretsFile，其中包含以下 JSON 内容：

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "mysql": {
          "username": "your mysql username",
          "password": "your mysql password"
        }
    }
}

connectionStrings 下的键 mysql 的内容具有大于 1 的嵌套级别，并将被展平。

以下是它在内存中的样子：

键	值
“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 这样的 secret 存储非常有用，它们每个 secret 键返回多个键/值对。

5.10 - 华为云密钥管理服务 (CSMS)

详细介绍华为云密钥管理服务 (CSMS) - 密钥存储组件

组件格式

要配置华为云密钥管理服务 (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 密钥存储或本地文件来确保密钥的安全存储。

元数据字段说明

字段	必需	详细信息	示例
region	是	华为云 CSMS 实例所在的具体区域	`"cn-north-4"`
accessKey	是	用于访问此资源的华为云访问密钥	`"accessKey"`
secretAccessKey	是	用于访问此资源的华为云密钥访问密钥	`"secretAccessKey"`

可选的每请求元数据属性

在从此密钥存储检索密钥时，可以提供以下可选查询参数：

查询参数	描述
`metadata.version_id`	指定密钥的版本。

设置华为云密钥管理服务 (CSMS) 实例

请参考华为云文档以设置华为云密钥管理服务 (CSMS)：https://support.huaweicloud.com/intl/en-us/usermanual-dew/dew_01_9993.html。

6 - 配置存储组件说明

与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
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

6.1 - Azure 应用配置

详细介绍 Azure 应用配置组件

组件格式

要设置 Azure 应用配置，需创建一个类型为 configuration.azure.appconfig 的组件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: configuration.azure.appconfig
  version: v1
  metadata:
  - name: host # 使用 Azure 身份验证时应使用此项。
    value: <HOST>
  - name: connectionString # 使用 Azure 身份验证时不应使用此项。
    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]

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，详见此处。

规格元数据字段

字段	必需	详情	示例
connectionString	Y*	Azure 应用配置实例的连接字符串。无默认值。可以使用 `secretKeyRef` 引用 secret。与 host 字段互斥。在使用 Azure 身份验证时不使用	`Endpoint=https://foo.azconfig.io;Id=osOX-l9-s0:sig;Secret=00000000000000000000000000000000000000000000`
host	N*	Azure 应用配置实例的端点。无默认值。与 connectionString 字段互斥。在使用 Azure 身份验证时使用	`https://dapr.azconfig.io`
maxRetries	N	最大重试次数，默认为 `3`	`5`, `10`
retryDelay	N	初始重试延迟时间，默认为 `4` 秒；`"-1"` 禁用重试延迟。延迟会随着每次重试呈指数增长，直到达到 maxRetryDelay 指定的最大值。	`4s`
maxRetryDelay	N	允许的最大重试延迟时间，通常大于或等于 retryDelay。默认为 `120` 秒；`"-1"` 禁用限制	`120s`
subscribePollInterval	N	轮询订阅键以检测更改的间隔时间（以纳秒为单位）。未来将更新为 Go 时间格式。默认间隔为 `24` 小时。	`24h`

注意：必须指定 host 或 connectionString。

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

通过连接字符串访问应用配置实例，该字符串可在 Azure 门户中获取。由于连接字符串包含敏感信息，建议将其视为 secret 并使用 secret 存储。

使用 Microsoft Entra ID 进行身份验证

Azure 应用配置组件还支持使用 Microsoft Entra ID 进行身份验证。在启用此组件之前：

阅读Azure 身份验证文档。
创建一个 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为您的应用程序平台创建托管身份。

设置 Azure 应用配置

您需要一个 Azure 订阅来设置 Azure 应用配置。

启动 Azure 应用配置创建流程。如有必要，请登录。
点击创建以启动 Azure 应用配置实例的部署。
创建实例后，获取端点或 连接字符串：
- 对于端点：导航到资源的概览并复制端点。
- 对于连接字符串：导航到设置 > 访问密钥 并复制连接字符串。
将端点或连接字符串添加到 Dapr 的 azappconfig.yaml 文件中。
将 host 键设置为 [Endpoint] 或将 connectionString 键设置为您之前保存的值。
注意
在生产环境中，请遵循秘密管理说明以安全管理您的 secret。

Azure 应用配置请求元数据

在 Azure 应用配置中，您可以为同一键定义不同标签的值。例如，您可以为开发和生产环境定义不同的值。您可以指定在连接到应用配置时要加载的标签。

Azure 应用配置组件支持以下可选的 label 元数据属性：

label：要检索的配置的标签。如果不存在，配置存储将返回指定键和空标签的配置。

标签可以通过请求 URL 中的查询参数指定：

GET curl http://localhost:<daprPort>/v1.0/configuration/<store-name>?key=<key name>&metadata.label=<label value>

6.2 - PostgreSQL

PostgreSQL 配置存储组件的详细说明

组件格式

要配置 PostgreSQL 作为配置存储，您需要创建一个类型为 configuration.postgresql 的组件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: configuration.postgresql
  version: v1
  metadata:
    # 连接字符串
    - name: connectionString
      value: "host=localhost user=postgres password=example port=5432 connect_timeout=10 database=config"
    # 存储配置信息的表名
    - name: table
      value: "[your_configuration_table_name]" 
    # 数据库操作的超时时间，以秒为单位（可选）
    #- name: timeoutInSeconds
    #  value: 20
    # 存储状态的表名（可选）
    #- name: tableName
    #  value: "state"
    # 存储 Dapr 使用的元数据的表名（可选）
    #- name: metadataTableName
    #  value: "dapr_metadata"
    # 清理过期行的间隔时间，以秒为单位（可选）
    #- name: cleanupIntervalInSeconds
    #  value: 3600
    # 该组件池化的最大连接数（可选）
    #- name: maxConns
    #  value: 0
    # 连接关闭前的最大空闲时间（可选）
    #- name: connectionMaxIdleTime
    #  value: 0
    # 控制查询执行的默认模式。（可选）
    #- name: queryExecMode
    #  value: ""
    # 如果希望使用 PostgreSQL 作为 actor 的状态存储，请取消注释此项（可选）
    #- name: actorStateStore
    #  value: "true"

警告

上述示例中使用了明文字符串来存储 secret。建议使用 secret 存储来保护这些信息，具体方法请参阅这里。

规格元数据字段

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

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

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

使用 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	客户端 secret（应用程序密码）	`"Ecy3X…"`

使用 AWS IAM 进行身份验证

字段	必需	详情	示例
`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’。与访问密钥关联的 secret 密钥	`"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 持有配置属性的值
VERSION VARCHAR N 持有配置属性的版本
METADATA JSON Y 以 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 属性提到的通道。

由于这是一个通用创建的触发器，将此触发器映射到 configuration table。

CREATE TRIGGER config
AFTER INSERT OR UPDATE OR DELETE ON configtable
    FOR EACH ROW EXECUTE PROCEDURE notify_event();

在订阅请求中添加一个额外的元数据字段，键为 pgNotifyChannel，值应设置为在 pg_notify 中提到的相同 channel name。从上面的示例中，它应设置为 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>'

6.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	Redis 主机地址	`"localhost:6379"`
redisPassword	N	Redis 密码	`"password"`
redisUsername	N	Redis 主机的用户名。默认为空。确保您的 Redis 服务器版本为 6 或更高，并已正确创建 acl 规则。	`"username"`
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。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	Sentinel 主名称。请参阅 Redis Sentinel 文档	`""`, `"127.0.0.1:6379"`
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"`

设置 Redis

Dapr 可以使用任何 Redis 实例：无论是容器化的、在本地开发机器上运行的，还是托管的云服务。

当您运行 dapr init 时，会自动创建一个 Redis 实例作为 Docker 容器。

您可以使用 Helm 在 Kubernetes 集群中快速创建一个 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。请注意，我们显式设置了一个镜像标签以获取版本大于 5 的版本，这是 Dapr 的 pubsub 功能所需的。如果您打算仅将 Redis 用作状态存储（而不是用于 pubsub），则无需设置镜像版本。
```
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 键设置为 [HOST NAME FROM PREVIOUS STEP]: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

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
Redis	Alpha	v1	1.8

7.1 - Redis

Redis 锁组件的详细介绍

组件格式

要配置 Redis 锁，需要创建一个类型为 lock.redis 的组件。请参阅本指南了解如何创建锁。

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: failover
    value: # 可选
  - name: sentinelMasterName
    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 存储来保存这些 secret，如此处所述。

规格元数据字段

字段	必需	详细信息	示例
redisHost	Y	Redis 主机的连接字符串	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`
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 应为哨兵主机地址。请参阅 Redis Sentinel 文档。默认为 `"false"`	`"true"`, `"false"`
sentinelMasterName	N	哨兵主名称。请参阅 Redis Sentinel 文档	`"mymaster"`
redeliverInterval	N	检查待处理消息以重新传递的间隔。默认为 `"60s"`。`"0"` 禁用重新传递。	`"30s"`
processingTimeout	N	消息必须待处理的时间量，然后才尝试重新传递。默认为 `"15s"`。`"0"` 禁用重新传递。	`"30s"`
redisType	N	Redis 的类型。有两个有效值，一个是单节点模式的 `"node"`，另一个是 Redis 集群模式的 `"cluster"`。默认为 `"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"`

设置 Redis

Dapr 可以使用任何 Redis 实例：容器化的、在本地开发机器上运行的或托管的云服务。

当您运行 dapr init 时，会自动创建一个作为 Docker 容器的 Redis 实例

您可以使用 Helm 在我们的 Kubernetes 集群中快速创建一个 Redis 实例。此方法需要安装 Helm。

将 Redis 安装到您的集群中。请注意，我们显式设置了一个镜像标签以获取版本大于 5 的版本，这是 Dapr 的 pubsub 功能所需的。如果您打算仅将 Redis 用作状态存储（而不是用于 pubsub），则无需设置镜像版本。
```
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 键设置为 [HOST NAME FROM PREVIOUS STEP]:6379，并将 redisPassword 键设置为您之前保存的密钥。
注意： 在生产环境中，请遵循秘密管理说明以安全管理您的 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

8 - 密码学组件规范

与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

8.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
  # 请参阅下文的身份验证部分以了解所有配置选项
  - name: azureTenantId
    value: ${{AzureKeyVaultTenantId}}
  - name: azureClientId
    value: ${{AzureKeyVaultServicePrincipalClientId}}
  - name: azureClientSecret
    value: ${{AzureKeyVaultServicePrincipalClientSecret}}

警告

上述示例中使用了明文字符串来表示密钥。建议使用密钥存储来保护密钥，详情请参阅此处。

通过 Microsoft Entra ID 进行身份验证

Azure Key Vault 加密组件仅支持通过 Microsoft Entra ID 进行身份验证。在启用此组件之前：

阅读 Azure 身份验证文档。
创建一个 Microsoft Entra ID 应用程序（也称为服务主体）。
或者，为您的应用程序平台创建一个托管身份。

元数据字段说明

字段	必需	详情	示例
`vaultName`	是	Azure Key Vault 的名称	`"mykeyvault"`
身份验证元数据	是	更多信息请参阅 Azure 身份验证

8.2 - JSON Web Key Sets (JWKS)

JWKS 加密组件的详细信息

组件格式

该组件用于从 JSON Web Key Set (RFC 7517) 中加载密钥。JSON Web Key Set 是包含一个或多个密钥的 JSON 文档，密钥以 JWK (JSON Web Key) 格式表示；这些密钥可以是公钥、私钥或共享密钥。

该组件支持从以下来源加载 JWKS：

本地文件；在这种情况下，Dapr 会监视文件的变化并自动重新加载。
HTTP(S) 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`	是	JWKS 文档的路径	本地文件: `"fixtures/crypto/jwks/jwks.json"` HTTP(S) URL: `"https://example.com/.well-known/jwks.json"` 嵌入的 JWKS: `{"keys": […]}` (可以是 base64 编码)
`requestTimeout`	否	从 HTTP(S) URL 获取 JWKS 文档时的网络请求超时时间，格式为 Go duration。默认值: “30s”	`"5s"`
`minRefreshInterval`	否	从 HTTP(S) 源刷新 JWKS 文档前的最小等待时间，格式为 Go duration。默认值: “10m”	`"1h"`

8.3 - Kubernetes Secrets

关于Kubernetes secret加密组件的详细信息

组件格式

此组件旨在加载以密钥名称命名的Kubernetes secret。

注意

此组件依赖于Dapr的加密引擎进行操作。虽然密钥不会直接暴露给您的应用程序，但Dapr可以访问原始密钥材料。

一个Dapr crypto.yaml组件文件的结构如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: crypto.dapr.kubernetes.secrets
  version: v1
  metadata:[]

警告

上述示例中使用了明文字符串形式的secrets。建议使用secret存储来保存secrets，具体方法请参见此处。

规格元数据字段

字段	必需	详情	示例
`defaultNamespace`	否	用于检索secrets的默认命名空间。如果未设置，必须为每个密钥指定命名空间，例如`namespace/secretName/key`	`"default-ns"`
`kubeconfigPath`	否	kubeconfig文件的路径。如果未指定，组件将使用默认的集群内配置	`"/path/to/kubeconfig"`

8.4 - 本地存储

本地存储加密组件的详细信息

组件格式

该组件用于从本地目录加载密钥。

组件接受文件夹名称作为输入，并从该文件夹加载密钥。每个密钥存储在单独的文件中，当用户请求某个名称的密钥时，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
  metadata:
    version: v1
    - name: path
      value: /path/to/folder/

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，具体方法请参见此处。

规格元数据字段

字段	必需	详情	示例
`path`	Y	包含要加载的密钥的文件夹。加载密钥时，密钥的名称将用作此文件夹中文件的名称。	`/path/to/folder`

示例

假设您设置了 path=/mnt/keys，其中包含以下文件：

/mnt/keys/mykey1.pem
/mnt/keys/mykey2

使用组件时，您可以将密钥引用为 mykey1.pem 和 mykey2。

9 - 会话组件规范

与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

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
Mistral	Alpha	v1	1.15
Ollama	Alpha	v1	1.16
OpenAI	Alpha	v1	1.15

9.1 -

yaml type: docs title: “AWS Bedrock” linkTitle: “AWS Bedrock” description: AWS Bedrock conversation组件的详细信息

组件格式

一个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: cacheTTL
    value: 10m

警告

上述示例中，secret以明文字符串形式使用。建议使用secret存储来保护secret，详情请参阅此处。

规格元数据字段

字段	必需	详情	示例
`endpoint`	N	组件连接到AWS模拟器的端点。不建议在生产环境中使用。	`http://localhost:4566`
`model`	N	使用的语言模型（LLM）。默认为Amazon的Bedrock默认提供商模型。	`amazon.titan-text-express-v1`
`cacheTTL`	N	提示缓存的生存时间（TTL），即缓存过期时间。使用Golang持续时间格式。	`10m`

9.2 - Anthropic

关于Anthropic conversation组件的详细信息

组件格式

一个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: cacheTTL
    value: 10m

警告

上述示例中，secret使用了明文字符串。建议使用secret存储，如此处所述。

元数据字段说明

字段	必需	详情	示例
`key`	Y	Anthropic的API密钥。	`"mykey"`
`model`	N	要使用的Anthropic LLM。默认为`claude-3-5-sonnet-20240620`	`claude-3-5-sonnet-20240620`
`cacheTTL`	N	提示缓存的过期时间。使用Golang的持续时间格式。	`10m`

9.3 - 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: cacheTTL
    value: 10m

警告

上述示例中，密钥以明文字符串形式使用。建议使用密钥存储来保存密钥，如此处所述。

元数据字段说明

字段	必需	详情	示例
`key`	Y	Huggingface 的 API 密钥。	`mykey`
`model`	N	要使用的 Huggingface LLM。默认为 `meta-llama/Meta-Llama-3-8B`。	`meta-llama/Meta-Llama-3-8B`
`cacheTTL`	N	提示缓存的过期时间。使用 Golang 持续时间格式。	`10m`

9.4 - 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: cacheTTL
    value: 10m

警告

上述示例中，密钥以明文形式展示。建议使用密钥存储来保护密钥，具体方法请参见此处。

规格元数据字段

字段	必需	详情	示例
`key`	Y	Mistral 的 API 密钥。	`mykey`
`model`	N	要使用的 Mistral LLM 模型。默认为 `open-mistral-7b`。	`open-mistral-7b`
`cacheTTL`	N	提示缓存的有效期，使用 Golang 的持续时间格式。	`10m`

9.5 - OpenAI

OpenAI conversation组件的详细信息

组件格式说明

一个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: cacheTTL
    value: 10m

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保护密钥，具体方法请参见此处。

规格元数据说明

字段	必需	详情	示例
`key`	是	OpenAI的API密钥。	`mykey`
`model`	否	要使用的OpenAI语言模型。默认为`gpt-4-turbo`。	`gpt-4-turbo`
`cacheTTL`	否	提示缓存的有效期。使用Golang的时间格式表示。	`10m`

10 - 名称解析提供者组件规范

支持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

10.1 - HashiCorp Consul

HashiCorp Consul 名称解析组件的详细信息

配置格式

在 Dapr 配置中设置 HashiCorp Consul。

在配置中，添加 nameResolution 规范，并将 component 字段设为 "consul"。

如果您使用 Dapr sidecar 将服务注册到 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 sidecar 端口。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 sidecar 健康端点上的单个健康检查	参见示例配置
Tags	N	`[]string`	配置注册服务时要包含的任何标签	`- "dapr"`
Meta	N	`map[string]string`	配置注册服务时要包含的任何附加元数据	`DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"`
DaprPortMetaKey	N	`string`	用于从 Consul 服务元数据中获取 Dapr sidecar 端口的键，在服务解析期间，它也将用于在注册期间在元数据中设置 Dapr sidecar 端口。如果为空，将默认为 `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 指南

10.2 - Kubernetes DNS

详细介绍 Kubernetes DNS 名称解析组件

配置格式

一般情况下，Kubernetes 模式下的 Kubernetes DNS 名称解析由 Dapr 自动配置。除非需要对 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}}`

10.3 - mDNS

mDNS名称解析组件的详细信息

配置格式

在Dapr的自托管模式中，mDNS会自动配置。使用mDNS作为名称解析提供程序无需进行任何配置。

行为

该组件通过主机系统的mDNS服务来解析目标应用程序。您可以在这里了解更多关于mDNS的信息。

故障排除

在某些云提供商的虚拟网络中，例如Microsoft Azure，mDNS可能不可用。请使用其他提供程序，例如HashiCorp Consul。

在某些企业管理的系统上，如果配置了网络过滤器或代理，macOS上的mDNS可能会被禁用。如果mDNS被禁用且您无法在本地使用服务调用，请与您的IT部门确认。

规格配置字段

不适用，因为在自托管模式下运行时，mDNS由Dapr自动配置。

10.4 - SQLite

详细介绍SQLite名称解析组件

SQLite名称解析组件可以作为mDNS的替代方案，适用于在单节点环境中运行Dapr以及本地开发场景。集群中的Dapr sidecar会将其信息存储在本地机器上的SQLite数据库中。

注意

该组件经过优化，适用于所有Dapr实例运行在同一台物理机器上的场景，数据库通过同一个本地挂载的磁盘进行访问。
通过网络（包括SMB/NFS）使用SQLite名称解析器访问数据库文件可能会导致数据损坏，因此不支持。

配置格式

名称解析通过Dapr配置进行设置。

在配置YAML中，将spec.nameResolution.component属性设置为"sqlite"，然后在spec.nameResolution.configuration字典中传递配置选项。

以下是一个基本的配置示例：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "sqlite"
    version: "v1"
    configuration:
      connectionString: "/home/user/.dapr/nr.db"

规格配置字段

使用SQLite名称解析组件时，spec.nameResolution.configuration字典包含以下选项：

字段	必需	类型	详情	示例
`connectionString`	Y	`string`	SQLite数据库的连接字符串。通常，这是磁盘上文件的路径，可以是相对路径或绝对路径。	`"nr.db"`（相对于工作目录），`"/home/user/.dapr/nr.db"`
`updateInterval`	N	Go duration (作为`string`)	活跃的Dapr sidecar在数据库中更新其状态的间隔，用作健康检查。较小的间隔减少了应用程序离线时返回过时数据的可能性，但增加了数据库的负载。必须至少比`timeout`大1秒。带有秒数分数的值会被截断（例如，`1500ms`变为`1s`）。默认值：`5s`	`"2s"`
`timeout`	N	Go duration (作为`string`)。必须至少为1秒。	数据库操作的超时时间。整数被解释为秒数。默认值为`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`

11 - 中间件组件说明

列出所有支持的中间件组件，这些组件可以集成到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

11.1 - Bearer

通过验证 bearer 令牌，使用 bearer 中间件保护 HTTP 端点

Bearer HTTP 中间件利用 OpenID Connect 在 Web API 上验证 Bearer Token，无需修改应用程序代码。此设计将身份验证和授权与应用程序逻辑分离，使应用程序管理员可以配置身份验证和授权提供者，而不影响应用程序的正常运行。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: bearer-token
spec:
  type: middleware.http.bearer
  version: v1
  metadata:
    - name: audience
      value: "<您的令牌受众，例如应用程序的客户端 ID>"
    - name: issuer
      value: "<您的令牌发行者，例如 'https://accounts.google.com'>"

    # 可选项
    - name: jwksURL
      value: "<JWKS URL，例如 'https://accounts.google.com/.well-known/openid-configuration'>"

规格元数据字段

字段	必需	详情	示例
`audience`	Y	令牌中预期的受众，通常是您的应用程序的客户端 ID，由 OpenID Connect 平台提供。
`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

11.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"

警告

上述示例中使用了明文字符串来表示secret。建议使用secret存储来安全地存储这些secret，具体方法请参见此处。

规范元数据字段

字段	详情	示例
clientId	您的应用程序的客户端ID，是在启用OAuth的平台上创建的凭据的一部分	`"your-client-id"`
clientSecret	您的应用程序的客户端secret，是在启用OAuth的平台上创建的凭据的一部分	`"your-client-secret"`
scopes	空格分隔的、区分大小写的范围字符串列表，通常用于应用程序中的授权	`"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"`

Dapr配置

要应用中间件，必须在配置中引用。请参阅中间件处理管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: oauth2
      type: middleware.http.oauth2

11.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"

警告

上述示例中使用了明文字符串来表示 secret。建议使用 secret 存储来安全地存储这些敏感信息，具体方法请参见这里。

规范元数据字段

字段	详情	示例
clientId	您的应用程序的客户端 ID，是由支持 OAuth 的平台生成的凭证的一部分
clientSecret	您的应用程序的客户端 secret，是由支持 OAuth 的平台生成的凭证的一部分
scopes	空格分隔的、区分大小写的 scopes 字符串列表，通常用于定义应用程序的授权范围	`"https://www.googleapis.com/auth/userinfo.email"`
tokenURL	客户端通过提供授权授予或刷新令牌来获取访问令牌的端点	`"https://accounts.google.com/o/oauth2/token"`
headerName	转发到您的应用程序的授权头名称	`"authorization"`
endpointParamsQuery	指定请求令牌端点的附加参数	`true`
authStyle	可选地指定端点希望客户端 ID 和客户端 secret 发送的方式。请参阅下表中的可能值	`0`

`authStyle` 的可能值

值	含义
`1`	在 POST 请求体中以 application/x-www-form-urlencoded 参数的形式发送 “client_id” 和 “client_secret”。
`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

11.4 - 应用 Open Policy Agent (OPA) 策略

通过中间件对传入请求应用 Open Policy Agent (OPA) 策略

Open Policy Agent (OPA) HTTP 中间件用于对传入的 Dapr HTTP 请求应用 OPA 策略。这可以用于在应用程序端点上实施可重用的授权策略。

组件格式

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 并在响应中设置位置头：
        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`	拒绝响应时返回的状态码	`"https://accounts.google.com"`，`"https://login.salesforce.com"`
`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 值。true 的 allow 将允许请求，而 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
}

11.5 - RouterChecker HTTP 请求路由检查

使用 routerchecker 中间件阻止无效的 HTTP 请求路由

RouterChecker HTTP 中间件组件通过正则表达式来验证 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 配置

要应用中间件，必须在配置中引用。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: routerchecker 
      type: middleware.http.routerchecker

11.6 - Sentinel 容错中间件组件

使用 Sentinel 中间件来保证应用程序的可靠性和弹性

Sentinel 是一个强大的容错组件，专注于流量管理，涵盖流量控制、流量整形、并发限制、熔断降级和自适应系统保护等多个领域，以确保微服务的可靠性和弹性。

Sentinel HTTP 中间件使 Dapr 可以利用 Sentinel 的强大功能来保护您的应用程序。您可以参考 Sentinel Wiki 以获取有关 Sentinel 的更多详细信息。

组件格式

在以下定义中，最大请求数被设定为每秒 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 参考]https://v1-16.docs.dapr.io/zh-hans/reference/api/ 中找到。在上述示例配置中，resource 字段被设置为 POST:/v1.0/invoke/nodeapp/method/neworder。

Dapr 配置

要应用中间件，必须在 configuration 中引用。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: daprConfig
spec:
  httpPipeline:
    handlers:
      - name: sentinel
        type: middleware.http.sentinel

11.7 - Wasm

在HTTP管道中使用Wasm中间件

WebAssembly是一种安全执行由其他语言编译的代码的方法。运行时会执行WebAssembly模块（Wasm），这些模块通常是带有.wasm扩展名的二进制文件。

Wasm HTTP中间件允许您使用编译为Wasm二进制文件的自定义逻辑来处理传入请求或提供响应。换句话说，您可以使用未预编译到daprd二进制文件中的外部文件来扩展Dapr。Dapr嵌入了wazero以在不使用CGO的情况下实现这一点。

Wasm二进制文件可以从URL加载。例如，使用URL file://rewrite.wasm可以从进程的当前目录加载rewrite.wasm文件。在Kubernetes环境中，您可以参考如何：将Pod卷挂载到Dapr sidecar来配置可以包含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"
  - guestConfig
    value: {"environment":"production"}

规范元数据字段

用户至少需要指定一个实现http-handler的Wasm二进制文件。如何编译将在后面描述。

字段	详情	必需	示例
url	包含要实例化的Wasm二进制文件的资源URL。支持的方案包括`file://`、`http://`和`https://`。`file://` URL的路径相对于Dapr进程，除非它以`/`开头。	true	`file://hello.wasm`，`https://example.com/hello.wasm`
guestConfig	传递给Wasm来宾的可选配置。用户可以传递由Wasm代码解析的任意字符串。	false	`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，按如下所示编译，并将名为"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)
}

11.8 - 将请求体转换为大写

测试您的HTTP管道是否正常工作，使用大写中间件

大写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

11.9 - HTTP 路由别名

通过路由别名中间件将任意 HTTP 路由映射为 Dapr 端点

HTTP 路由别名中间件组件允许您将进入 Dapr 的任意 HTTP 路由映射为有效的 Dapr API 端点。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: routeralias 
spec:
  type: middleware.http.routeralias
  version: v1
  metadata:
    # 包含 JSON 或 YAML 格式的字典字符串
    # 字典中的每个键是传入路径，值是映射后的路径
    - 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

11.10 - 速率限制

通过速率限制中间件控制每秒请求数量

HTTP中间件速率限制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 sidecar中独立执行的，而不是在整个集群范围内统一执行。

此外，您还可以使用最大并发设置来限制应用程序的请求处理能力，这种方法适用于所有流量，不论远程IP、协议或路径。

Dapr配置

要应用中间件，必须在配置中进行引用。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  httpPipeline:
    handlers:
    - name: ratelimit
      type: middleware.http.ratelimit

字段	数据类型	可为空	详情
KEY	VARCHAR	N	持有配置属性的 `"Key"`
VALUE	VARCHAR	N	持有配置属性的值
VERSION	VARCHAR	N	持有配置属性的版本
METADATA	JSON	Y	以 JSON 形式持有元数据

Dapr 组件指南

1 - 发布/订阅代理组件规范

发布/订阅组件的重试机制与入站弹性

Generic

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Microsoft Azure

1.1 - Apache Kafka

组件格式

规格元数据字段

注意

认证

注意

None

SASL 密码

Mutual TLS

OAuth2 或 OpenID Connect

AWS IAM

注意

使用 TLS 进行通信

从多个主题消费

发送和接收多条消息

配置批量订阅

每次调用的元数据字段

分区键

消息头

Kafka Pubsub 在消费者端接收到的特殊消息头

接收带有特殊字符的消息头

注意

Avro Schema Registry 序列化/反序列化

配置

重要

发布 Avro 消息

订阅 Avro 主题

创建一个 Kafka 实例

相关链接

1.2 - AWS SNS/SQS

组件格式

注意

警告

规格元数据字段

其他信息

符合AWS规范

SNS/SQS组件行为

SQS FIFO

默认并行concurrencyMode

SQS死信队列

重要

SNS/SQS与Dapr的争用

重要

创建SNS/SQS实例

相关链接

1.3 - Azure Event Hubs

组件格式

注意

规格元数据字段

Microsoft Entra ID 身份验证

示例配置

发送和接收多条消息

配置批量发布

配置批量订阅

配置检查点频率

注意

创建 Azure Event Hub

为每个订阅者创建消费者组

实体管理

订阅 Azure IoT Hub 事件

相关链接

1.4 - Azure Service Bus Topics

组件格式

连接字符串认证

警告

规格元数据字段

Microsoft Entra ID 认证

示例配置

消息元数据

发送带有元数据的消息

接收带有元数据的消息

订阅启用会话的主题

为主题创建 Azure Service Bus broker

默认并行`concurrencyMode`