Getting Started（Google Cloud Storage Client Library）

標籤：

在運行下面的步驟之前，請確保：

1.你的項目已經啟用了Google Cloud Storage和App Engine，包括已經建立了至少一個Cloud Storage bucket。

2.你已經下載了client庫並解壓了。

3.你已經安裝並配置了最新的App Engine Java SDK。

運行LocalExample.java例子

LocalExample.java是一個非部署的例子，有助於快速測試和調查Cloud Storage的功能。除了Eclipse控制台輸出它沒有UI組件。（Cloud Storage client library deployable samples有UI也是可以擷取的）

在Eclipse中運行LocalExample.java

1.開始Eclipse

2.在Eclipse中，單擊Windows->Preferneces->Google->App Engine然後單擊Add。

3.跟隨提示，提供App Engine SDK的安裝路徑，然後單擊OK。

4.在Files菜單中，單擊Files->New->Java Project，建立一個名稱為LocalExample的項目，並使用包名稱com.google.appengine.demos。

5.在Package Explorer中選擇這個項目，單擊Files->New->Class並給這個類命名LocalExample，並使用包名稱com.google.appengine.demos。

6.拷貝 LocalExampleJava source 的內容到這個類檔案中。

7.在Package Explorer中再次選擇這個項目，並右擊，單擊Properties->Java Build Path.

8.在Libraries tab，單擊Add External Jars。必須追加下面的JARs:

● appengine-gcs-client.jar 來自你安裝的Cloud Storage client庫

● guava-15.0.jar 來自你安裝的Cloud Storage client庫

● joda-time-2.3.jar來自你安裝的Cloud Storage client庫

● appengine-testing.jar 來自App Engine 安裝的子目錄 /lib/testing

● appengine-api.jar 來自App Engine 安裝的子目錄 /lib/impl

● appengine-api-stubs.jar 來自App Engine 安裝的子目錄 /lib/impl

9.編譯，運行Run as-> Java Application

10.在Eclipse Console中看到如下輸出：

調查LocalExample.java例子

LocalExample.java在下面做了詳細描述，說明了Cloud Storage client庫的使用。

Imports

有一些使用的imports你可能不需要，或者本地測試會用到。下面列出了例子的imports。

import com.google.appengine.tools.cloudstorage.GcsFileOptions;import com.google.appengine.tools.cloudstorage.GcsFilename;import com.google.appengine.tools.cloudstorage.GcsInputChannel;import com.google.appengine.tools.cloudstorage.GcsOutputChannel;import com.google.appengine.tools.cloudstorage.GcsService;import com.google.appengine.tools.cloudstorage.GcsServiceFactory;import com.google.appengine.tools.cloudstorage.RetryParams;import com.google.appengine.tools.development.testing.LocalBlobstoreServiceTestConfig;import com.google.appengine.tools.development.testing.LocalDatastoreServiceTestConfig;import com.google.appengine.tools.development.testing.LocalServiceTestHelper;import java.io.IOException;import java.io.ObjectInputStream;import java.io.ObjectOutputStream;import java.nio.ByteBuffer;import java.nio.channels.Channels;import java.util.Arrays;import java.util.HashMap;import java.util.Map;

下面簡要介紹了這些imports：

com.google.appengine.tools.cloudstorage.*使我們可以使用Cloud Storage client庫。

com.google.appengine.tools.development.testing.* 僅在做某些App Engine特性的本地單元測試時需要。

java.io.ObjectInputStream 和java.io.ObjectOutputStream 用來讀寫對象。

java.nio.ByteBuffer用於非緩衝的讀寫

java.io.IOException 錯誤處理時需要（儘管沒有列出）

java.nio.channels.Channels 用於將輸入輸出通道轉換為流

java.nio.channels.ReadableByteChannel 用於從Cloud Storage中讀取資料

建立一個GcsService來發送請求

通過庫發送和接受請求到Cloud Storage，你需要一個GcsService執行個體：

private final GcsService gcsService =    GcsServiceFactory.createGcsService(RetryParams.getDefaultInstance());

在這個片段中，注意在createGcsService中RetryParams的使用。如上所示，createGcsService(RetryParams.getDefaultInstance()),這設定了預設的重試配置，當訪問Cloud Storage時，發生逾時或者意想不到的錯誤時會進行重試。為了指定不同的值，比如重試的最大次數，你使用RetryParams.Builder 在一個新的 RetryParams對象中改變更配置置，並且在建立GcsService時提供它。注意一旦這個GcsService對象被建立了，它的重試參數不能被改變。

你可以建立任意多的GcsService執行個體。每一個執行個體是獨立的，不可變的（因此是安全執行緒的），可重複使用的。比如，一個可以使用某個參數設定來寫檔案，同時另一個可以使用不同的重試參數來讀不同的檔案。

一個推薦的實踐是在你的每個I/O類中使用獨立的執行個體。這將協助保持你的類的獨立，以及少的開銷。

向Cloud Storage寫資料

下面的例子展示了如何向Cloud Storage的檔案中寫資料。獨立的片段提供了寫可序列化對象資料和位元組數組。

Cloud Storage檔案不會完全建立好直到close被調用

在下面的片段中，在finally塊中沒有出現close，就像Java中經常做的。所以有異常時，任何被寫的部分都會自動地被清除。

向Cloud Storage寫對象

這兒是說明如何序列化對象到Cloud Storage 檔案。首先，擷取一個可寫的位元組通道：

GcsOutputChannel outputChannel =    gcsService.createOrReplace(fileName, GcsFileOptions.getDefaultInstance());

在這個片段中GcsService.createOrReplace 被調用了，GcsFilename 作為第一個參數。這個對象包含了要使用的bucket的名稱以及對象的名稱。如果在bucket已經有了一個同名的對象，並且你的應用有寫的許可權，這個調用會覆蓋存在的檔案（Cloud Storage不支援附加）。如果沒有那個名字的檔案，這個調用的結果就是建立了一個新檔案。

第二個參數是GcsFileOptions。要使用預設的選項，使用GcsFileOptions.getDefaultInstance。要使用自己的設定，使用GcsFileOptions.Builder來設定選項並建立一個GcsFileOptions作為第二個參數。

這個檔案選項被傳遞給Cloud Storage告訴它檔案的文本類型，在頭部你想傳遞的使用者中繼資料，檔案訪問管理ACL等等。如果你不提供一個文本類型（mimeType）,這個檔案將會被Cloud Storage以預設的MIME類型提供（serve），目前使用的是binary/octet-stream。如果你不指定一個ACL，分配的對象存取權限是當前預設的對象ACL。

注意所有的檔案選項資訊都可以通過在一個Close之後，通過調用GcsService.getMetadata(fileName)從一個對象中擷取，而不需要它自己下載這個對象。

關於更多的配置資訊，瀏覽Cloud Storage文檔的ACLs和file options。

現在使用一個輸出資料流來寫資料

@SuppressWarnings("resource")ObjectOutputStream oout =    new ObjectOutputStream(Channels.newOutputStream(outputChannel));oout.writeObject(content);oout.close();

向Cloud Storage檔案中寫位元組數組

這兒說明如何向Cloud Storage檔案中寫位元組數組。

@SuppressWarnings("resource")GcsOutputChannel outputChannel =    gcsService.createOrReplace(fileName, GcsFileOptions.getDefaultInstance());outputChannel.write(ByteBuffer.wrap(content));outputChannel.close();

在createOrReplace調用中使用的參數的說明，參見Writing an Object to Cloud Storage下的說明。

從Cloud Storage中讀取資料

下面的例子說明如何從儲存在Cloud Storage中的檔案讀取資料。分開的片段提供了讀Cloud Storage檔案到對象（序列化）和位元組數組。

將Cloud Storage讀到一個對象

這個方法對於讀大檔案到一個緩衝中是有用的。

GcsInputChannel readChannel = gcsService.openPrefetchingReadChannel(fileName, 0, 1024 * 1024);

這個調用 GcsService.openPrefetchingReadChannel 有一個 GcsFilename，它包含了要讀取的bucket的名字和要被讀的對象。第二個參數是檔案開始讀的位元組，0表示從檔案的開頭開始讀。如果你提供了檔案中其他的開始位置，比如位元組300，這個讀操作從位元組300開始到檔案的末尾，或直到你停止讀。（預讀緩衝會先讀，它將包含超過你停止的位置的位元組）

預讀對大部分應用而言是一個主要的優勢，因為當更多的資料正在後台被下載的時候，允許並行地處理檔案的一部分。

第三個參數就是預讀的緩衝的尺寸，在這個例子中設定為1MB。

現在，從通道中讀檔案：

try (ObjectInputStream oin = new ObjectInputStream(Channels.newInputStream(readChannel))) {  return oin.readObject();}

讀資料到位元組數組

對於小檔案，你可以一次讀取所有的檔案到位元組數組中：

int fileSize = (int) gcsService.getMetadata(fileName).getLength();ByteBuffer result = ByteBuffer.allocate(fileSize);try (GcsInputChannel readChannel = gcsService.openReadChannel(fileName, 0)) {  readChannel.read(result);}

在上面的片段中，注意java.nio.ByteBuffer的使用，特別是緩衝的尺寸的設定等於要從通道中讀取的檔案的尺寸。

注意，對於大多數應用，更喜歡的方法是讀（stream）檔案(讀資料到對象中)，因為這不需要在記憶體中一次就儲存所有的資料。

有UI的可部署的Cloud Storage Client庫的例子

對於有UI的可部署例子，瀏覽代碼：

● GcsExampleServlet.java從Cloud Storage中上傳下載檔案

● PortOfFilesAPIGuestbookServlet.java是例子程式的連接埠（port），之前使用現已淘汰的Files API。更多關於遷移的資訊，參見Migrating from the Files API。

在development server上運行以及部署之前需喲啊編譯這個例子。

編譯這個例子：

1.從終端中Checkout代碼

svn checkout http://appengine-gcs-client.googlecode.com/svn/trunk/ appengine-gcs-client-read-only

2.改變目錄到ppengine-gcs-client-read-only/java

3.調用ant compile_example，這會用目錄中的build.xml來編譯例子。更多的關於使用Apache Ant的資訊，參見 Using Apache Ant.

4.調用下面命令，運行dev server：

/path/to/AppEngSDK/dev_appserver.sh  /path/to/example/war

5.在你的瀏覽其中瀏覽 localhost:8080。看到：

Getting Started（Google Cloud Storage Client Library）