外部存储服务的 URI 格式

本文档描述了外部存储服务的 URI 格式，包括 Amazon S3、GCS 和 Azure Blob Storage。

URI 的基本格式如下：

[scheme]://[host]/[path]?[parameters]

Amazon S3 URI 格式

scheme: s3
host: bucket name
parameters:
- access-key: 指定访问密钥。
- secret-access-key: 指定秘密访问密钥。
- session-token: 指定临时会话令牌。
- use-accelerate-endpoint: 指定是否使用 Amazon S3 的加速终端节点（默认为 false）。
- endpoint: 指定 S3 兼容服务的自定义端点 URL（例如 https://s3.example.com/）。
- force-path-style: 使用路径样式访问而非虚拟托管样式（默认为 true）。
- storage-class: 指定上传对象的存储类别（例如 STANDARD 或 STANDARD_IA）。
- sse: 指定用于加密上传对象的服务器端加密算法（取值选项：空、AES256 或 aws:kms）。
- sse-kms-key-id: 如果 sse 设置为 aws:kms，则指定 KMS ID。
- acl: 指定上传对象的预定义访问控制列表（例如 private 或 authenticated-read）。
- role-arn: 为了让平凯数据库云服务使用特定的 IAM role 访问 Amazon S3 数据，可以在 role-arn URL 查询参数中提供角色的 Amazon Resource Name (ARN)。例如：arn:aws:iam::888888888888:role/my-role。
  i
  Note
  - 若要自动创建 IAM role，可以在平凯数据库云服务控制台中的“导入数据自 Amazon S3”页面，填写 Folder URI 字段，在 Role ARN 字段下点击 Click here to create new one with AWS CloudFormation，然后按照弹出的 Add New Role ARN 对话框中的指示操作。
  - 如果在使用 AWS CloudFormation 创建 IAM role 时遇到困难，可以在 Add New Role ARN 对话框中点击 click Having trouble? Create Role ARN manually，获取平凯数据库云服务账户 ID 和平凯数据库云服务 External ID，然后手动创建角色。在配置 IAM role 时，确保在 Account ID 字段中输入平凯数据库云服务账户 ID，并选择 Require external ID，以防止 confused deputy attacks。
  - 为了增强安全性，可以通过配置较短的 Max session duration 来缩短 IAM role 的有效期。更多信息请参见 AWS 文档中的 Update the maximum session duration for a role。
- external-id: 指定平凯数据库云服务 External ID，平凯数据库云服务访问 Amazon S3 数据时需要此 ID。你可以在平凯数据库云服务控制台的 Add New Role ARN 对话框中获取此 ID。

以下是 BACKUP 和 RESTORE 使用的 Amazon S3 URI 示例。此示例使用文件路径 testfolder。

s3://external/testfolder?access-key=${access-key}&secret-access-key=${secret-access-key}

GCS URI 格式

scheme: gcs 或 gs
host: bucket name
parameters:
- credentials-file: 指定迁移工具节点上的凭证 JSON 文件路径。
- storage-class: 指定上传对象的存储类别（例如 STANDARD 或 COLDLINE）
- predefined-acl: 指定上传对象的预定义访问控制列表（例如 private 或 project-private）

以下是 IMPORT INTO 使用的 GCS URI 示例。在此示例中，你需要指定特定的文件名 test.csv。

gcs://external/test.csv?credentials-file=${credentials-file-path}

Azure Blob Storage URI 格式

scheme: azure 或 azblob
host: container name
parameters:
- account-name: 指定存储账户名。
- account-key: 指定访问密钥。
- sas-token: 指定共享访问签名（SAS）令牌。
- access-tier: 指定上传对象的访问层，例如 Hot、Cool 或 Archive。默认值为存储账户的默认访问层。
- encryption-scope: 指定服务器端加密的 encryption scope。
- encryption-key: 指定用于服务器端加密的 encryption key，使用 AES256 加密算法。

以下是 BR 使用的 Azure Blob Storage URI 示例。在此示例中，你需要指定特定的文件路径 testfolder。

azure://external/testfolder?account-name=${account-name}&account-key=${account-key}