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

Windows
Linux

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

示例

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

将文本保存到特定文件

Windows
Linux

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>

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

Windows
Linux

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 元数据键。

Windows
Linux

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

Windows
Linux

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 - 对象的名称

示例

Windows
Linux

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 - 对象的名称

示例

删除对象

Windows
Linux

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

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

AWS S3 绑定规范

组件格式

警告

规范元数据字段

重要

S3 Bucket 创建

使用 Minio

绑定支持

创建对象

使用预签名 URL 共享对象

响应

示例

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

将文本保存到特定文件

将文件保存为对象

从文件路径上传

响应

预签名现有对象

响应

获取对象

示例

响应

删除对象

示例

删除对象

响应

列出对象

响应

相关链接

Feedback