link之家

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

OSS相关概念

存储类型（Storage Class）

OSS提供标准、低频访问、归档、冷归档四种存储类型，全面覆盖从热到冷的各种数据存储场景。其中标准存储类型提供高持久、高可用、高性能的对象存储服务，能够支持频繁的数据访问；低频访问存储类型适合长期保存不经常访问的数据（平均每月访问频率1到2次），存储单价低于标准类型；归档存储类型适合需要长期保存（建议半年以上）的归档数据；冷归档存储适合需要超长时间存放的极冷数据。更多信息，请参见存储类型介绍。

存储空间（Bucket）

存储空间是您用于存储对象（Object）的容器，所有的对象都必须隶属于某个存储空间。存储空间具有各种配置属性，包括地域、访问权限、存储类型等。您可以根据实际需求，创建不同类型的存储空间来存储不同的数据。

对象（Object）

对象是OSS存储数据的基本单元，也被称为OSS的文件。对象由元信息（Object Meta）、用户数据（Data）和文件名（Key）组成。对象由存储空间内部唯一的Key来标识。对象元信息是一组键值对，表示了对象的一些属性，例如最后修改时间、大小等信息，同时您也可以在元信息中存储一些自定义的信息。

地域（Region）

地域表示OSS的数据中心所在物理位置。您可以根据费用、请求来源等选择合适的地域创建Bucket。更多信息，请参见 OSS已开通的地域。

访问域名（Endpoint）

Endpoint表示OSS对外服务的访问域名。OSS以HTTP RESTful API的形式对外提供服务，当访问不同地域的时候，需要不同的域名。通过内网和外网访问同一个地域所需要的域名也是不同的。更多信息，请参见各个Region对应的Endpoint 。

访问密钥（AccessKey）

AccessKey简称AK，指的是访问身份验证中用到的AccessKey ID和AccessKey Secret。OSS通过使用AccessKey ID和AccessKey Secret对称加密的方法来验证某个请求的发送者身份。AccessKey ID用于标识用户；AccessKey Secret是用户用于加密签名字符串和OSS用来验证签名字符串的密钥，必须保密。关于获取AccessKey的方法，请参见获取AccessKey 。

OSS常见操作

创建Bucket

在上传文件（Object）到OSS之前，您需要创建一个用于存储文件的Bucket。Bucket具有各种配置属性，包括地域、访问权限以及其他元数据。创建Bucket的具体操作，请参见创建存储空间。

Bucket创建完成后，您可以通过多种方式上传不同大小的文件。有关上传文件的具体操作，请参见上传文件。

文件上传完成后，您可以将文件下载至浏览器默认路径或本地指定路径。有关下载文件的具体操作，请参见下载文件。

当您Bucket内存储了大量的文件后，您可以选择列举Bucket内的全部或部分文件。有关列举文件的具体操作，请参见列举文件。

当您不再需要保留上传的文件时，您可以手动删除单个或多个文件，也可以通过配置生命周期规则自动删除单个或多个文件。有关删除文件的具体操作，请参见删除文件。

OSS重要特性

版本控制是针对存储空间（Bucket）级别的数据保护功能。开启版本控制后，针对数据的覆盖和删除操作将会以历史版本的形式保存下来。您在错误覆盖或者删除文件（Object）后，能够将Bucket中存储的Object恢复至任意时刻的历史版本。有关版本控制的更多信息，请参见版本控制介绍。

Bucket Policy

Bucket拥有者可通过Bucket Policy授权不同用户以何种权限访问指定的OSS资源。例如您需要进行跨账号或对匿名用户授权访问或管理整个Bucket或Bucket内的部分资源，或者需要对同账号下的不同RAM用户授予访问或管理Bucket资源的不同权限，例如只读、读写或完全控制的权限等。有关配置Bucket Policy的操作步骤，请参见通过Bucket Policy授权用户访问指定资源。

跨区域复制

跨区域复制（Cross-Region Replication）是跨不同OSS数据中心（地域）的Bucket自动、异步（近实时）复制Object，它会将Object的创建、更新和删除等操作从源存储空间复制到不同区域的目标存储空间。跨区域复制功能满足Bucket跨区域容灾或用户数据复制的需求。有关跨区域复制的更多信息，请参见跨区域复制。

服务器端加密：上传文件时，OSS对收到的文件进行加密，再将得到的加密文件持久化保存；下载文件时，OSS自动将加密文件解密后返回给用户，并在返回的HTTP请求Header中，声明该文件进行了服务器端加密。有关服务器端加密的更多信息，请参见服务器端加密。

客户端加密：将文件上传到OSS之前在本地进行加密。有关客户端加密的更多信息，请参见客户端加密。

OSS使用方式

OSS提供多种灵活的上传、下载和管理方式。

通过控制台管理OSS

OSS提供了Web服务页面，您可以登录 OSS控制台管理您的OSS资源。更多信息，请参见控制台用户指南。

通过API或SDK管理OSS

OSS提供RESTful API和各种语言的SDK开发包，方便您快速进行二次开发。更多信息，请参见 OSS API参考和 OSS SDK参考。

通过工具管理OSS

OSS提供图形化管理工具ossbrowser、命令行管理工具ossutil、FTP管理工具ossftp等各种类型的管理工具。更多信息，请参见 OSS常用工具。

通过云存储网关管理OSS

OSS的存储空间内部是扁平的，没有文件系统的目录等概念，所有的对象都直接隶属于其对应的存储空间。如果您想要像使用本地文件夹和磁盘那样来使用OSS存储服务，可以通过配置云存储网关来实现。更多信息，请参见云存储网关产品详情页面。

其他相关服务

您把数据存储到OSS以后，就可以使用阿里云提供的其他产品和服务对其进行相关操作。

以下是您会经常使用到的阿里云产品和服务：

图片处理：对存储在OSS上的图片进行格式转换、缩放、裁剪、旋转、添加水印等各种操作。更多信息，请参见快速使用OSS图片处理服务。

云服务器ECS：提供简单高效、处理能力可弹性伸缩的云端计算服务。更多信息，请参见 ECS产品详情页面。

内容分发网络CDN：将OSS资源缓存到各区域的边缘节点，利用边缘节点缓存的数据，提升同一个文件，被边缘节点客户大量重复下载的体验。更多信息，请参见 CDN产品详情页面。

E-MapReduce：构建于ECS上的大数据处理的系统解决方案，基于开源的Apache Hadoop和Apache Spark，方便您分析和处理自己的数据。更多信息，请参见 E-MapReduce产品详情页面。

媒体处理：将存储于OSS的音视频转码成适合在PC、TV以及移动终端上播放的格式。并基于海量数据深度学习，对音视频的内容、文字、语音、场景多模态分析，实现智能审核、内容理解、智能编辑。更多信息，请参见媒体处理产品详情页面。

在线迁移服务：您可以使用在线迁移服务将第三方数据源，如亚马逊AWS、谷歌云等数据轻松迁移至OSS。更多信息，请参见在线迁移服务使用教程。

离线迁移服务：如果您有TB或PB级别的海量数据需要上传到OSS，但本地的网络带宽不够，扩容成本高，可以使用闪电立方离线数据迁移服务。更多信息，请参见离线迁移（闪电立方）介绍。

其他阿里云存储服务

除了对象存储以外，阿里云还提供文件存储、块存储等类型的存储服务，满足您不同场景下的业务需求。详细信息，请参见阿里云存储服务介绍和阿里云存储产品文档。

有关阿里云存储服务的客户案例、解决方案等，请参见阿里云存储产品家族。

OSS作为阿里巴巴全集团数据存储的核心基础设施，多年支撑双11业务高峰，历经高可用与高可靠的严苛考验。OSS的多重冗余架构设计，为数据持久存储提供可靠保障。同时，OSS基于高可用架构设计，消除单点故障，确保数据业务的持续性。

服务可用性不低于99.995%。

数据设计持久性不低于99.9999999999%（12个9）。

规模自动扩展，不影响对外服务。

数据自动多重冗余备份。

提供企业级多层次安全防护，包括服务端加密、客户端加密、防盗链、通过Bucket Policy限制IP黑白名单访问、细粒度权限管控、日志审计、WORM特性等。

多用户资源隔离机制，支持异地容灾机制。

获得多项合规认证，包括SEC、FINRA等，满足企业数据安全与合规要求。

提供多种数据处理能力，如图片处理、视频截帧、文档预览、图片场景识别、人脸识别、SQL就地查询等，并无缝对接Hadoop生态、以及阿里云函数计算、EMR、DataLakeAnalytics、BatchCompute、MaxCompute、DBS等产品，满足企业数据分析与管理的需求。需要额外采购，单独部署。

OSS其他优势

方便、快捷的使用方式

提供标准的RESTful API接口、丰富的SDK包、客户端工具、控制台。您可以像使用文件一样方便地上传、下载、检索、管理用于Web网站或者移动应用的海量数据。

不限制存储空间大小。您可以根据所需存储量无限扩展存储空间，解决了传统硬件存储扩容问题。

支持流式写入和读出。特别适合视频等大文件的边写边读业务场景。

支持数据生命周期管理。您可以通过设置生命周期规则，将到期数据批量删除或者转储为更低成本的低频访问、归档存储、冷归档存储。

强大、灵活的安全机制

提供STS和URL鉴权和授权机制、IP黑白名单、防盗链、主子账号等功能。

提供用户级别资源隔离机制和多集群同步机制。

提供服务器端加密和客户端加密，并支持基于SSL/TLS的HTTPS加密传输，有效防止数据在云端的潜在安全风险。

提供版本控制功能，防止文件被误删除或覆盖而造成数据丢失。

数据冗余机制

OSS采用数据冗余存储机制，将每个对象的不同冗余存储在同一个区域内多个设施的多个设备上，确保硬件失效时的数据持久性和可用性。

OSS针对对象的操作具有强一致性。对象一旦上传或复制成功，即可立即读取，且冗余写入多个设备。

OSS会通过计算网络流量包的校验和，验证数据包在客户端和服务端之间传输中是否出错，保证数据完整传输。

OSS的冗余存储机制，可支持两个存储设施并发损坏时，仍维持数据不丢失。

当数据存入OSS后，OSS会检测和修复丢失的冗余，确保数据持久性和可用性。

OSS会周期性地通过校验等方式验证数据的完整性，及时发现因硬件失效等原因造成的数据损坏。当检测到数据有部分损坏或丢失时，OSS会利用冗余数据重建并修复损坏数据。

图片处理：支持JPG、PNG、BMP、GIF、WebP、TIFF等多种图片格式的转换，以及缩略图、剪裁、水印、缩放等多种操作。

音视频转码：提供高质量、高速并行的音视频转码能力，让您的音视频文件轻松应对各种终端设备。

互联网访问加速：提供传输加速服务，可优化互联网传输链路和协议栈，大幅减少数据远距离传输超时的比例，极大地提升用户上传和下载体验。更多详情，请参见传输加速。

内容加速分发：OSS作为源站，搭配CDN进行内容分发，提升同一个文件被重复下载的体验。

本文介绍对象存储OSS的主要应用场景。

图片和音视频等应用的海量存储

OSS可用于图片、音视频、日志等海量文件的存储。各种终端设备、Web网站程序、移动应用可以直接向OSS写入或读取数据。OSS支持流式写入和文件写入两种方式。

网页或者移动应用的静态和动态资源分离

利用海量互联网带宽，OSS可以实现海量数据的互联网并发下载。OSS提供原生的传输加速功能，支持上传加速、下载加速，提升跨国、跨洋数据上传、下载的体验。同时，OSS也可以结合CDN产品，提供静态内容存储、分发到边缘节点的解决方案，利用CDN边缘节点缓存的数据，提升同一个文件被同一地区客户大量重复并发下载的体验。

云端数据处理

上传文件到OSS后，可以配合媒体处理服务和图片处理服务进行云端的数据处理。场景3

本文将向您介绍对象存储OSS产品中涉及的几个基本概念，以便于您更好地理解OSS产品。

存储空间（Bucket）

存储空间是用户用于存储对象（Object）的容器，所有的对象都必须隶属于某个存储空间。存储空间具有各种配置属性，包括地域、访问权限、存储类型等。用户可以根据实际需求，创建不同类型的存储空间来存储不同的数据。

同一个存储空间的内部是扁平的，没有文件系统的目录等概念，所有的对象都直接隶属于其对应的存储空间。

每个用户可以拥有多个存储空间。

存储空间的名称在OSS范围内必须是全局唯一的，一旦创建之后无法修改名称。

存储空间内部的对象数目没有限制。

存储空间的命名规范如下：

只能包括小写字母、数字和短划线（-）。

必须以小写字母或者数字开头和结尾。

长度必须在3~63字符之间。

存储空间总结：

命名规范。

创建存储空间:包括地域、访问权限、存储类型等。

列举存储空间:通过设置prefix、marker或者max-keys参数列举满足指定条件的存储空间。

获取存储空间的地域信息:通过 GetBucketLocation接口返回的Location字段查看存储空间所属的地域信息。

生命周期：策略创建生命周期规则，定期将存储空间（Bucket）内的多个文件（Object）转储为指定存储类型，或者将过期的Object和碎片删除，从而节省存储费用

存储空间清单:清单功能获取存储空间（Bucket）中指定文件（Object）的数量、大小、存储类型、加密状态等信息。

绑定自定义域名:文件（Object）上传至存储空间（Bucket）后，OSS会自动生成文件URL，您可以直接通过文件URL访问该文件。

传输加速:OSS传输加速利用全球分布的云机房，将全球各地用户对您存储空间（Bucket）的访问，经过智能路由解析至就近的接入点，使用优化后的网络及协议，为云存储互联网的上传、下载提供端到端的加速方案。

设置跨域资源共享:跨域资源共享CORS（Cross-Origin Resource Sharing）简称跨域访问，是HTML5提供的标准跨域解决方案，允许Web应用服务器进行跨域访问控制，确保跨域数据传输的安全性。

存储空间标签:通过存储空间（Bucket）的标签功能，对Bucket进行分类管理，例如通过设置不同的标签来标记不同用途的Bucket，设置对拥有指定标签的Bucket设置访问权限等。

删除存储空间:当您不再需要保留某个存储空间（Bucket）时，可将其删除，以免产生额外费用。

OSS加速器:随着互联网业务的发展，越来越多的业务对于数据的吞吐量有了更高的要求。为此，对象存储OSS推出加速器功能，可以缓存OSS中的热点文件（Object），提供高性能、高吞吐量的数据访问服务。

对象（Object）

对象是OSS存储数据的基本单元，也被称为OSS的文件。和传统的文件系统不同，对象没有文件目录层级结构的关系。对象由元信息（Object Meta），用户数据（Data）和文件名（Key）组成，并且由存储空间内部唯一的Key来标识。对象元信息是一组键值对，表示了对象的一些属性，比如最后修改时间、大小等信息，同时用户也可以在元信息中存储一些自定义的信息。

对象的生命周期是从上传成功到被删除为止。在整个生命周期内，除通过追加方式上传的Object可以通过继续追加上传写入数据外，其他方式上传的Object内容无法编辑，您可以通过重复上传同名的对象来覆盖之前的对象。

对象的命名规范如下：

使用UTF-8编码。

长度必须在1~1023字符之间。

不能以正斜线（/）或者反斜线（\）开头。

对象总结：

三种类型：通过简单上传生成的Object类型为Normal。
通过分片上传生成的Object类型为Multipart。
通过追加上传生成的Object类型为Appendable，且仅支持在Appendable类型的Object后直接追加内容。

上传文件（Object）：简单上传、分片上传、断点续传上传、上传回调、授权给第三方上传、表单上传、追加上传、RTMP推流上传

下载文件：简单下载、断点续传下载、授权给第三方下载

管理文件：列举文件、拷贝文件、解冻文件、删除文件、对象标签、管理文件元信息、通过目录管理文件、单链接限速、使用SelectObject查询文件

ObjectKey

在各语言SDK中，ObjectKey、Key以及ObjectName是同一概念，均表示对Object执行相关操作时需要填写的Object名称。例如向某一存储空间上传Object时，ObjectKey表示上传的Object所在存储空间的完整名称，即包含文件后缀在内的完整路径，如填写为abc/efg/123.jpg。

Region（地域）

Region表示OSS的数据中心所在物理位置。用户可以根据费用、请求来源等选择合适的地域创建Bucket。一般来说，距离用户更近的Region访问速度更快。详情请参见 OSS已经开通的Region 。

Region是在创建Bucket的时候指定的，一旦指定之后就不允许更改。该Bucket下所有的Object都存储在对应的数据中心，目前不支持Object级别的Region设置。

Endpoint（访问域名）

Endpoint表示OSS对外服务的访问域名。OSS以HTTP RESTful API的形式对外提供服务，当访问不同的Region的时候，需要不同的域名。通过内网和外网访问同一个Region所需要的Endpoint也是不同的。例如杭州Region的外网Endpoint是oss-cn-hangzhou.aliyuncs.com，内网Endpoint是oss-cn-hangzhou-internal.aliyuncs.com。具体的内容请参见各个Region对应的Endpoint 。

AccessKey（访问密钥）

AccessKey简称AK，指的是访问身份验证中用到的AccessKeyId和AccessKeySecret。OSS通过使用AccessKeyId和AccessKeySecret对称加密的方法来验证某个请求的发送者身份。AccessKeyId用于标识用户；AccessKeySecret是用户用于加密签名字符串和OSS用来验证签名字符串的密钥，必须保密。对于OSS来说，AccessKey的来源有：

Bucket的拥有者申请的AccessKey。

被Bucket的拥有者通过RAM授权给第三方请求者的AccessKey。

被Bucket的拥有者通过STS授权给第三方请求者的AccessKey。

Object操作在OSS上具有原子性，操作要么成功要么失败，不会存在有中间状态的Object。OSS保证用户一旦上传完成之后读到的Object是完整的，OSS不会返回给用户一个部分上传成功的Object。

Object操作在OSS同样具有强一致性，用户一旦收到了一个上传（PUT）成功的响应，该上传的Object就已经立即可读，并且Object的冗余数据已经写成功。不存在一种上传的中间状态，即read-after-write却无法读取到数据。对于删除操作也是一样的，用户删除指定的Object成功之后，该Object立即变为不存在。

数据冗余机制

OSS使用基于纠删码、多副本的数据冗余存储机制，将每个对象的不同冗余存储在同一个区域内多个设施的多个设备上，确保硬件失效时的数据持久性和可用性。

OSS Object操作具有强一致性，用户一旦收到了上传或复制成功的响应，则该上传的Object就已经立即可读，且数据已经冗余写入到多个设备中。

OSS会通过计算网络流量包的校验和，验证数据包在客户端和服务端之间传输中是否出错，保证数据完整传输。

OSS的冗余存储机制，可支持两个存储设施并发损坏时，仍维持数据不丢失。

当数据存入OSS后，OSS会检测和修复丢失的冗余，确保数据持久性和可用性。

OSS会周期性地通过校验等方式验证数据的完整性，及时发现因硬件失效等原因造成的数据损坏。当检测到数据有部分损坏或丢失时，OSS会利用冗余的数据，进行重建并修复损坏数据。

访问控制：

Bucket ACL分为public-read-write（公共读写）、public-read（公共读）和private（私有）三种。
Object ACL分为继承Bucket、public-read-write（公共读写）、public-read（公共读）和private（私有）四种。

Allow：允许访问请求，即比对Policy命中了Allow规则。
Explicit Deny：显式拒绝访问请求，即比对Policy命中了Deny规则
Implicit Deny：隐式拒绝访问请求，即Policy不存在、或比对Policy没有命中Allow或Deny规则。

数据容灾：

同城冗余存储
跨区域复制
同区域复制
特殊场景下的复制行为
数据复制问题排查

数据加密：

服务器端加密
客户端加密

版本控制：

版本控制介绍
开启版本控制下Object的操作
暂停版本控制下Object的操作
删除标记
常见问题

OSS请求流程
在Header中包含签名
在URL中包含签名
签名常见问题

使用STS临时访问凭证访问OSS

防盗链功能通过设置Referer白名单以及是否允许空Referer，限制仅白名单中的域名可以访问您Bucket内的资源。OSS支持基于HTTP和HTTPS header中表头字段Referer的方法设置防盗链。
是否进行防盗链验证的具体场景如下：
仅当通过签名URL或者匿名访问Object时，进行防盗链验证。
当请求的Header中包含Authorization字段，不进行防盗链验证。

合规保留策略

OSS沙箱

OSS高防

敏感数据保护

日志转存：

访问OSS的过程中会产生大量的访问日志。您可以通过日志转存功能将这些日志按照固定命名规则，以小时为单位生成日志文件写入您指定的存储空间（Bucket）。
对于已存储的日志，您可以通过阿里云日志服务或搭建Spark集群等方式进行分析。
生成日志的源Bucket和存储日志的目标Bucket可以相同也可以不同，但是必须属于同一账号下的相同地域。
日志文件以小时为单位生成，但并不表示某个时段的日志文件记录了该时段的所有请求，部分请求可能会出现在上一时段或下一时段的日志文件中。
在您关闭日志转存功能前，OSS的日志文件会一直生成。请及时清理不再需要的日志文件，以减少您的存储费用。
您可以通过生命周期规则定期删除日志文件。更多信息，请参见基于最后一次修改时间的生命周期规则介绍。
OSS会根据需求在日志的尾部添加一些字段，请您在开发日志处理工具时考虑兼容性的问题。

实时日志查询：

访问对象存储OSS的过程中会产生大量的访问日志。实时日志查询功能将OSS与日志服务SLS相结合，允许您在OSS控制台直接查询OSS的访问日志，帮助您完成OSS访问的操作审计、访问统计、异常事件回溯和问题定位等工作，提升您的工作效率并更好地帮助您基于数据进行决策。
3分钟内将日志实时推送到日志服务实例中，支持在OSS控制台直接查看实时日志。
提供日志分析服务，定制了常用的分析报表，数据查询更方便。
支持实时查询和分析原始日志，并按照Bucket名称、Object名称、API操作、时间等条件过滤日志。

根据Object的名称（Key）唯一的获取该Object的内容。

虽然用户可以使用类似test1/test.jpg的名字，但是这并不表示用户的Object是保存在test1目录下面的。对于OSS来说，test1/test.jpg仅仅只是一个字符串，与example.jpg并没有本质的区别。因此不同名称的Object之间的访问消耗的资源是类似的。

一个名为test1/test.jpg的文件，访问过程需要先访问到test1这个目录，然后再在该目录下查找名为test.jpg的文件。支持海量的用户并发访问。支持文件的修改，比如修改指定偏移位置的内容、截断文件尾部等。也支持文件夹的操作，比如重命名目录、删除目录、移动目录等非常容易。 OSS保存的Object不支持修改（追加写Object需要调用特定的接口，生成的Object也和正常上传的Object类型上有差别）。用户哪怕是仅仅需要修改一个字节也需要重新上传整个Object。

OSS可以通过一些操作来模拟类似文件夹的功能，但是代价非常昂贵。比如重命名目录，希望将test1目录重命名成test2，那么OSS的实际操作是将所有以test1/开头的Object都重新复制成以test2/开头的Object，这是一个非常消耗资源的操作。因此在使用OSS的时候要尽量避免类似的操作。

受限于单个设备的性能。访问越深的目录消耗的资源也越大，操作拥有很多文件的目录也会非常慢。

因此，将OSS映射为文件系统是非常低效的，也是不建议的做法。如果一定要挂载成文件系统的话，建议尽量只做写新文件、删除文件、读取文件这几种操作。使用OSS应该充分发挥其优点，即海量数据处理能力，优先用来存储海量的非结构化数据，比如图片、视频、文档等。

以下是OSS与文件系统的概念对比：

对象存储 OSS文件系统

开始使用OSS

阿里云对象存储OSS（Object Storage Service）为您提供基于网络的数据存取服务。使用OSS，您可以通过网络随时存储和调用包括文本、图片、音视频在内的各类数据文件。

使用控制台

您可以通过OSS控制台创建Bucket，并将文件上传至Bucket。上传完成后，将文件（Object）下载至本地或者通过生成签名URL的方式将文件分享给第三方，供其下载或预览。更多信息，请参见控制台使用流程。

观看以下视频快速了解如何通过控制台使用OSS。

使用命令行管理工具ossutil

ossutil是OSS的命令行工具，支持Windows、Linux、macOS系统。您可以通过ossutil提供的方便、简洁、丰富的Bucket和Object命令管理您的OSS。更多信息，请参见命令行工具ossutil快速入门。

使用图形化管理工具ossbrowser

ossbrowser是OSS的图形化工具，支持Windows、Linux、macOS系统。您可以通过ossbrowser的图形化界面方便直观地管理Bucket、上传下载Object和文件夹（目录）、简化Policy授权等操作。更多信息，请参见图形化管理工具ossbrowser快速入门。

ossbrowser是桌面式图形化工具，所以传输速度和性能不如命令行工具ossutil。

使用API和SDK

OSS提供Java、Python、PHP、Go等多种语言的API和SDK包，方便您快速进行二次开发。各语言SDK示例，请参见 OSS SDK示例。各API接口的详细信息，请参见 OSS API文档。

基于OSS的文件系统管理

OSS的存储空间内部是扁平的，没有文件系统的目录等概念，所有的对象都直接隶属于其对应的存储空间。如果您想要像使用本地文件夹和磁盘那样来使用OSS存储服务，可以通过配置云存储网关来实现。通过云存储网关提供的NFS、SMB（CIFS）、iSCSI协议，OSS的存储资源会以Bucket为基础映射成本地文件夹或者磁盘。您可以通过文件读写操作访问OSS资源，无缝衔接基于POSIX和块访问协议的应用，降低应用改造和学习成本。更多信息，请参见通过云存储网关挂载OSS 。

Java SDK快速入门

本文介绍如何快速使用OSS Java SDK完成常见操作，如创建存储空间（Bucket）、上传文件（Object）、下载文件等。

已安装Java SDK。

OSS Java SDK提供了基于Maven和Ant的示例工程。您可以在本地设备上编译和运行示例工程，或者以示例工程为基础开发您的应用。工程的编译和运行方法，请参见工程目录下的README.md。

Maven示例工程： aliyun-oss-java-sdk-demo-mvn.zip

Ant示例工程： aliyun-oss-java-sdk-demo-ant.zip

创建存储空间

存储空间是OSS的全局命名空间，相当于数据的容器，可以存储若干文件。

说明关于获取Endpoint的更多信息，请参见访问域名和数据中心。关于存储空间的命名规范的更多信息，请参见基本概念中的命名规范。

以下代码用于创建examplebucket存储空间。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写Bucket名称，例如examplebucket。
String bucketName = "examplebucket";
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
// 创建存储空间。
ossClient.createBucket(bucketName);
// 关闭OSSClient。
ossClient.shutdown();

关于创建存储空间的更多信息，请参见创建存储空间。

以下代码用于上传文件到OSS。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写Bucket名称，例如examplebucket。
String bucketName = "examplebucket";
// 填写文件名。文件名包含路径，不包含Bucket名称。例如exampledir/exampleobject.txt。
String objectName = "exampledir/exampleobject.txt";
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
String content = "Hello OSS";
ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
// 关闭OSSClient。
ossClient.shutdown();

关于上传文件的更多信息，请参见上传文件。

以下代码用于从OSS下载文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写Bucket名称，例如examplebucket。
String bucketName = "examplebucket";
// 填写文件名。文件名包含路径，不包含Bucket名称。例如exampledir/exampleobject.txt。
String objectName = "exampledir/exampleobject.txt";
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
// 调用ossClient.getObject返回一个OSSObject实例，该实例包含文件内容及文件元信息。
OSSObject ossObject = ossClient.getObject(bucketName, objectName);
// 调用ossObject.getObjectContent获取文件输入流，可读取此输入流获取其内容。
InputStream content = ossObject.getObjectContent();
if (content != null) {
    BufferedReader reader = new BufferedReader(new InputStreamReader(content));
    while (true) {
        String line = reader.readLine();
        if (line == null) break;
        System.out.println("\n" + line);
    // 数据读取完成后，获取的流必须关闭，否则会造成连接泄漏，导致请求无连接可用，程序无法正常工作。
    content.close();
// 关闭OSSClient。
ossClient.shutdown();

关于下载文件的更多信息，请参见下载文件。

以下代码用于列举examplebucket存储空间下的文件。默认列举100个文件。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写Bucket名称，例如examplebucket。
String bucketName = "examplebucket";
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
// ossClient.listObjects返回ObjectListing实例，包含此次listObject请求的返回结果。
ObjectListing objectListing = ossClient.listObjects(bucketName);
// objectListing.getObjectSummaries获取所有文件的描述信息。
for (OSSObjectSummary objectSummary : objectListing.getObjectSummaries()) {
    System.out.println(" - " + objectSummary.getKey() + "  " +
            "(size = " + objectSummary.getSize() + ")");
// 关闭OSSClient。
ossClient.shutdown();

发起请求
使用阿里云SDK发起请求
使用REST API发起请求

API参考

阿里云对象存储服务（Object Storage Service，简称OSS），是阿里云对外提供的海量、安全、低成本、高可靠的云存储服务。您可以通过本文档提供的简单的REST接口，在任何时间、任何地点、任何互联网设备上进行上传和下载数据。基于OSS，您可以搭建出各种多媒体分享网站、网盘、个人和企业数据备份等基于大规模数据的服务。

您使用的OSS资源和相关功能，都有一定的限制，具体请参见 OSS使用限制。

OSS API参考主要介绍接口的请求语法、相关参数含义以及请求和返回示例。如果要进行快速二次开发，建议您使用SDK开发包。关于SDK的安装和使用，请参见 OSS SDK参考。

OSS定价

关于OSS的价格，请参见 OSS详细价格信息。关于OSS的计量计费方式，请参见 OSS计量项和计费项。

请参见 OSS常见错误响应。

中文英文说明 Bucket 存储空间是您用于存储对象（Object）的容器，所有的对象都必须隶属于某个存储空间。对象/文件 Object 对象是 OSS 存储数据的基本单元，也被称为OSS的文件。对象由元信息（Object Meta）、用户数据（Data）和文件名（Key）组成。对象由存储空间内部唯一的Key来标识。 Region 地域表示 OSS 的数据中心所在物理位置。您可以根据费用、请求来源等综合选择数据存储的地域。详情请查看 OSS已经开通的Region 。 Endpoint Endpoint 表示OSS对外服务的访问域名。OSS以HTTP RESTful API的形式对外提供服务，当访问不同地域的时候，需要不同的域名。通过内网和外网访问同一个地域所需要的域名也是不同的。具体的内容请参见各个Region对应的Endpoint 。 AccessKey AccessKey，简称 AK，指的是访问身份验证中用到的AccessKeyId 和AccessKeySecret。OSS通过使用AccessKeyId 和AccessKeySecret对称加密的方法来验证某个请求的发送者身份。AccessKeyId用于标识用户，AccessKeySecret是用户用于加密签名字符串和OSS用来验证签名字符串的密钥，其中AccessKeySecret 必须保密。 Options 浏览器在发送跨域请求之前会发送一个preflight请求（Options）给OSS，并带上特定的来源域、HTTP方法和header等信息，以决定是否发送真正的请求。元数据索引（MetaQuery） OpenMetaQuery 为Bucket开启元数据管理功能。 GetMetaQueryStatus 获取指定Bucket的元数据索引库信息。 DoMetaQuery 查询满足指定条件的Object，并按照指定字段和排序方式列出Object信息。 CloseMetaQuery 关闭Bucket的元数据管理功能。

关于Object的操作

分类APi描述 PutObject 上传Object。 GetObject 获取Object。 CopyObject 拷贝Object。 AppendObject 以追加写的方式上传Object。 DeleteObject 删除单个Object。 DeleteMultipleObjects 删除多个Object。 HeadObject 只返回某个Object的meta信息，不返回文件内容。 GetObjectMeta 返回Object的基本meta信息，包括该Object的ETag、Size（文件大小）以及LastModified等，不返回文件内容。 PostObject 通过HTML表单上传的方式上传Object。 Callback 您只需在发送给OSS的请求中携带相应的Callback参数即能实现回调。 RestoreObject 解冻归档类型（Archive）或冷归档（Cold Archive）的文件（Object）。 SelectObject 对目标文件执行SQL语句，返回执行结果。分片上传（MultipartUpload） InitiateMultipartUpload 初始化一个Multipart Upload事件。 UploadPart 根据指定的Object名和uploadId来分块（Part）上传数据。 UploadPartCopy 通过在UploadPart请求的基础上增加一个请求头x-oss-copy-source来调用UploadPartCopy接口，实现从一个已存在的Object中拷贝数据来上传一个Part。 CompleteMultipartUpload 在将所有数据Part都上传完成后，您必须调用CompleteMultipartUpload接口来完成整个文件的分片上传。 AbortMultipartUpload 取消Multipart Upload事件并删除对应的Part数据。 ListMultipartUploads 列举所有执行中的Multipart Upload事件，即已经初始化但还未完成（Complete）或者还未中止（Abort）的Multipart Upload事件。 ListParts 列举指定uploadId所属的所有已经上传成功Part。权限控制（ACL) PutObjectACL 修改Object的访问权限。 GetObjectACL 查看Object的访问权限。软链接（Symlink） PutSymlink 创建软链接。 GetSymlink 获取软链接。标签（Tagging） PutObjectTagging 设置或更新对象标签。 GetObjectTagging 获取对象标签信息。 DeleteObjectTagging 删除指定的对象标签。

关于Live Channel的操作

API描述 PutLiveChannelStatus 切换LiveChannel的状态。 PutLiveChannel 创建LiveChannel。 GetVodPlaylist 获取播放列表。 PostVodPlaylist 生成播放列表。 GetLiveChannelStat 获取LiveChannel的推流状态信息。 GetLiveChannelInfo 获取LiveChannel的配置信息。 GetLiveChannelHistory 获取LiveChannel的推流记录。 ListLiveChannel 列举LiveChannel。 DeleteLiveChannel 删除LiveChannel。

OSS Bucket之间的数据迁移包含以下场景：

同账号下的OSS数据迁移，即同一个阿里云账号下相同或者不同地域Bucket之间的数据迁移。具体步骤，请参见使用数据复制功能迁移同账号下的OSS数据。

跨账号下的OSS数据迁移，即不同阿里云账号下相同或不同地域Bucket之间的数据迁移。具体操作，请参见使用在线迁移服务跨账号迁移OSS数据。

数据迁移任务会在跨区域复制或者同区域复制规则配置完成的3~5分钟后启动。

由于Bucket间的数据复制采用异步（近实时）复制，数据迁移到目标Bucket需要的时间取决于数据的大小，通常几分钟到几小时不等。

迁移历史数据时，从源Bucket复制的Object可能会覆盖目标Bucket中同名的Object。为避免同名文件被覆写，建议您对源Bucket和目标Bucket开启版本控制。开启版本控制的具体步骤，请参见版本控制相关操作。

如果您希望在数据迁移进度达到100%时，不再继续迁移源Bucket中的增量数据，您可以选择关闭数据同步。此时，已迁移的数据将被保留在目标Bucket中，源Bucket中的增量数据将不再迁移到目标Bucket。

已创建RAM用户。

为阿里云账号A创建RAM用户A，为阿里云账号B创建RAM用户B。具体步骤，请参见创建RAM用户。

已创建AccessKey。

分别为RAM用户A以及RAM用户B创建访问密钥AccessKey，并记录AccessKey信息。具体步骤，请参见为RAM用户创建访问密钥

已为RAM用户授权。

分别为RAM用户A以及RAM用户B授予 AliyunOSSFullAccess 以及 AliyunMGWFullAccess 的权限。具体步骤，请参见为RAM用户授权。

第三方数据源迁移到 OSS:

您可以使用阿里云在线迁移服务将第三方数据源，如亚马逊AWS、谷歌云等数据轻松迁移至阿里云对象存储OSS。

使用在线迁移服务，您只需在控制台填写源数据地址和目标OSS地址信息，并创建迁移任务即可。启动迁移后，您可以通过控制台管理迁移任务，查看迁移进度、流量等信息；也可以生成迁移报告，查看迁移文件列表、错误文件列表。具体各个数据源的迁移操作

从AWS S3上的应用无缝切换至OSS

由于OSS兼容S3协议，因此您可以通过S3 SDK进行创建Bucket、上传Object等相关操作。执行相关操作过程中其带宽、QPS等限制遵循OSS性能指标，详情请参见使用限制。

客户端配置

从AWS S3迁移到OSS后，您仍然可以使用S3 API访问OSS，仅需要对S3的客户端应用进行如下改动：

获取阿里云账号或RAM用户的AccessKey ID和AccessKey Secret，并在您使用的客户端和SDK中配置您申请的AccessKey ID与AccessKey Secret。

设置客户端连接的Endpoint为OSS Endpoint。OSS Endpoint列表请参见访问域名和数据中心。

使用ossimport迁移数据:

ossimport支持将任意地域的本地存储数据、第三方存储数据、对象存储OSS数据迁移至任意地域的OSS中。本文介绍如何使用ossimport将数据从第三方存储迁移到OSS。

某用户的数据存储于腾讯云COS广州（华南）区域，数据大小约500TB。现希望将这些数据，通过ossimport工具，于一周内迁移至OSS华东1（杭州）区域。在迁移的同时，需保证自身业务的正常进行。

ossimport有单机模式和分布式模式两种部署方式：

对于小于30TB的小规模数据迁移，单机模式即可完成。

对于大规模的数据迁移，请使用分布式模式。

此需求需要使用ossimport分布式配置进行数据迁移。

说明您也可以使用在线迁移服务进行数据的迁移，迁移过程更加简单，详情请参见在线迁移服务。

开通OSS，并创建华东1（杭州）地域的存储空间（Bucket）

开通OSS步骤请参见开通OSS服务。

创建Bucket步骤请参见创建存储空间。

创建RAM用户，并授予访问OSS的权限

在RAM控制台创建RAM用户，并授权该RAM用户访问OSS的权限，然后保存AccessKey ID和AccessKey Secret。详情请参见创建RAM用户并授予相关权限。

（可选）购买ECS

购买与OSS相同地域的ECS实例。有关ECS实例规格的更多信息，请参见通用型。如果迁移后ECS实例需释放，建议按需购买ECS。

说明如果分布式部署所需的计算机数量较少时，您可以直接在本地部署；如果所需计算机数量较多时，建议在ECS实例上部署。本示例以ECS实例进行迁移任务。

ECS所需数量的计算公式为：X/Y/（Z/100）台。其中X为需要迁移的数据量、Y为要求迁移完成的时间（天）、Z为单台ECS迁移速度Z Mbps（每天迁移约Z/100 TB数据）。假设单台ECS迁移速度达到200Mbps（即每天约迁移2TB数据），则上述示例中需购买ECS 36台（即500/7/2）。

配置ossimport

结合本示例中的大规模迁移需求，您需要在ECS上搭建ossimport分布式模式。有关分布式部署的配置定义信息，如 conf/job.cfg 、 conf/sys.properties 、并发控制等配置，请参见说明及配置。有关分布式部署的相关操作，如ossimport下载、配置过程的常见错误及排除等，请参见分布式部署。

使用分布式模式将第三方存储迁移至OSS的过程如下：

说明在ECS上搭建ossimport分布式环境后，ossimport从腾讯云COS广州（华南）区域下载数据到ECS华东1（杭州），建议使用外网。使用ossimport从ECS华东1（杭州）将数据上传到OSS华东1（杭州），建议使用内网。

迁移过程涉及到的成本包含：源和目的存储空间访问费用、源存储空间的流出流量费用、ECS实例费用、数据存储费用、时间成本。如果数据超过TB级别，存储成本和迁移时间成正比。相对流量、存储费用，ECS费用较小，增加ECS数量，会减少迁移时间。

全量迁移第三方存储T1前的历史数据。

详细步骤请参考分布式部署的运行。

注意 T1为Unix时间戳，即自1970年01月01日UTC零点以来的秒数，通过命令 date +%s获取。

配置镜像回源。

数据迁移过程中，源站还在不断产生新的数据。为了不中断业务，做到业务无缝切换，还需要配置镜像回源功能。当用户请求的文件在 OSS 中没有找到时，OSS会自动到源站抓取对应文件保存到 OSS，并将内容直接返回给用户。配置步骤请参见 OSS镜像回源。

将业务系统读写切换至OSS，此时业务系统记录的时间为T2。

修改配置文件 job.cfg的配置项 importSince=T1，重新发起迁移任务，进行T1~T2的增量数据迁移。

步骤4完成后，您业务系统的所有的读写都在OSS上。第三方存储只是一份历史数据，您可以根据需要决定保留或删除。

ossimport只负责数据的迁移和校验，不会删除任何数据。

在传统大数据领域，HDFS经常作为大规模数据的底层存储。在进行数据迁移、数据拷贝的场景中，最常用的是Hadoop自带的DistCp工具。但是该工具不能很好利用对象存储OSS的特性，导致效率低下并且不能保证数据一致性。此外，该工具提供的功能选项较单一，无法很好地满足用户的需求。

阿里云Jindo DistCp（分布式文件拷贝工具）用于大规模集群内部或集群之间拷贝文件。Jindo DistCp使用MapReduce实现文件分发，错误处理和恢复，把文件和目录的列表作为MapReduce任务的输入，每个任务会完成源列表中部分文件的拷贝。全量支持HDFS之间、HDFS与OSS之间、以及OSS之间的数据拷贝场景，提供多种个性化拷贝参数和多种拷贝策略。

相对于Hadoop DistCp，使用阿里云Jindo DistCp从HDFS迁移数据到OSS具有以下优势：

效率高，在测试场景中最高可达到1.59倍的加速。

基本功能丰富，提供多种拷贝方式和场景优化策略。

深度结合OSS，对文件提供归档、压缩等操作。

实现No-Rename拷贝，保证数据一致性。

场景全面，可完全替代Hadoop DistCp，目前支持Hadoop2.7+和Hadoop3.x。

如果您使用的是自建ECS集群，需要具备Hadoop2.7+或Hadoop3.x环境以及进行MapReduce作业的能力。

如果您使用的是阿里云E-MapReduce：

对于EMR3.28.0/bigboot2.7.0及以上的版本，可以通过Shell命令的方式使用Jindo DistCp。更多信息，请参见 Jindo DistCp使用说明。

对于EMR3.28.0/bigboot2.7.0以下的版本，可能会存在一定的兼容性问题，您可以通过提交工单申请处理。

步骤一：下载JAR包

Hadoop 2.7+的JAR包

Hadoop 3.x的JAR包

步骤二：配置OSS的AccessKey

您可以通过以下任意方式配置AccessKey：

在示例命令中配置AccessKey

例如，在将HDFS中的目录拷贝到OSS指定路径的示例命令中结合 --ossKey、 --ossSecret、 --ossEndPoint选项配置AccessKey。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming/examplefile --dest oss://examplebucket/example_file --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com

通过配置文件预先配置AccessKey

将OSS的 --ossKey、 --ossSecret、 --ossEndPoint预先配置在Hadoop的 core-site.xml文件里。示例命令如下：

<configuration>
    <property>
        <name>fs.oss.accessKeyId</name>
        <value>xxx</value>
    </property>
    <property>
        <name>fs.oss.accessKeySecret</name>
        <value>xxx</value>
    </property>
    <property>
        <name>fs.oss.endpoint</name>
        <!-- 阿里云ECS环境下推荐使用内网OSS Endpoint，即oss-cn-xxx-internal.aliyuncs.com -->
        <value>oss-cn-xxx.aliyuncs.com</value>
    </property>
</configuration>

配置免密功能

配置免密功能，避免明文保存AccessKey，提高安全性。具体操作，请参见使用JindoFS SDK免密功能。

步骤三：迁移或拷贝数据

以下以Jindo DistCp 3.7.3版本为例，您可以根据实际环境替换对应的版本号。

全量迁移或拷贝数据

将HDFS指定目录 /data/incoming下的数据全量迁移或拷贝到OSS目标路径 oss://examplebucket/incoming/，示例命令如下：

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --parallelism 10

示例中涉及的各参数或选项说明如下：

参数及选项说明示例 --src 待迁移或拷贝的HDFS数据所在的路径。 /data/incoming --dest OSS中存放迁移或拷贝数据的目标路径。 oss://examplebucket/incoming --ossKey 访问OSS的AccessKey ID。关于获取AccessKey ID的具体操作，请参见获取AccessKey 。 LTAI5t7h6SgiLSganP2m**** --ossSecret 访问OSS的AccessKey Secret。关于获取AccessKey Secret的具体操作，请参见获取AccessKey 。 KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint Bucket所在地域（Region）对应的访问域名（Endpoint）。关于OSS支持的地域和对应的访问域名列表信息，请参见访问域名和数据中心。

注意 ECS环境下推荐使用内网 ossEndPoint，即 oss-cn-xxx-internal.aliyuncs.com。

oss-cn-hangzhou.aliyuncs.com --parallelism 根据集群资源调整任务并发数。

增量迁移或拷贝数据

如果您仅希望拷贝在上一次全量迁移或拷贝后源路径下新增的数据，此时您可以结合 --update选项完成数据的增量迁移或拷贝。

将HDFS指定目录 /data/incoming下的数据增量迁移或拷贝到OSS目标路径 oss://examplebucket/incoming，示例命令如下：

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --update --parallelism 10

使用 --update选项时，默认开启校验和Checksum。开启后，DistCp将对源路径和目标路径的文件名称、文件大小以及文件的Checksum进行比较。如果源路径或目标路径下的文件名称、文件大小或者文件的Checksum不一致时，将自动触发增量迁移或拷贝任务。

如果您不需要对源路径和目标路径的文件的Checksum进行比较，请增加 --disableChecksum选项关闭Checksum校验，示例命令如下：

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --update --disableChecksum --parallelism 10

附录一：Jindo DistCp支持的参数及选项

Jindo DistCp提供一系列的参数及选项。您可以通过以下命令获取各参数及选项的具体用法。

hadoop jar jindo-distcp-3.7.3.jar --help

各参数及选项的含义及其示例如下表所示。

参数及选项说明示例 --src 指定拷贝的源路径。 --src oss://exampleBucket/sourceDir --dest 指定拷贝的目标路径。 --dest oss://exampleBucket/destDir --parallelism 指定拷贝的任务并发数，可根据集群资源调节。 --parallelism 10 --policy 指定拷贝到OSS后的文件类型。取值：

ia：低频访问

archive：归档存储

coldArchive：冷归档存储

--policy archive --srcPattern 指定通过正则表达式来选择或者过滤需要拷贝的文件，正则表达式必须为全路径正则匹配。 --srcPattern .*\.log --deleteOnSuccess 指定在拷贝任务完成后删除源路径下的文件。 --deleteOnSuccess --outputCodec 指定文件的压缩方式。当前版本支持编解码器gzip、gz、lzo、lzop和snappy，以及关键字none和keep。关键字含义如下：

none：保存为未压缩的文件。如果文件已压缩，则Jindo DistCp会将其解压缩。

keep（默认值）：不更改文件压缩形态。

说明如果您需要在开源Hadoop集群环境中使用lzo的压缩方式，请确保已安装gplcompression的native库和hadoop-lzo包。如果缺少相关环境，建议使用其他压缩方式进行压缩。

--outputCodec gzip --srcPrefixesFile 指定需要拷贝的文件列表，列表里文件以src路径作为前缀。 --srcPrefixesFile file:///opt/folders.txt --outputManifest 指定在dest目录下生成一个gzip压缩的文件，记录已完成拷贝的文件信息。 --outputManifest=manifest-2020-04-17.gz --requirePreviousManifest 指定本次拷贝操作是否需要读取之前已拷贝的文件信息。取值如下：

false：不读取已拷贝的文件信息，直接拷贝全量数据。

true：读取已拷贝的文件信息，仅拷贝增量数据。

--requirePreviousManifest=false --previousManifest 指定本次拷贝需要读取已拷贝文件信息所在的路径，完成增量更新。 --previousManifest=oss://exampleBucket/manifest-2020-04-16.gz --copyFromManifest 从已完成的Manifest文件中进行拷贝，通常与 --previousManifest选项配合使用。 --previousManifest oss://exampleBucket/manifest-2020-04-16.gz --copyFromManifest --groupBy 通过正则表达式将符合规则的文件进行聚合。 --groupBy='.*/([a-z]+).*.txt' --targetSize 指定聚合后的文件大小阈值，单位为MB。 --targetSize=10 --enableBalancePlan 适用于拷贝任务中数据量差异不大的场景，例如均为大于10 GB或者均为小于10 KB的文件。 --enableBalancePlan --enableDynamicPlan 适用于拷贝任务中数据量差异较大的场景，例如10 GB大文件和10 KB小文件混合的场景。 --enableDynamicPlan --enableTransaction 保证Job级别的一致性，默认是Task级别。 --enableTransaction --diff 查看本次拷贝是否完成全部文件拷贝，并对未完成拷贝的文件生成文件列表。 --diff --ossKey 访问OSS的AccessKey ID。 --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret 访问OSS的AccessKey Secret。 --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint Bucket所在地域对应的Endpoint。 --ossEndPoint oss-cn-hangzhou.aliyuncs.com --cleanUpPending 清理OSS残留文件，清理过程需要消耗一定的时间。 --cleanUpPending --queue Yarn队列名称。 --queue examplequeue1 --bandwidth 指定本次DistCp任务所用的单机带宽，单位为 MB。 --bandwidth 6 --disableChecksum 关闭Checksum校验。 --disableChecksum --enableCMS 开启云监控告警功能。 --enableCMS --update 使用增量同步功能，即仅同步上一次全量迁移或拷贝后源路径下新增的数据到目标路径。 --update --filters 通过filters参数指定一个文件路径。在这个文件中，每一行配置一个正则表达式，对应DistCp任务中不需要拷贝或比对的文件。 --filters /path/to/filterfile.txt --tmp 指定在使用DistCp工具的过程中，用于存放临时文件的目录。 --tmp /data --overwrite 使用覆盖同步功能，即使用源路径完全覆盖目标路径。 --overwrite --ignore 忽略数据迁移期间发生的异常，相关报错不会中断任务，并最终以DistCp Counter的形式透出。如果使用了--enableCMS，也会通过指定方式进行通知。 --ignore

附录二：场景示例

场景一：使用JindoDistCp成功传输数据后，如何验证数据完整性？

JindoDistCp提供了以下两种方式用于验证数据的完整性。

方式一：DistCp Counters

通过Distcp Counters信息中包含的BYTES_EXPECTED、FILES_EXPECTED等参数验证数据完整性。

JindoDistcpCounter BYTES_COPIED=10000 BYTES_EXPECTED=10000 FILES_COPIED=11 FILES_EXPECTED=11 Shuffle Errors BAD_ID=0 CONNECTION=0 IO_ERROR=0 WRONG_LENGTH=0 WRONG_MAP=0 WRONG_REDUCE=0

示例中可能包含的Counter参数如下：

参数说明 BYTES_COPIED 拷贝成功的字节数。 BYTES_EXPECTED 预期拷贝的字节数。 FILES_COPIED 拷贝成功的文件数。 FILES_EXPECTED 预期拷贝的文件数。 FILES_SKIPPED 增量拷贝时跳过的文件数。 BYTES_SKIPPED 增量拷贝时跳过的字节数。 COPY_FAILED 拷贝失败的文件数，不为0时触发告警。 BYTES_FAILED 拷贝失败的字节数。 DIFF_FILES 源路径与目标路径下不相同的文件数，不为0时触发告警。 DIFF_FAILED 文件比较操作异常的文件数，并计入DIFF_FILE。 SRC_MISS 源路径下不存在的文件数，并计入DIFF_FILES。 DST_MISS 目标路径下不存在的文件数，并计入DIFF_FILES。 LENGTH_DIFF 源文件和目标文件大小不一致的数量，并计入DIFF_FILES。 CHECKSUM_DIFF Checksum校验失败的文件数，并计入COPY_FAILED。 SAME_FILES 源路径与目标路径下完全相同的文件数。

场景二：从HDFS迁移数据到OSS过程中，迁移任务可能随时失败，要想支持断点续传，该使用哪些参数？

您可以在示例中结合 --diff选项查看HDFS指定路径下的文件是否都已迁移至OSS。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --diff

如果所有文件都已迁移完成，则提示如下信息，否则在执行目录下会生成一个manifest文件。

INFO distcp.JindoDistCp: Jindo DistCp job exit with 0

对于生成的manifest文件，您可以使用 --copyFromManifest和 --previousManifest选项迁移剩余文件。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --previousManifest=file:///opt/manifest-2020-04-17.gz --copyFromManifest --parallelism 20

其中， --previousManifest选项后指定的 file:///opt/manifest-2020-04-17.gz为当前执行命令的本地路径。

场景三：如果要以低频访问、归档或者冷归档的方式存储写入OSS的文件，该使用哪些参数？

您可以在示例中添加 --policy选项来指定写入OSS文件的存储类型。以下以指定为低频访问类型为例：

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --policy ia --parallelism 10

如果需要指定为归档存储类型，请将 --policy ia替换为 --policy archive。如需指定为冷归档存储类型，请将 --policy ia替换为 --policy coldArchive。此外，目前冷归档存储仅支持部分地域，更多信息，请参见冷归档存储（Cold Archive）。

场景四：了解待迁移或拷贝的源路径下数据的分布情况后，例如大文件和小文件的占比，该使用哪些参数来优化数据传输速度？

小文件较多，大文件较大

例如HDFS源路径下包含50万个大小为100 KB左右的文件，10个5 TB大小的文件，此时您可以结合 --enableDynamicPlan选项优化数据传输速度。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --enableDynamicPlan --parallelism 10

文件大小无明显差异

例如HDFS源路径下包含100个大小为200 KB的文件，此时您可以结合 --enableBalancePlan选项优化数据传输速度。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --enableBalancePlan --parallelism 10

说明不支持在同一个示例中同时使用 --enableDynamicPlan以及 --enableBalancePlan选项。

场景五：迁移或者拷贝任务完成后，希望仅保留目标路径下的数据，且删除源路径下的指定数据，该使用哪些参数？

您可以结合 --deleteOnSuccess选项，在迁移或者拷贝任务完成后，仅保留OSS目标路径下的数据，并删除HDFS源路径下的指定数据。

hadoop jar jindo-distcp-3.7.3.jar --src /data/incoming --dest oss://examplebucket/incoming --ossKey LTAI5t7h6SgiLSganP2m**** --ossSecret KZo149BD9GLPNiDIEmdQ7dyNKG**** --ossEndPoint oss-cn-hangzhou.aliyuncs.com --deleteOnSuccess --parallelism 10