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 os buckets do Compute Engine e do Cloud Storage, ignorando os Google Front Ends (GFEs).

Observação: para ter o desempenho ideal com o gRPC ao se conectar ao Cloud Storage, verifique se as VMs do Compute Engine e os buckets regionais estão localizados na mesma região.

Embora não seja possível usar o gRPC diretamente para se conectar ao Cloud Storage, é 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 solicitações 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.

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á em execução no 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 e Bazel.

   CMake

   1. Ativar o plug-in de cliente gRPC do Cloud Storage no momento da 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 por @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 do Google Cloud, use as versões especificadas na Lista de materiais (BOM) das bibliotecas do Google Cloud. Para atualizar seu projeto para usar a BOM, use um dos seguintes métodos:

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

Cloud Storage independente

Se você estiver usando a biblioteca de cliente do Cloud Storage de forma independente (sem outras bibliotecas do Google 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 bibliotecas do Google Cloud

Se você estiver usando a biblioteca de cliente do Cloud Storage com outras bibliotecas do Google Cloud, use a BOM das bibliotecas de cliente do 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 a conectividade direta automaticamente quando detecta que o aplicativo está em execução no 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.

import (
  "context"
  "fmt"
  "log"
  "time"
  "cloud.google.com/go/storage"
  )
  func main() {
      ctx := context.Background()
      // The project ID and bucket name
      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á em execução no 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, atualize as regras do firewall para ativar a conexão direta e ter o desempenho ideal entre as instâncias de máquina virtual 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 para os seguintes blocos 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.

• O uso do gRPC para se conectar ao Cloud Storage melhora a performance de leitura das cargas de trabalho de análise executadas no Google Cloud somente quando as VMs de computação e os buckets do Cloud Storage estão localizados na mesma região. Não recomendamos o uso do gRPC para buckets em multirregiões e bi-regiões.

• 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.