使用 gRPC 連線至 Cloud Storage

gRPC 是 Google 開發的高效能開放原始碼通用遠端程序呼叫 (RPC) 架構，可讓您使用通訊協定緩衝區定義服務。您可以使用 gRPC 與 Cloud Storage 互動。gRPC 會在 Compute Engine 執行個體和 Cloud Storage 值區之間使用直接連線，略過 Google Front Ends (GFE)。

注意： 針對 Google Cloud上的分析工作負載，只有在 Compute Engine 執行個體和 Cloud Storage bucket 位於相同區域時，gRPC 才能提升 Cloud Storage 的讀取效能。

您可以透過下列支援的用戶端，使用 gRPC 連線至 Cloud Storage：

• Managed Service for Apache Spark 的 Cloud Storage 連接器。

• Dataflow 上的 Apache Beam I/O 連接器，用於讀取和寫入要求。

• Cloud Storage C++、Go 和 Java 用戶端程式庫。如要瞭解如何為這些用戶端程式庫啟用 gRPC，請參閱「在用戶端程式庫啟用 gRPC」。

• Cloud Storage FUSE。您可以使用 Cloud Storage FUSE 設定檔，在 client-protocol 欄位中指定 grpc，或使用 Cloud Storage FUSE CLI 的 --client-protocol 選項，將 Cloud Storage FUSE 做為用戶端。如要搭配使用 gRPC 和 Cloud Storage FUSE，建議使用 Cloud Storage FUSE 2.10.0 以上版本。

在用戶端程式庫上啟用 gRPC

C++

事前準備

1. 請確認已安裝下列版本：

   • gRPC 1.65.1 以上版本

   • C++ 用戶端程式庫 v2.30.0 以上版本

   • C++ 14 以上版本

   如需安裝操作說明，請參閱「設定 C++ 開發環境」。

2. 設定驗證方法。

3. 確保每個 Compute Engine 執行個體都附加服務帳戶，即使服務帳戶沒有權限也一樣。這個服務帳戶用於代表應用程式層傳輸安全性 (ALTS) 交握程序中的 Compute Engine 執行個體，是直接連線的必要條件。

設定 C++ 用戶端程式庫

1. 使用 gcs::MakeGrpcClient() 建立 gRPC 用戶端：

     namespace gcs = google::cloud::storage;
     void App() {
      auto client = gcs::MakeGrpcClient();
   
     // application code
   
     }
   

   當 C++ 用戶端程式庫偵測到應用程式在 Google Cloud上執行時，會自動使用直接連線。

2. 如要設定 C++ 用戶端程式庫以使用 gRPC，請啟用 Cloud Storage gRPC 用戶端，更新 CMake 或 Bazel 的建構系統設定。

   CMake

   1. 在編譯期間啟用 Cloud Storage gRPC 用戶端外掛程式。

      cmake -DGOOGLE_CLOUD_CPP_ENABLE=storage_grpc [other options here]
      

   2. 在程式碼庫中，將 target_link_libraries() 指令的 google-cloud-cpp::storage 替換為 google-cloud-cpp::storage_grpc。

      舉例來說，gRPC 的快速入門程式會使用下列程式碼：

      add_executable(quickstart_grpc quickstart_grpc.cc)
      target_link_libraries(quickstart_grpc google-cloud-cpp::storage_grpc)
      

   Bazel

   將依附元件從 @google_cloud_cpp//:storage 替換為 @google_cloud_cpp//:storage_grpc。

   舉例來說，gRPC 的快速入門程式會使用下列程式碼：

     cc_binary(
         name = "quickstart",
         srcs = [
             "quickstart.cc",
         ],
         deps = [
             "@com_github_googleapis_google_cloud_cpp//:storage_grpc",
         ],
     )
   

Java

事前準備

1. 請確認已安裝下列版本：

   • Java 用戶端程式庫：

     • com.google.cloud:google-cloud-storage:2.43.1 以上版本。
     • com.google.cloud:libraries-bom:26.48 以上版本。

   • Java 8 以上版本

   如需安裝說明，請參閱「設定 Java 開發環境」。

2. 設定驗證方法。

3. 確保每個 Compute Engine 執行個體都附加服務帳戶，即使服務帳戶沒有權限也一樣。這個服務帳戶用於在應用程式層傳輸安全性 (ALTS) 握手程序中代表 Compute Engine 執行個體，且為直接連線的必要項目。

更新專案以使用 BOM

為確保專案具有相容版本的 Google Cloud 用戶端程式庫，請使用Google Cloud 程式庫物料清單 (BOM) 中指定的版本。如要更新專案以使用 BOM，請採用下列任一方法：

• 獨立 Cloud Storage
• Cloud Storage 與其他 Google Cloud 程式庫

獨立 Cloud Storage

如果您獨立使用 Cloud Storage 用戶端程式庫 (不含其他Google Cloud 程式庫)，請使用 Cloud Storage 用戶端程式庫專屬的 BOM。

Maven

在 pom.xml 檔案的 dependencyManagement 區段中匯入 BOM。

以下範例說明如何匯入 BOM 並納入 google-cloud-storage 構件。

<dependencyManagement>
  <dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage-bom</artifactId>
   <version>2.43.1</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage</artifactId>
  </dependency>
</dependencies>

Gradle

新增 com.google.cloud:google-cloud-storage-bom 的平台依附元件：

implementation platform('com.google.cloud:google-cloud-storage-bom:2.43.1')
implementation 'com.google.cloud:google-cloud-storage'

搭配其他程式庫使用 Cloud Storage Google Cloud

如果您使用 Cloud Storage 用戶端程式庫以及其他 Google Cloud 程式庫，請使用 Google Cloud 用戶端程式庫 BOM。

Maven

在 pom.xml 檔案的 dependencyManagement 區段中匯入 BOM。

以下範例說明如何匯入 BOM 並納入 libraries-bom 構件。

<dependencyManagement>
  <dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>libraries-bom</artifactId>
   <version>26.48.0</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage</artifactId>
  </dependency>
</dependencies>

Gradle

新增 com.google.cloud:libraries-bom 的平台依附元件：

implementation platform('com.google.cloud:libraries-bom:26.48.0')
implementation 'com.google.cloud:google-cloud-storage'

建立 gRPC 用戶端

下列範例使用以 gRPC 為主的建構工具。gRPC Java 用戶端偵測到應用程式在 Google Cloud上執行時，會自動使用直接連線。

// Imports the Google Cloud client library
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class QuickstartGrpcSample {
  public static void main(String... args) throws Exception {

    // Create an instance of options which will use the Google Cloud Storage gRPC API for all
    // operations
    StorageOptions options = StorageOptions.grpc().build();

    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (Storage storage = options.getService()) {
      // The name for the new bucket
      String bucketName = args[0]; // "my-new-bucket";

      // Creates the new bucket using a request to the gRPC API
      Bucket bucket = storage.create(BucketInfo.of(bucketName));

      System.out.printf("Bucket %s created.%n", bucket.getName());
    }
  }
}

Go

事前準備

1. 設定開發環境。

2. 請務必使用 Cloud Storage Go 用戶端程式庫 1.46.0 以上版本。

3. 設定驗證方法。

4. 請確保每個 Compute Engine 執行個體都附加服務帳戶，即使服務帳戶沒有任何權限也一樣。這個服務帳戶用於代表應用程式層傳輸安全性 (ALTS) 交握程序中的 Compute Engine 執行個體，是直接連線的必要條件。

建立 gRPC 用戶端

如要使用用戶端，您必須在應用程式中呼叫 NewGRPCClient 建構函式，而非 NewClient。

// Sample storage-quickstart creates a Google Cloud Storage bucket using
// gRPC API.
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/storage"
)

func main() {
	ctx := context.Background()

	// Use your Google Cloud Platform project ID and Cloud Storage bucket
	projectID := "project-id"
	bucketName := "bucket-name"

	// Creates a gRPC enabled client.
	client, err := storage.NewGRPCClient(ctx)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// Creates the new bucket.
	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	if err := client.Bucket(bucketName).Create(ctx, projectID, nil); err != nil {
		log.Fatalf("Failed to create bucket: %v", err)
	}

	fmt.Printf("Bucket %v created.\n", bucketName)
}

Go 用戶端程式庫偵測到應用程式在 Google Cloud上執行時，會自動使用直接連線。

如要瞭解如何使用 gRPC 用戶端，請參閱「gRPC API」。

設定 VPC Service Controls

如果您使用虛擬私有雲搭配受限虛擬 IP 位址 (VPC Service Controls) 來強化網路安全性，則必須更新防火牆規則，啟用直接連線，讓 Compute Engine 執行個體和 Cloud Storage bucket 之間的效能達到最佳。

如要這麼做，請新增許可清單防火牆規則，允許下列 CIDR 區塊的所有通訊埠流量：

• IPv4 流量：34.126.0.0/18
• IPv6 流量：2001:4860:8040::/42

除了上述規則外，請保留 199.36.153.4/30 的現有許可清單規則。

如果您對防火牆規則修改設有限制，且無法更新規則，則可使用 storage.googleapis.com 做為 Cloud Storage 端點，而非 google-c2p://storage.googleapis.com，強制流量避免直接連線。

例如，如果是 C++，請使用 .set<google::cloud::EndpointOption>(storage.googleapis.com)，而非 google-c2p:///storage.googleapis.com。

注意： 虛擬私有雲網路的預設最大傳輸單位 (MTU) 為 1460 個位元組。為提升輸送量，建議將預設 MTU 增加至至少 4096 位元組。如要進一步瞭解網路 MTU，請參閱最大傳輸單位總覽。

啟用 gRPC 相關要求的觀測能力

您可以設定 Cloud Storage 用戶端程式庫，在 Cloud Monitoring 中產生 gRPC 相關指標。gRPC 相關指標可提供以下助益：

• 監控並最佳化向 Cloud Storage 發送 gRPC 要求時的傳輸效能。

• 輔助疑難排解和偵錯，及時解決問題。

• 深入瞭解應用程式的使用情況和行為。

如要瞭解如何產生 gRPC 相關指標，請參閱「使用用戶端指標」。

如果您的用途不需要收集指標，可以選擇不採用指標收集功能。如需操作說明，請參閱「選擇不採用用戶端指標」。

限制

• IPv6 要求無法透過舊版網路傳送。

• 在僅限 IPv4 的叢集上使用下列 GKE 版本時，不支援直接連線：

  • 1.28、1.28.0-gke.100 以上版本，直到 1.28.5-gke.1199000
  • 1.27、1.27.4-gke.1900 以上版本
  • 1.26、1.26.10-gke.1238000 以上版本
  • 1.25、1.25.15-gke.1045000 以上版本

• gRPC 不支援 notifications、hmacKeys 和 serviceAccount 方法。

• Go 用戶端程式庫不支援 HTTP 專屬的用戶端建構函式選項，例如 WithHTTPClient。

• 區域性端點不支援 gRPC API。

排解直接連線問題

如要瞭解如何檢查直接連線能力，以及在無法使用時進行疑難排解，請參閱「直接連線」。

後續步驟

• 使用 gRPC 連線至 Managed Service for Apache Spark 上的 Cloud Storage 連接器。
• 在 Dataflow 的 Apache Beam I/O 連接器上啟用 gRPC。