Java Client for Google Cloud Storage

关于Google Cloud Storage

Google Cloud Storage有益于大文件的存储与服务（serve）。此外，Cloud Storage提供了对访问控制列表（ACLs）的使用，提供了对上传中断的恢复功能以及其他的特性。Google Cloud Storage client库对应用自动使用恢复功能，提供了一种健壮的导(stream)数据到Cloud Storage的方法。

关于client library

Google Cloud Storage client库使你的应用可以从Cloud Storage的buckets读文件或向其写文件。这个库支持对Cloud Storage的大量数据的读写处理，能够进行内部错误处理和重试，所以你不需要自己写代码来完成这种事情。而且，它使用预读取提供了读缓冲，所以你的应用可以变得更有效。当对Cloud Storage进行读写时，client库使用HTTPS，所以你的数据在传输过程中是加密的。

Google Cloud Storage client库包含以下的功能：

● 一个接口对象（GcsService）,支持以下的Cloud Storage访问：

1.将一列存在的Cloud Storage对象组成一个新对象（GcsService.compose）。

2.复制一个存在的Cloud Storage对象（GcsService.copy）

3.创建一个新的或复写一个几经存在的Cloud Storage对象（GcsService.createOrReplace）

4.删除一个Cloud Storage对象（GcsService.delete）

5.为Cloud Storage对象获取元数据（GcsService.getMetaData）

6.列出一个指定的bucket的内容（GcsService.list）

7.打开一个缓冲读取通道从一个大的Cloud Storage对象中读数据[streaming in data](GcsService.openPrefetchingReadChannel)

8.打开一个无缓冲读取通道从一个小的Cloud Storage对象中读数据[streaming in data](GcsService.openReadChannel)

● 一个可写字节通道（GcsOutputChannel），缓冲或无缓冲地写到Cloud Storage.

下载client库

对于下载说明和分发内容，参见 downloads页

使用client库

从下面的选项中选择一个：

● 使用默认的Cloud Storage bucket:一个有免费配额的已配置的bucket

● 如果你不想使用默认的bucket，你首先需要激活Cloud Storage。

可选的访问Cloud Storage的方法

Google Cloud Storage client库提供了一个与GAE紧密集成的读写Cloud Storage的方法。使得GAE应用能够在Cloud Storage中创建对象和提供服务。

除了使用Google Cloud Storage client库以外还有其他的方法可以从GAE访问Cloud Storage。你也可以使用下面方法中的任一个：

● Blobstore API

● Cloud Storage REST API

● Cloud Storage Browser

● gsutil Tool

Blobstore API

你可以使用Blobstore API来上传对象到Cloud Storage或从Cloud Storage提供对象[serve objects]。你需要使用BlobstoreService.createGsBlobKey()方法创建一个blob key代表Cloud Storage 对象。这个方法对于从网页上传文件是有用的。当Blobstore API和Images API一起使用时，你可以拥有很强大的方法来提供图像[serve images]，因为你可以直接从Cloud Storage中提供图像，绕开了App Engine应用，这可以节省费用[saves on instance hour costs]。

Cloud Storage REST API

你可以使用Cloud Storage REST API读写Cloud Storage。如果你要寻找client库没有提供的某个明确特性的话，REST API将是一个不错的选择。

然而，client库包含了App Engine优化，所以使用REST API可能需要额外的开发时间。注意：App Engine开发服务器支持Cloud Storage Client。它不支持REST API。

Cloud Storage Browser

如果你需要快速上传对象，你可以使用Cloud Storage Browser。

关键的Cloud Storage概念

参见 Cloud Storage documentation查阅完整的概念和技术列表。下面的部分总结了Google Cloud Storage client库的重要概念。

Buckets，objects，ACLs

一个bucket就是可以读写文件的一个存储位置。在使用Cloud Storage client库的时候，你必须总是指定一个bucket。你的项目可以访问多个buckets。client库不支持bucket的创建。你可以通过Cloud Storage browser或gsutil工具手动创建。

访问控制列表（ACLs）控制对buckets以及其中的对象的访问。你的项目和你的App Engine 应用被添加到了ACL，这个ACL允许在激活期间访问bucket。这个允许访问bucket的ACL和潜在的许多管理bucket中对象的ACLs是不同的。因此，你的应用对其激活的bucket拥有读写权限(your app has read and write privileges to the bucket(s) it is activated for)，但是它仅仅对在bucket中的由它创建的对象拥有完整的权限。对于其他的应用或个人创建的对象，你的访问权限仅限于对象创建者赋予的部分。

如果一个对象在一个没有显式定义ACL的bucket中被创建的话，它将会使用bucket拥有者分配给bucket的默认的对象ACL。如果bucket的拥有者没有指定默认的对象ACL，那么对象默认就是public-read，这意味着任何被允许访问bucket的人可以读取这个对象。

ACLs以及Google Cloud Storage client库

使用client库的应用不能改变bucket ACL，但是它可以指定一个控制由它创建的对象的ACL。这个可以获得的ACL配置在GcsService.FcsFileOptions object文档的下面做了说明。

修改Cloud Storage 对象

一旦你在bucket中创建了一个对象，它就不能被修改和附加。你必须使用一个包含了你想要变更的内容的同名的新对象来覆盖这个对象。

Cloud Storage和子目录

Cloud Storage client库在创建一个对象时，支持子目录分隔符。但是在Cloud Storage中并没有真正的子目录。一个子目录在Cloud Storage中就是对象文件名的一部分。

比如，你可能认为创建一个对象somewhere/over/the/rainbow.mp3会将文件rainbow.mp3保存在子目录somewhere/over/the/。实际上，对象的名字被设置为了somewhere/over/the/rainbow.mp3。

Retries and exponential backoff

在访问Cloud Storage的时候，万一发生了超时失败，Google Cloud Storage client库会提供一个可配置的机制来自动请求重试。这个机制也提供了exponential backoff来决定最佳处理速度。具体的关于exponential backoff的说明，参见backoff。

要改变retries和backoff的默认，请使用 RetryParams类。

在development app server上使用client库

从SDK的版本1.8.1开始，在development server上可以使用client库。它使用本地磁盘提供了Cloud Storage模拟。

价格，配额和限制

在使用Google Cloud Storage client库调用Cloud Storage方面没有宽带费用。然而却有操作和存储费用，以及针对URL fetch配额的调用次数，因为这个库使用URL Fetch服务和Cloud Storage交互。

如果你使用默认的Cloud Storage bucket，你有一个免费的配额。如果你需要更多的配额，你需要让你的应用开始计费，所以你需要为额外的配额付费。

如果你不想使用默认的bucket，你需要激活Cloud Storage（ activate Cloud Storage）。如果你选择这样做，那么将没有免费配额并且所有存储在Cloud Storage的数据都要按正常的Cloud Storage数据存储费用付费。Cloud Storage是一个付费使用的服务；你将会被要求按Cloud Storage的价格表付费。

接下来做什么

1.下载client库

2.创建一个App Engine项目并激活Cloud Storage。

3.可选地，如果你有一个使用旧的Cloud Storage API的已有应用，迁移你的应用。

4.查看这个简要的Getting Started指导快速判断对client库的使用。

5.上传和部署你的应用到生产App Engine上。

6.在Cloud Storage上测试应用预期的行为。