外部存储服务的 URI 格式

本文介绍 Amazon S3、GCS、和 Azure Blob Storage 存储服务的 URI 格式。基本格式如下:

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

Amazon S3 URI 格式

  • schemes3

  • hostbucket name

  • parameters

    • access-key:访问密钥
    • secret-access-key:秘密访问密钥
    • session-token:临时会话令牌(BR v7.6.0 及之后版本支持)
    • use-accelerate-endpoint:是否在 Amazon S3 上使用加速端点,默认为 false
    • endpoint:Amazon S3 兼容服务自定义端点的 URL,例如 <https://s3.example.com/>
    • force-path-style:使用路径类型 (path-style),而不是虚拟托管类型 (virtual-hosted-style),默认为 true
    • storage-class:上传对象的存储类别,例如 STANDARDSTANDARD_IA
    • sse:加密上传的服务端加密算法,可以设置为空、AES256aws:kms
    • sse-kms-key-id:如果 sse 设置为 aws:kms,则使用该参数指定 KMS ID
    • acl:上传对象的标准 ACL (Canned ACL),例如 privateauthenticated-read
    • role-arn:当需要使用特定的 IAM 角色来访问第三方 Amazon S3 的数据时,使用这个参数来指定 IAM 角色的对应 Amazon Resource Name (ARN)(例如 arn:aws:iam::888888888888:role/my-role)。关于使用 IAM 角色访问第三方 Amazon S3 数据的场景,请参考 AWS 相关文档介绍。(BR v7.6.0 及之后版本支持)
    • external-id:当需要使用特定的 IAM 角色来访问第三方 Amazon S3 的数据时,可能需要同时提供正确的外部 ID 来确保用户有权限代入该 IAM 角色。这个参数用来指定对应的外部 ID,确保成功代入 IAM 角色。外部 ID 可以是任意字符串,并且不是必须的,一般由控制 Amazon S3 数据访问的第三方来指定。如果第三方对于 IAM 角色没有要求指定外部 ID,则可以不需要提供该参数也能顺利代入对应的 IAM 角色,从而访问对应的 Amazon S3 数据。

以下是用于 TiDB Lightning 和 BR 的 Amazon S3 URI 示例,需要指定文件夹路径 testfolder

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

以下是用于 TiCDC sink-uri 的 Amazon S3 URI 示例:

tiup cdc:v7.5.0 cli changefeed create \ --server=http://172.16.201.18:8300 \ --sink-uri="s3://cdc?endpoint=http://10.240.0.38:9000&access-key=${access-key}&secret-access-key=${secret-access-key}" \ --changefeed-id="cdcTest" \ --config=cdc_csv.toml

以下是用于 IMPORT INTO 的 Amazon S3 URI 示例,需要指定具体的文件名 test.csv

s3://external/test.csv?access-key=${access-key}&secret-access-key=${secret-access-key}

GCS URI 格式

  • schemegcsgs

  • hostbucket name

  • parameters

    • credentials-file:迁移工具节点上凭证 JSON 文件的路径
    • storage-class:上传对象的存储类别,例如 STANDARDCOLDLINE
    • predefined-acl:上传对象的预定义 ACL,例如 privateproject-private

以下是用于 TiDB Lightning 和 BR 的 GCS URI 示例,需要指定文件夹路径 testfolder

gcs://external/testfolder?credentials-file=${credentials-file-path}

以下是用于 IMPORT INTO 的 GCS URI 示例,需要指定具体的文件名 test.csv

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

Azure Blob Storage URI 格式

  • schemeazureazblob

  • hostcontainer name

  • parameters

    • account-name:存储账户名
    • account-key:访问密钥
    • sas-token:共享访问签名令牌
    • access-tier:上传对象的存储类别,例如 HotCoolArchive,默认值为该存储账户的默认访问层。
    • 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}