You need to enable JavaScript to run this app.
导航

SDK 常见问题

最近更新时间2023.09.27 16:24:34

首次发布时间2023.05.10 19:17:12

本文介绍使用 TOS SDK 过程中遇到的常见问题。

索引

使用支持 S3 协议的 SDK 和工具访问 TOS 时,报错 Forbidden path to access server 或 InvalidPathAccess 是什么原因?

以上报错是由于使用 PathStyle 请求方式导致的。 TOS 不支持路径样式(即 PathStyle)的请求方式,仅支持使用虚拟主机(即 VirtualHostStyle)的请求方式。
Path 和 VirtualHost 的区别主要在于 HTTP URL 中存储桶名称的位置,如下所示:

# Path 访问方式 
https://tos-s3-cn-beijing.volces.com/{bucketname} 

# VirtualHost 访问方式 
https://{bucketname}.tos-s3-cn-beijing.volces.com

使用各种支持 S3 协议的 SDK 和工具访问 TOS 时,请务必确保配置了 VirtualHostStyle 的请求方式。例如:

  • 使用 AWS S3 Java SDK 时,需要在客户端初始化时确保设置了禁用 PathStyle 的配置参数:AmazonS3Builder.withPathStyleAccessEnabled(false)
  • 使用 AWS CLI 工具访问 TOS 时,需要在 ~/.aws/config 文件中添加 addressing_style = virtual 内容,确保请求方式为 VirtualHostStyle。

使用 TOS Java SDK 报错 com.fasterxml.jackson.core.JsonParseException 是什么原因?

以上报错通常是因为初始化客户端时设置的 TOS 服务的域名(Endpoint)错误,TOS SDK 当前仅支持使用 TOS 协议域名(例如北京地域域名为 tos-cn-beijing.volces.com),不支持使用 S3 协议域名(例如北京 tos-s3-cn-beijing.volces.com),关于 TOS 支持的域名信息,请参见地域和访问域名

Java SDK 版本依赖管理

下文列举了TOS Java SDK的依赖包及版本,如您遇到java.lang.NoSuchMethodErrorjava.lang.ClassNotFoundException等错误,您可以对比参考以下依赖,解决依赖冲突问题。

<dependencies>
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
        <version>4.9.2</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-annotations</artifactId>
        <version>2.12.5</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.12.5</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>1.7.25</version>
        <scope>compile</scope>
    </dependency>

TOS Java SDK 底层依赖的 okhttp client,依赖了 kotlin-stdlib 的 1.4.10 版本组件。如遇到 okhttp client 的依赖冲突报错,可以在最外层 pom.xml 声明 kotlin-stdlib 的 1.4.10 版本组件依赖。

<dependency>
  <groupId>org.jetbrains.kotlin</groupId>
  <artifactId>kotlin-stdlib</artifactId>
  <version>1.4.10</version>
  <scope>compile</scope>
</dependency>

如何处理 Windows 编译连接问题?

  • 如果提示找不到 MSVCR.120 dll ,您需要单击链接安装 Visual C++ 。
  • 如果提示 0xc000007b 错误,您需要检查是否链接到了正确的 dll。

使用 TOS BrowserJS SDK 请求 TOS 服务遇到跨域问题,如何解决?

您需要先配置桶的 CORS 策略,允许跨域请求,详细配置方式,请参见跨域访问设置

使用 TOS Browser.JS SDK 如何支持 ListBuckets 和 CreateBucket?

由于跨域访问设置(CORS 策略)是配置在桶上的,因此 BrowserJS SDK 无法支持 ListBuckets 和 CreateBucket。

为什么使用 TOS Browser.JS SDK 上传对象感觉很慢?

这个问题有两个方面的原因:

  • 对于单个大对象(MB+ 级别),由于 TOS BrowserJS SDK 是通过用户的浏览器从公网上传,受限于用户本地网络从公网到 TOS 服务的带宽,在本地网络是弱网(例如在移动端使用浏览器上传)和慢网的情况下,可能会导致整个上传耗时较长。

  • 对于批量上传多个对象的情况,受限于浏览器本身的并发限制(例如谷歌浏览器的并发限制是 6),无法执行较高并发的上传请求,导致整体上批量上传较慢。

在希望提升上传对象速度的场景,推荐使用 TOS 工具,例如 tosutiltosbrowser

使用 TOS Python SDK 上传下载对象报错 SignatureDoesNotMatch 是什么原因?

报错原因通常如下:

  • 初始化客户端时,使用的 AK/SK 不正确。

  • 上传/下载的对象名以 . 号开头,当前 Python SDK 不支持以 . 开头的对象名。

如果非以上原因导致的错误,请提交工单联系技术支持。

使用 TOS Python SDK 请求 Unsupported Authorization Type 或 InvalidRequest 是什么原因?

以上报错通常是因为初始化客户端时设置的 TOS 服务的域名(Endpoint)错误,TOS SDK 当前仅支持使用 TOS 协议域名(例如北京地域域名为 tos-cn-beijing.volces.com),不支持使用 S3 协议域名(例如北京 tos-s3-cn-beijing.volces.com),关于 TOS 支持的域名信息,请参见地域和访问域名

如何解决开启 CRC 校验后,上传和下载对象性能差的问题?

您可以设置 enable_crc=False 关闭 CRC 校验。更多信息,请参见配置数据校验

调用接口时返 400 如何处理?

调用接口失败,HTTP状态码返回 400,说明客户端侧的配置或者参数有误,根据返回的信息提示进行重新配置。

使用 TOS SDK 上传或下载对象过程中客户端自动断开,报错 unexpected eof、request timeout、use of closed network connection 等错误是为什么?

以上报错通常是因为客户端到 TOS 服务端的网络高延迟导致的(触发客户端-服务端断流进而请求中断),比如客户端的网络过慢、客户端带宽过低、客户端请求超带宽、客户端 CPU 过高导致收发流异常等,建议您先确认客户端当前的网络以及程序运行环境的负载情况。如果以上均没有问题,您可以提交工单联系技术支持。

使用 TOS SDK 请求报错 server returned an invalid body 是什么原因?

以上报错通常是因为 TOS 服务的域名(Endpoint)配置错误,TOS SDK 当前仅支持使用 TOS 协议域名(例如北京地域域名为 tos-cn-beijing.volces.com),不支持使用 S3 协议域名(例如北京 tos-s3-cn-beijing.volces.com),关于 TOS 支持的域名信息,请参见地域和访问域名

使用 TOS SDK 如何获取错误码、错误信息?

TOS SDK 统一定义了服务端错误(TosServerError)和客户端错误(TosClientError)。各 SDK 错误码的详细获取方式,请参见以下文档:

使用 TOS SDK 生成预签名 URL 是什么原理?是否会与服务端交互?

预签名 URL 完全由 TOS SDK 在本地通过签名算法生成,不会与服务端交互,因此也不会校验有效性(例如桶是否存在、对象是否存在 etc),仅当使用预签名 URL 进行实际请求时,才会进行预签名 URL 有效性校验。

使用 TOS SDK 上传包含特殊字符(如空格、中文)的对象时,需要 URL 编码吗?

不需要,TOS SDK 会自行处理特殊字符的问题,确保上传后桶中对象名和传入的对象名一致。

使用 TOS SDK DownloadFile 接口下载文件时为什么会产生 .temp 临时文件?

TOS SDK 下载对象时,会首先生成 .temp 临时文件并将下载的数据写入该临时文件,当临时文件完全写入成功后,再重命名成最终的文件,避免已有文件被未写入完成的中间态文件覆盖导致已有文件损坏。

TOS SDK 如何使用 STS Token 初始化客户端?

TOS SDK 支持通过临时 AK、临时 SK 和 STS Token 生成客户端,常用主流语言的初始化示例如下:

如何使用 TOS SDK 删除目录?

TOS API 没有提供删除目录的接口,使用 TOS SDK 可以通过组合列举对象和删除对象接口实现,您可以参考以下文档设置:

如果您需要定期删除桶中的对象,您可以创建生命周期规则,详细信息,请参见设置生命周期规则

如何通过 TOS SDK 获取对象下载链接(URL)?

  • 如果对象 ACL 为公共读,您可以自行拼接对象的下载链接,拼接方式为 https://{bucketname}.{endpoint}/{objectkey}
  • 如果对象非公共读,则可以通过 TOS SDK 的 PreSignedURL 函数生成对象带签名的下载链接。

如何开启 TOS SDK 的日志?

TOS SDK 的日志是默认关闭的,如果您需要打开日志,可以参考以下文档:

如何使用 TOS SDK 实现分片上传、下载或复制?

TOS SDK 统一封装了 UploadFile、DownloadFile、ResumableCopyObject 函数分别用于实现分片上传、分片下载和分片复制,支持设置并发度并实现了断点续传能力,详细示例代码,请参见各语言的 SDK 文档。

如何获取对象某个区间的数据?

如果想获取对象某个区间的数据,可以通过 Range 下载方式进行下载,Range 下载还可以把大对象分成多个Range下载,提升下载效率,具体使用示例,请参见范围下载 Java SDK范围下载 Go SDK范围下载 C++ SDK范围下载 Node.js SDK范围下载 Browser.js SDK范围下载 Python SDK

如何添加重试策略?

从 2.1.0 版本开始,TOS Java SDK 新增了失败重试机制,对于服务端返回的 429 和 5xx 错误,默认会进行指数退避重试,最大重试次数默认为 3。您可以在初始化 TOSV2Client 时,通过 TOSClientConfiguration 配置 maxRetryCount 参数来调整最大重试次数,设置为 0 即可关闭重试机制。具体说明,请参见初始化客户端
TOS Go SDK、TOS Node.js SDK 和 TOS .NET SDK 自身没有失败重试机制,在网络环境不好的场景下,可能出现网络导致的请求失败,建议您根据实际业务情况在自己代码上添加重试机制。

警告

请勿无限重试,建议重试2 ~ 3次即可,重试会导致指数回退一段时间。如果一段时间内重试的失败率比较高,建议您放弃重试。

使用 TOS Android SDK 出现兼容性问题,报错 java.lang.ClassNotFoundException 或 java.lang.NoClassDefFoundException 错误如何解决?

以上报错通常是因为客户端的 Android 环境版本较低导致,需要进行脱糖处理,详细配置方式,请参见安装 Android SDK 的注意事项