google cloud java
v1.48.0
Cliente idiomático Java para serviços do Google Cloud Platform.
As bibliotecas estão disponíveis no GitHub e no Maven Central para desenvolver aplicativos Java que interagem com serviços individuais do Google Cloud:
| Cliente | Nível de liberação | Versão |
|---|---|---|
| Cadernos da plataforma AI | ||
| Gateway de API | ||
| API de chaves de API | ||
| Aprovação de acesso | ||
| API de notificações consultivas | ||
| LigaDB | ||
| Conectores AlloyDB | ||
| API Hub do Analytics | ||
| Apigee Connect | ||
| API de administração do App Engine | ||
| Registro de artefato | ||
| Inventário de ativos | ||
| Cargas de trabalho garantidas para o governo | ||
| ML automático | ||
| API de serviço de backup e DR | ||
| BigQuery | ||
| Conexão do BigQuery | ||
| Serviço de transferência de dados do BigQuery | ||
| Reserva do BigQuery | ||
| Armazenamento do BigQuery | ||
| Mesa grande | ||
| Cliente Hbase do Bigtable | ||
| Cobrança | ||
| Orçamentos de cobrança | ||
| Autorização Binária | ||
| Construir | ||
| Informações do CCAI | ||
| Serviço de autoridade de certificação | ||
| Serviços de canal | ||
| Compositor | ||
| Mecanismo de computação | ||
| Conectar API do Gateway | ||
| Análise de contêiner | ||
| Controla a API do parceiro | ||
| DNS | ||
| Catálogo de Dados | ||
| Fusão de dados | ||
| Linhagem de dados | ||
| Prevenção contra perda de dados | ||
| Serviço de migração de banco de dados | ||
| Dataplex | ||
| Dataproc | ||
| Metastore do Dataproc | ||
| Armazenamento de dados | ||
| Fluxo de dados | ||
| Depurador | ||
| Implantar | ||
| API Dialogflow | ||
| API do mecanismo de descoberta | ||
| Borda Distribuída | ||
| API de rede de borda distribuída | ||
| Documento IA | ||
| Domínios | ||
| API de contatos essenciais | ||
| Eventarc | ||
| API de armazenamento de arquivos | ||
| Armazém de Fogo | ||
| Roteamento de Frota | ||
| Funções | ||
| API GKE Hub | ||
| EU SOU | ||
| API de administração IAM | ||
| API de solução de problemas de políticas do IAM | ||
| API de credenciais de conta de serviço IAM | ||
| Gerenciador de contexto de acesso de identidade | ||
| API de proxy com reconhecimento de identidade | ||
| API do Gerenciador de Infraestrutura | ||
| Núcleo da Internet das Coisas (IoT) | ||
| Sistema de detecção de intrusão | ||
| Serviço de gerenciamento de chaves | ||
| Motor Kubernetes | ||
| Registro | ||
| Serviço gerenciado para Microsoft Active Directory | ||
| Memcache | ||
| Painéis de monitoramento | ||
| Linguagem Natural | ||
| Centro de conectividade de rede | ||
| API de gerenciamento de rede | ||
| API de segurança de rede | ||
| API de configuração do sistema operacional | ||
| Login do sistema operacional | ||
| Política da Organização | ||
| Criador de perfil | ||
| Pub/Sub | ||
| Conector Kafka do grupo Pub/Sub | ||
| Pub/Sub Lite | ||
| Pub/Sub Lite Kafka Shim | ||
| Conector Spark do Pub/Sub Lite | ||
| API de autoridade de certificação pública | ||
| API de cotas | ||
| Recomendador | ||
| Redis | ||
| API do Gerenciador de Recursos | ||
| API de configurações de recursos | ||
| Varejo | ||
| API de rotas | ||
| Agendador | ||
| Gerenciamento Secreto | ||
| API do Gerenciador de Fonte Segura | ||
| API de gerenciamento do Security Center | ||
| Centro de Comando de Segurança | ||
| API de postura de segurança | ||
| Verificador de segurança | ||
| Acesso VPC sem servidor | ||
| API de controle de serviço | ||
| Diretório de serviços | ||
| API de gerenciamento de serviços | ||
| Uso do serviço | ||
| Concha | ||
| Chave inglesa | ||
| Chave Inglesa JDBC | ||
| Discurso | ||
| Monitoramento do Stackdriver | ||
| Rastreamento do Stackdriver | ||
| Armazenar | ||
| Serviço de transferência de armazenamento | ||
| TPU | ||
| Solução de Talentos | ||
| Tarefas | ||
| API de automação de telecomunicações | ||
| Texto para fala | ||
| Tradução | ||
| Migração de VM | ||
| Vértice AI | ||
| API VertexAI | ||
| Inteligência de vídeo | ||
| API de costura de vídeo | ||
| Transcodificador de vídeo | ||
| Visão | ||
| Risco da Web | ||
| Execuções de fluxo de trabalho | ||
| Fluxos de trabalho | ||
| API de complementos do Workspace | ||
| Estações de trabalho | ||
| reCAPTCHA Empresarial | ||
| API do hub de API | ||
| API do Gerenciador de anúncios | ||
| API de validação de endereço | ||
| Administrador do Google Analytics | ||
| Dados analíticos | ||
| Centro de análise | ||
| Anthos Multicloud | ||
| Serviço gerenciado para API Apache Kafka | ||
| API Hub de Aplicativos | ||
| Mesas da Área 120 | ||
| Backup para GKE | ||
| Solução Bare Metal | ||
| Lote | ||
| BeyondCorp AppConnections | ||
| Conectores de aplicativos BeyondCorp | ||
| BeyondCorp AppGateways | ||
| Serviços BeyondCorp ClientConnector | ||
| BeyondCorp ClientGateways | ||
| Lago Grande | ||
| API DataPolicy do BigQuery | ||
| Migração do BigQuery | ||
| API CSS | ||
| Gerenciador de certificados | ||
| API de bate-papo | ||
| Compras de consumo comercial | ||
| API de computação confidencial | ||
| Conectar API do Gateway | ||
| Rotulagem de dados | ||
| Fluxo de dados | ||
| Formulário de dados | ||
| API de conexão do desenvolvedor | ||
| Fluxo de diálogo CX | ||
| Armazém de IA de documentos | ||
| Gráfico de conhecimento empresarial | ||
| Relatório de erros | ||
| Publicação Eventarc | ||
| API de gerenciamento de hardware GDC | ||
| API de inventário KMS | ||
| Ciências da Vida | ||
| API de transmissão ao vivo | ||
| Registrando Logback Appender | ||
| Registrando o inicializador de servlet | ||
| API de conjuntos de dados da plataforma Maps | ||
| API de administração da plataforma de marketing | ||
| API de tradução de mídia | ||
| Conheça a API | ||
| API Memorystore para Redis | ||
| API do comerciante | ||
| API do comerciante | ||
| API do comerciante | ||
| API do comerciante | ||
| API do comerciante | ||
| API do comerciante | ||
| API de conversões de comerciante | ||
| API LFP do comerciante | ||
| API de notificações do comerciante | ||
| API de cota de comerciante | ||
| API do Centro de Migração | ||
| Monitorando escopos de métricas | ||
| Provedor de sistema de arquivos NIO para armazenamento | ||
| API NetApp | ||
| API de serviços de rede | ||
| Banco de Dados Oracle@API | ||
| API Parallelstore | ||
| Proteção contra phishing | ||
| API de locais (nova) | ||
| API de insights de lugares | ||
| API do Simulador de Política | ||
| Catálogo Privado | ||
| API do gerenciador de acesso privilegiado | ||
| Conector Pub/Sub Lite Flink | ||
| API de avaliação de migração rápida | ||
| IA de recomendações | ||
| API de registro | ||
| API de otimização de rota | ||
| Correr | ||
| API de configurações do Security Command Center | ||
| API de integridade do serviço | ||
| API solar | ||
| API de informações de armazenamento | ||
| API de suporte | ||
| Motor VMware | ||
| API de IA de visão | ||
| API de eventos do espaço de trabalho |
Se o serviço não estiver listado, google-api-java-client fará interface com APIs adicionais do Google Cloud usando uma interface REST legada.
Ao construir aplicações Java, deve-se dar preferência às bibliotecas listadas na tabela.
A maioria das bibliotecas google-cloud exige um ID de projeto. Existem várias maneiras de especificar esse ID do projeto.
google-cloud no Compute/App Engine, não há necessidade de especificar um ID do projeto. É inferido automaticamente do ambiente de produção.google-cloud em outro lugar, você pode fazer o seguinte:Forneça o ID do projeto ao criar as opções de serviço. Por exemplo, para usar o Datastore de um projeto com ID "PROJECT_ID", você pode escrever:
Datastore datastore = DatastoreOptions . newBuilder (). setProjectId ( "PROJECT_ID" ). build (). getService (); Especifique a variável de ambiente GOOGLE_CLOUD_PROJECT como o ID do projeto desejado.
Defina o ID do projeto usando o SDK do Google Cloud. Para usar o SDK, baixe-o, caso ainda não o tenha feito, e defina o ID do projeto na linha de comando. Por exemplo:
gcloud config set project PROJECT_ID
google-cloud determina o ID do projeto a partir das seguintes fontes na ordem listada, parando quando encontra um valor:
GOOGLE_CLOUD_PROJECTGOOGLE_APPLICATION_CREDENTIALSNos casos em que a biblioteca espera explicitamente um ID do projeto, fornecemos um auxiliar que pode fornecer o ID do projeto inferido:
import com . google . cloud . ServiceOptions ;
...
String projectId = ServiceOptions . getDefaultProjectId (); google-cloud-java usa https://github.com/googleapis/google-auth-library-java para autenticar solicitações. google-auth-library-java oferece suporte a uma ampla variedade de tipos de autenticação; consulte o README e o javadoc do projeto para obter mais detalhes.
Ao usar bibliotecas do Google Cloud de um ambiente do Google Cloud Platform, como Compute Engine, Kubernetes Engine ou App Engine, nenhuma etapa adicional de autenticação é necessária.
Por exemplo:
Storage storage = StorageOptions . getDefaultInstance (). getService ();ou:
CloudTasksClient cloudTasksClient = CloudTasksClient . create ();Gere uma chave de conta de serviço JSON.
Depois de baixar essa chave, você deve seguir um destes procedimentos:
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json Storage storage = StorageOptions . newBuilder ()
. setCredentials ( ServiceAccountCredentials . fromStream ( new FileInputStream ( "/path/to/my/key.json" )))
. build ()
. getService (); Se estiver executando localmente para desenvolvimento/teste, você poderá usar o SDK do Google Cloud. Crie credenciais padrão do aplicativo com gcloud auth application-default login e google-cloud detectará automaticamente essas credenciais.
Se você já possui um token de acesso OAuth2, você pode usá-lo para autenticar (observe que neste caso, o token de acesso não será atualizado automaticamente):
Credentials credentials = GoogleCredentials . create ( new AccessToken ( accessToken , expirationTime ));
Storage storage = StorageOptions . newBuilder ()
. setCredentials ( credentials )
. build ()
. getService ();ou:
Credentials credentials = GoogleCredentials . create ( new AccessToken ( accessToken , expirationTime ));
CloudTasksSettings cloudTasksSettings = CloudTasksSettings . newBuilder ()
. setCredentialProvider ( FixedCredentialsProvider . create ( credentials ))
. build ();
CloudTasksClient cloudTasksClient = CloudTasksClient . create ( cloudTasksSettings ); Se nenhuma credencial for fornecida, google-cloud tentará detectá-las no ambiente usando GoogleCredentials.getApplicationDefault() que procurará por credenciais padrão do aplicativo nos seguintes locais (em ordem):
GOOGLE_APPLICATION_CREDENTIALSgcloud auth application-default login do SDK do Google CloudA autenticação com chaves de API é suportada por algumas APIs do Google Cloud.
Estamos explorando ativamente maneiras de melhorar a experiência da chave de API. Atualmente, para usar uma chave de API com uma biblioteca cliente Java, você precisa definir manualmente o cabeçalho do cliente de serviço relevante.
Por exemplo, para definir a chave API com o serviço de idioma:
public LanguageServiceClient createGrpcClientWithApiKey ( String apiKey ) throws Exception {
// Manually set the api key via the header
Map < String , String > header = new HashMap < String , String >() { { put ( "x-goog-api-key" , apiKey );}};
FixedHeaderProvider headerProvider = FixedHeaderProvider . create ( header );
// Create the client
TransportChannelProvider transportChannelProvider = InstantiatingGrpcChannelProvider . newBuilder (). setHeaderProvider ( headerProvider ). build ();
LanguageServiceSettings settings = LanguageServiceSettings . newBuilder (). setTransportChannelProvider ( transportChannelProvider ). build ();
LanguageServiceClient client = LanguageServiceClient . create ( settings );
return client ;
}Um exemplo de instanciação com o Language Client usando rest:
public LanguageServiceClient createRestClientWithApiKey ( String apiKey ) throws Exception {
// Manually set the api key header
Map < String , String > header = new HashMap < String , String >() { { put ( "x-goog-api-key" , apiKey );}};
FixedHeaderProvider headerProvider = FixedHeaderProvider . create ( header );
// Create the client
TransportChannelProvider transportChannelProvider = InstantiatingHttpJsonChannelProvider . newBuilder (). setHeaderProvider ( headerProvider ). build ();
LanguageServiceSettings settings = LanguageServiceSettings . newBuilder (). setTransportChannelProvider ( transportChannelProvider ). build ();
LanguageServiceClient client = LanguageServiceClient . create ( settings );
return client ;
}Para obter ajuda, siga as instruções no documento Solução de problemas.
As bibliotecas de cliente do Google Cloud usam HTTPS e gRPC na comunicação subjacente com os serviços. Em ambos os protocolos, você pode configurar um proxy usando as propriedades https.proxyHost e (opcional) https.proxyPort .
Para um proxy mais personalizado com gRPC, você precisará fornecer um ProxyDetector para o ManagedChannelBuilder :
import com . google . api . core . ApiFunction ;
import com . google . api . gax . rpc . TransportChannelProvider ;
import com . google . cloud . tasks . v2 . CloudTasksClient ;
import com . google . cloud . tasks . v2 . CloudTasksSettings ;
import com . google . cloud . tasks . v2 . stub . CloudTasksStubSettings ;
import io . grpc . HttpConnectProxiedSocketAddress ;
import io . grpc . ManagedChannelBuilder ;
import io . grpc . ProxiedSocketAddress ;
import io . grpc . ProxyDetector ;
import javax . annotation . Nullable ;
import java . io . IOException ;
import java . net . InetSocketAddress ;
import java . net . SocketAddress ;
public CloudTasksClient getService () throws IOException {
TransportChannelProvider transportChannelProvider =
CloudTasksStubSettings . defaultGrpcTransportProviderBuilder ()
. setChannelConfigurator (
new ApiFunction < ManagedChannelBuilder , ManagedChannelBuilder >() {
@ Override
public ManagedChannelBuilder apply ( ManagedChannelBuilder managedChannelBuilder ) {
return managedChannelBuilder . proxyDetector (
new ProxyDetector () {
@ Nullable
@ Override
public ProxiedSocketAddress proxyFor ( SocketAddress socketAddress )
throws IOException {
return HttpConnectProxiedSocketAddress . newBuilder ()
. setUsername ( PROXY_USERNAME )
. setPassword ( PROXY_PASSWORD )
. setProxyAddress ( new InetSocketAddress ( PROXY_HOST , PROXY_PORT ))
. setTargetAddress (( InetSocketAddress ) socketAddress )
. build ();
}
});
}
})
. build ();
CloudTasksSettings cloudTasksSettings =
CloudTasksSettings . newBuilder ()
. setTransportChannelProvider ( transportChannelProvider )
. build ();
return CloudTasksClient . create ( cloudTasksSettings );
} As operações de longa execução (LROs, na sigla em inglês) costumam ser usadas para chamadas de API que devem levar muito tempo para serem concluídas (ou seja, provisionar uma instância do GCE ou um pipeline do Dataflow). A chamada inicial da API cria uma "operação" no servidor e retorna um ID de operação para acompanhar seu progresso. RPCs LRO têm o sufixo Async anexado ao nome da chamada (ou seja, clusterControllerClient.createClusterAsync() )
Nossos clientes gerados fornecem uma interface agradável para iniciar a operação e aguardar a conclusão da operação. Isso é feito retornando um OperationFuture . Ao chamar get() no OperationFuture , a biblioteca cliente pesquisará a operação para verificar o status da operação.
Por exemplo, veja um exemplo de operação createCluster no google-cloud-dataproc v4.20.0:
try ( ClusterControllerClient clusterControllerClient = ClusterControllerClient . create ()) {
CreateClusterRequest request =
CreateClusterRequest . newBuilder ()
. setProjectId ( "{PROJECT_ID}" )
. setRegion ( "{REGION}" )
. setCluster ( Cluster . newBuilder (). build ())
. setRequestId ( "{REQUEST_ID}" )
. setActionOnFailedPrimaryWorkers ( FailureAction . forNumber ( 0 ))
. build ();
OperationFuture < Cluster , ClusterOperationMetadata > future =
clusterControllerClient . createClusterOperationCallable (). futureCall ( request );
// Do something.
Cluster response = future . get ();
} catch ( CancellationException e ) {
// Exceeded the default RPC timeout without the Operation completing.
// Library is no longer polling for the Operation status. Consider
// increasing the timeout.
} As operações de polling têm um tempo limite padrão que varia de serviço para serviço. A biblioteca lançará um java.util.concurrent.CancellationException com a mensagem: Task was cancelled. se o tempo limite exceder a operação. Uma CancellationException não significa que a operação de back-end do GCP foi cancelada. Esta exceção é lançada da biblioteca cliente quando excede o tempo limite total sem receber um status de sucesso da operação. Nossas bibliotecas cliente respeitam os valores configurados definidos no OperationTimedPollAlgorithm para cada RPC.
Observação: a biblioteca cliente cuida do mecanismo de sondagem da operação para você. Por padrão, não há necessidade de pesquisar manualmente o status.
Cada RPC LRO possui um conjunto de valores padrão pré-configurados. Você pode encontrar esses valores pesquisando na classe StubSettings de cada cliente. As configurações padrão de LRO são inicializadas dentro do método initDefaults() na classe Builder aninhada.
Por exemplo, no google-cloud-aiplatform v3.24.0, o OperationTimedPollAlgorithm padrão tem estes valores padrão:
OperationTimedPollAlgorithm . create (
RetrySettings . newBuilder ()
. setInitialRetryDelay ( Duration . ofMillis ( 5000L ))
. setRetryDelayMultiplier ( 1.5 )
. setMaxRetryDelay ( Duration . ofMillis ( 45000L ))
. setInitialRpcTimeout ( Duration . ZERO )
. setRpcTimeoutMultiplier ( 1.0 )
. setMaxRpcTimeout ( Duration . ZERO )
. setTotalTimeout ( Duration . ofMillis ( 300000L ))
. build ())Tanto as novas tentativas quanto as LROs compartilham a mesma classe RetrySettings. Observe o link correspondente:
Os valores de tempo limite de RPC não têm uso em LROs e podem ser omitidos ou definidos com os valores padrão ( Duration.ZERO para tempos limite ou 1.0 para o multiplicador).
Para configurar os valores LRO, crie um objeto OperationTimedPollAlgorithm e atualize o algoritmo de sondagem do RPC. Por exemplo:
ClusterControllerSettings . Builder settingsBuilder = ClusterControllerSettings . newBuilder ();
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm . create (
RetrySettings . newBuilder ()
. setInitialRetryDelay ( Duration . ofMillis ( 500L ))
. setRetryDelayMultiplier ( 1.5 )
. setMaxRetryDelay ( Duration . ofMillis ( 5000L ))
. setInitialRpcTimeout ( Duration . ZERO ) // ignored
. setRpcTimeoutMultiplier ( 1.0 ) // ignored
. setMaxRpcTimeout ( Duration . ZERO ) // ignored
. setTotalTimeout ( Duration . ofHours ( 24L )) // set polling timeout to 24 hours
. build ());
settingsBuilder . createClusterOperationSettings ()
. setPollingAlgorithm ( timedRetryAlgorithm );
ClusterControllerClient clusterControllerClient = ClusterControllerClient . create ( settingsBuilder . build ()); Nota: A configuração acima modifica apenas os valores de LRO para o RPC createClusterOperation . Os outros RPCs no Cliente ainda usarão os valores LRO pré-configurados de cada RPC.
Se você estiver usando mais de uma biblioteca de cliente do Google Cloud, recomendamos usar um de nossos artefatos de lista de materiais (BOM) para ajudar a gerenciar versões de dependência. Para obter mais informações, consulte Usando as bibliotecas de cliente do Cloud.
Java 8 ou superior é necessário para usar os clientes neste repositório.
Os clientes neste repositório usam HTTP ou gRPC para a camada de transporte. Todos os clientes baseados em HTTP devem funcionar em todos os ambientes.
Para clientes que usam gRPC, as plataformas suportadas são limitadas pelas plataformas suportadas pelo Forked Tomcat Native, que para arquiteturas significa apenas x86_64 e para sistemas operacionais significa Mac OS X, Windows e Linux. Além disso, o gRPC restringe o uso de plataformas com restrições de threading.
Assim, o seguinte não é suportado:
Os seguintes ambientes devem funcionar (entre outros):
Esta biblioteca fornece ferramentas para ajudar a escrever testes para código que usa serviços Google-Cloud.
Consulte TESTES para ler mais sobre como usar nossos auxiliares de teste.
Esta biblioteca segue o Versionamento Semântico, com algumas qualificações adicionais:
Os componentes marcados com @BetaApi ou @Experimental são considerados recursos "0.x" dentro de uma biblioteca "1.x". Isso significa que eles podem alternar entre versões secundárias e de patch de maneiras incompatíveis. Esses recursos não devem ser usados por nenhuma biblioteca "B" que possua consumidores, a menos que os componentes da biblioteca B que usam os recursos @BetaApi também estejam marcados com @BetaApi . Os recursos marcados como @BetaApi estão a caminho de eventualmente se tornarem recursos "1.x" com o marcador removido.
Exceção especial para google-cloud-java : google-cloud-java pode depender dos recursos @BetaApi em gax-java sem declarar o código de consumo @BetaApi , porque gax-java e google-cloud-java se movem em sintonia um com o outro . Por esse motivo, gax-java não deve ser usado independentemente do google-cloud-java.
Os componentes marcados com @InternalApi são tecnicamente públicos, mas apenas devido às limitações dos modificadores de acesso do Java. Para efeitos de semver, devem ser considerados privados.
Interfaces marcadas com @InternalExtensionOnly são públicas, mas só devem ser implementadas por classes internas. Para fins de semver, nos reservamos o direito de adicionar a essas interfaces sem implementações padrão (para Java 7).
Observe que esses clientes estão atualmente em desenvolvimento ativo. Qualquer versão com versão 0.xy está sujeita a alterações incompatíveis com versões anteriores a qualquer momento.
Espera-se que as bibliotecas definidas em um nível de qualidade Estável sejam estáveis e que todas as atualizações nas bibliotecas sejam compatíveis com versões anteriores. Quaisquer alterações incompatíveis com versões anteriores levarão ao incremento da versão principal (1.xy -> 2.0.0).
As bibliotecas definidas no nível de qualidade de visualização ainda são um trabalho em andamento e têm maior probabilidade de receber atualizações incompatíveis com versões anteriores. Além disso, é possível que as bibliotecas de visualização sejam obsoletas e excluídas antes mesmo de serem promovidas para visualização ou estável.
Se estiver usando IntelliJ ou Eclipse, você pode adicionar bibliotecas de cliente ao seu projeto usando estes plug-ins IDE:
Além de adicionar bibliotecas de clientes, os plug-ins fornecem funcionalidades adicionais, como gerenciamento de chaves de contas de serviço. Consulte a documentação de cada plugin para obter mais detalhes.
Essas bibliotecas cliente podem ser usadas no App Engine padrão para o tempo de execução Java 8 e no App Engine flexível (incluindo o tempo de execução Compat). A maioria das bibliotecas não funciona no padrão App Engine para Java 7 runtime. No entanto, Datastore, Storage e BigQuery devem funcionar.
Contribuições para esta biblioteca são sempre bem-vindas e altamente incentivadas.
Consulte a documentação CONTRIBUTING do google-cloud e a documentação compartilhada para obter mais informações sobre como começar.
Observe que este projeto é lançado com um Código de Conduta do Colaborador. Ao participar deste projeto você concorda em cumprir seus termos. Consulte Código de Conduta para obter mais informações.
Apache 2.0 - Consulte LICENÇA para obter mais informações.
