AWS S3 绑定规范

AWS S3 绑定组件的详细文档

组件格式

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

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

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

警告

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

规范元数据字段

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

重要

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

S3 存储桶创建

与 Minio 一起使用

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

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

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

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

version: "3.8"

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

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

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

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

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

绑定支持

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

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

创建对象

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

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

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

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

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

使用预签名 URL 共享对象

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

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

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

响应

响应体包含以下示例 JSON：

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

示例

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

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

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

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

将文本保存到特定文件

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

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

将文件保存为对象

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

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

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

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

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

从文件路径上传

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

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

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

响应

响应体将包含以下 JSON：

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

预签名现有对象

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

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

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

响应

响应体包含以下示例 JSON：

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

获取对象

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

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

元数据参数为：

key - 对象的名称

示例

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

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

响应

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

删除对象

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

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

元数据参数为：

key - 对象的名称

示例

删除对象

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

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

响应

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

列出对象

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

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

数据参数为：

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

响应

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

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

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

AWS S3 绑定规范

组件格式

警告

规范元数据字段

重要

S3 存储桶创建

与 Minio 一起使用

绑定支持

创建对象

使用预签名 URL 共享对象

响应

示例

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

将文本保存到特定文件

将文件保存为对象

从文件路径上传

响应

预签名现有对象

响应

获取对象

示例

响应

删除对象

示例

删除对象

响应

列出对象

响应

相关链接