This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Bindings 组件规格

支持与 Dapr 接口的外部绑定

1: Apple 推送通知服务绑定说明
2: AWS DynamoDB 绑定说明
3: AWS Kinesis 绑定规范
4: AWS S3 绑定规范
5: AWS SES 绑定说明
6: AWS SNS 绑定组件规范
7: AWS SQS 绑定规范
8: Azure Blob Storage 绑定指南
9: Azure Cosmos DB (Gremlin API) 绑定组件说明
10: Azure Cosmos DB (SQL API) 绑定说明
11: Azure Event Grid 绑定规范
12: Azure Event Hubs 绑定规范
13: Azure OpenAI 绑定组件规范
14: Azure Service Bus Queues 绑定规范
15: Azure SignalR 绑定规范
16: Azure Storage Queues 绑定规范
17: Cloudflare Queues 绑定规范
18: commercetools GraphQL 绑定说明
19: Cron 绑定规范
20: GCP Pub/Sub 绑定规范
21: GCP 存储桶绑定指南
22: GraphQL 绑定说明
23: HTTP 绑定规范
24: InfluxDB 绑定规范
25: Kafka 绑定规范
26: Kitex
27: KubeMQ 绑定规范
28: Kubernetes Events 绑定指南
29: MQTT3 绑定规范
30: MySQL & MariaDB 绑定规范
31: PostgreSQL 绑定组件规范
32: Postmark 绑定说明
33: RabbitMQ 绑定规范
34: Redis 绑定规范
35: RethinkDB 绑定规范
36: SFTP 绑定规范
37: SMTP 绑定规范
38: Twilio SendGrid 绑定规范
39: Twilio SMS 绑定说明
40: Wasm
41: Zeebe JobWorker 绑定说明
42: Zeebe 命令绑定说明
43: 阿里云 Tablestore 绑定组件规范
44: 阿里云钉钉绑定组件规范
45: 阿里云对象存储服务绑定指南
46: 阿里云日志存储服务绑定指南
47: 本地存储绑定规范
48: 华为 OBS 绑定规范

下表列出了 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
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
SendGrid		✅	Alpha	v1	1.0
SFTP		✅	Alpha	v1	1.15
SMTP		✅	Alpha	v1	1.0
Twilio		✅	Alpha	v1	1.0
Wasm		✅	Alpha	v1	1.11

Alibaba Cloud

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

Amazon Web Services (AWS)

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

Cloudflare

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

Google Cloud Platform (GCP)

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

Microsoft Azure

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

Zeebe (Camunda Cloud)

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

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

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

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

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

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

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

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

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

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"

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

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

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 输出绑定的信息。

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 时间戳格式。

接收带有元数据的消息

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

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

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

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

注意

所有时间均由服务器设置，并未调整时钟偏差。

为每条消息指定 TTL

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

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

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

调度消息

可以调度消息以进行延迟处理。

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

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

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

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 集成到解决方案中的更多信息，请查看文档

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

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 值！

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

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 调用。

绑定支持

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

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

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

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

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 认证时，可以使用此功能。

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

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

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
}

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 文档了解更多信息。

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

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>再见！"
}

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

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

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

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

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 实例。

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

绑定支持

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

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

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

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

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

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

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	在绑定元数据中定义的自动完成状态

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 文档的根是一个数组而不是对象。

响应

绑定不返回响应正文。

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 字段是必填项。

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

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

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是异步的，因此此绑定没有直接响应（没有回调接口来接收成功或失败的响应，只有在失败时会记录到控制台日志）。

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

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>

响应

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

Bindings 组件规格

Generic

Alibaba Cloud

Amazon Web Services (AWS)

Cloudflare

Google Cloud Platform (GCP)

Microsoft Azure

Zeebe (Camunda Cloud)

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

组件格式

元数据字段说明

私钥

绑定功能支持

推送通知格式

请求格式

响应格式

相关链接

2 - AWS DynamoDB 绑定说明

组件配置格式

警告

规范元数据字段

重要

绑定支持

相关链接

3 - AWS Kinesis 绑定规范

组件格式

警告

规范元数据字段

重要

绑定支持

相关链接

4 - AWS S3 绑定规范

组件格式

警告

规范元数据字段

重要

S3 Bucket 创建

使用 Minio

绑定支持

创建对象

使用预签名 URL 共享对象

响应

示例

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

将文本保存到特定文件

将文件保存为对象

从文件路径上传

响应

预签名现有对象

响应

获取对象

示例

响应

删除对象

示例

删除对象

响应

列出对象

响应

相关链接

5 - AWS SES 绑定说明

组件格式

警告

规范元数据字段

重要

绑定支持

示例请求

相关链接

6 - AWS SNS 绑定组件规范

组件格式

警告

规范元数据字段

重要

绑定支持

相关链接

7 - AWS SQS 绑定规范

组件格式

警告

规范元数据字段

重要