Conectar-se ao Cloud Storage usando o gRPC

O gRPC é um framework de RPC universal de alto desempenho e código aberto desenvolvido pelo Google que pode ser usado para definir seus serviços usando buffers de protocolo. É possível usar o gRPC para interagir com o Cloud Storage. O gRPC utiliza conexão direta entre a instância do Compute Engine e os buckets do Cloud Storage, ignorando os front-ends do Google (GFE).

Observação: para ter o melhor desempenho com o gRPC ao se conectar ao Cloud Storage, verifique se a instância do Compute Engine e os buckets regionais estão na mesma região.

É possível se conectar ao Cloud Storage usando o gRPC pelos seguintes clientes compatíveis:

• Conector do Cloud Storage no Dataproc.

• Conector de E/S do Apache Beam no Dataflow para pedidos de leitura e gravação.

• Bibliotecas de cliente do Cloud Storage para C++, Go e Java. Para instruções sobre como ativar o gRPC para essas bibliotecas de cliente, consulte Ativar o gRPC na biblioteca de cliente.

• Cloud Storage FUSE. Para usar o Cloud Storage FUSE como cliente, especifique grpc no campo client-protocol usando um arquivo de configuração do Cloud Storage FUSE ou a flag --client-protocol usando a CLI do gcsfuse.

O uso do gRPC para se conectar ao Cloud Storage deve melhorar a performance de leitura das cargas de trabalho de análise executadas em Google Cloud somente quando a instância do Compute Engine e os buckets do Cloud Storage estiverem localizados na mesma região. Não recomendamos o uso do gRPC para buckets em multirregiões e bi-regiões.

Ativar o gRPC em uma biblioteca de cliente

C++

Antes de começar

1. Verifique se você tem as versões a seguir instaladas:

   • gRPC versão 1.65.1 ou mais recente

   • Biblioteca de cliente C++ versão v2.30.0 ou mais recente

   • C++ versão 14 ou mais recente

   Para instruções de instalação, consulte Como configurar um ambiente de desenvolvimento em C++.

2. Configure a autenticação.

Configurar a biblioteca de cliente C++

1. Crie um cliente gRPC usando gcs::MakeGrpcClient():

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

   A biblioteca de cliente C++ usa automaticamente a conexão direta quando detecta que o aplicativo está sendo executado em Google Cloud.

2. Para configurar a biblioteca de cliente C++ para usar o gRPC, ative o cliente gRPC do Cloud Storage para atualizar a configuração do sistema de build para CMake ou Bazel.

   CMake

   1. Ative o plug-in de cliente gRPC do Cloud Storage no tempo de compilação.

      cmake -DGOOGLE_CLOUD_CPP_ENABLE=storage_grpc [other options here]
      

   2. Na base de código, substitua google-cloud-cpp::storage por google-cloud-cpp::storage_grpc no comando target_link_libraries().

      Por exemplo, o programa de início rápido para gRPC usa o seguinte código:

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

   Bazel

   Substitua as dependências de @google_cloud_cpp//:storage para @google_cloud_cpp//:storage_grpc.

   Por exemplo, o programa de início rápido para gRPC usa o seguinte código:

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

Java

Antes de começar

1. Verifique se você tem as versões a seguir instaladas:

   • Bibliotecas de cliente Java:

     • com.google.cloud:google-cloud-storage:2.43.1 ou mais recente.
     • com.google.cloud:libraries-bom:26.48 ou mais recente.

   • Java 8 ou mais recente

   Para instruções de instalação, consulte Como configurar um ambiente de desenvolvimento em Java.

2. Configure a autenticação.

Atualizar seu projeto para usar a BOM

Para garantir que seus projetos tenham versões compatíveis das bibliotecas de cliente Google Cloud , use as versões especificadas na lista de materiais (BOM) das bibliotecasGoogle Cloud . Para atualizar seu projeto para usar a BOM, use um dos seguintes métodos:

• Cloud Storage independente
• Cloud Storage com outras Google Cloud bibliotecas

Cloud Storage independente

Se você estiver usando a biblioteca de cliente do Cloud Storage de forma independente (sem outras bibliotecasGoogle Cloud ), use o BOM específico da biblioteca de cliente do Cloud Storage.

Maven

Importe a BOM na seção dependencyManagement do seu arquivo pom.xml.

O exemplo a seguir mostra como importar a BOM e incluir o artefato 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

Adicione uma dependência de plataforma a 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 com outras Google Cloud bibliotecas

Se você estiver usando a biblioteca de cliente do Cloud Storage com outras Google Cloud bibliotecas, use a BOM das bibliotecas de cliente Google Cloud .

Maven

Importe a BOM na seção dependencyManagement do seu arquivo pom.xml.

O exemplo a seguir mostra como importar a BOM e incluir o artefato 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

Adicione uma dependência de plataforma a com.google.cloud:libraries-bom:

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

Criar um cliente gRPC

O exemplo a seguir usa um builder centralizado em gRPC. O cliente Java do gRPC usa automaticamente a conectividade direta quando detecta que o aplicativo está sendo executado em 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

Antes de começar

1. Configure seu ambiente de desenvolvimento.

2. Use a versão 1.46.0 ou mais recente da biblioteca de cliente Go do Cloud Storage.

3. Configure a autenticação.

Criar um cliente gRPC

Para usar o cliente, é necessário chamar o construtor NewGRPCClient no aplicativo em vez de 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)
}

A biblioteca de cliente Go usa automaticamente a conectividade direta quando detecta que o aplicativo está sendo executado em Google Cloud.

Para saber como usar um cliente gRPC, consulte API gRPC.

Configurar o VPC Service Controls

Se você estiver usando a nuvem privada virtual com endereços IP virtuais restritos (VPC Service Controls) para melhorar a segurança da sua rede, será necessário atualizar as regras do firewall para ativar a conexão direta e ter o melhor desempenho entre a instância do Compute Engine e o Cloud Storage.

Para fazer isso, adicione regras de firewall de lista de permissões para permitir o tráfego em todas as portas dos seguintes blocos de CIDR:

• Para tráfego IPv4: 34.126.0.0/18
• Para tráfego IPv6: 2001:4860:8040::/42

Além das regras anteriores, mantenha a regra de lista de permissões atual para 199.36.153.4/30.

Se você tiver restrições nas modificações de regras de firewall e não puder atualizá-las, poderá forçar o tráfego a evitar a conectividade direta usando storage.googleapis.com como o endpoint do Cloud Storage em vez de google-c2p://storage.googleapis.com.

Por exemplo, para C++, use .set<google::cloud::EndpointOption>(storage.googleapis.com) em vez de google-c2p:///storage.googleapis.com.

Ativar a observabilidade para solicitações relacionadas ao gRPC

É possível configurar bibliotecas de cliente do Cloud Storage para gerar métricas relacionadas ao gRPC no Cloud Monitoring. As métricas relacionadas ao gRPC podem ajudar você a fazer o seguinte:

• Monitore e otimize a performance das solicitações gRPC para o Cloud Storage.

• Resolver problemas e depurar.

• Receba insights sobre o uso e o comportamento do seu aplicativo.

Para saber como gerar métricas relacionadas ao gRPC, consulte Usar métricas do lado do cliente.

Se a coleta de métricas não for necessária para seu caso de uso, você poderá desativar a coleta de métricas. Para instruções, consulte Desativar as métricas do lado do cliente.

Limitações

• As solicitações IPv6 não podem ser enviadas por redes legadas.

• A conectividade direta não é compatível com as seguintes versões do GKE em clusters somente IPv4:

  • 1.28, 1.28.0-gke.100 ou mais recente até 1.28.5-gke.1199000
  • 1.27, 1.27.4-gke.1900 ou mais recente
  • 1.26, 1.26.10-gke.1238000 ou mais recente
  • 1.25, 1.25.15-gke.1045000 ou mais recente

• O gRPC não oferece suporte a notificações, hmacKeys e métodos serviceAccount.

• As opções do construtor de cliente específicas do HTTP, como WithHTTPClient, não são compatíveis com a biblioteca de cliente Go.

A seguir

• Conectar ao conector do Cloud Storage no Dataproc usando o gRPC.
• Ative o gRPC no conector de E/S do Apache Beam no Dataflow.