Uso avançado

Este guia descreve como personalizar vários aspectos mais avançados da biblioteca de cliente Java. Um padrão comum é que muitos desses recursos dependem do Callable em vez dos métodos padrão. O elemento que pode ser chamado é geralmente um bom lugar para procurar outros recursos por RPC que não estão documentados aqui.

Tempo limite

A biblioteca Java fornece uma superfície para definir timeouts no nível de cada chamada. O valor padrão é definido com base na configuração method_config/timeout em googleads_grpc_service_config.json. Defina um valor menor se precisar aplicar um limite mais curto no tempo máximo de uma chamada de API.

Para usar esse recurso, use o objeto que pode ser chamado diretamente. Por exemplo, se a chamada for GoogleAdsService.searchStream(), o tempo limite será definido como:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request = ...

  // Executes the API call, with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> result = googleAdsServiceClient
      .searchStreamCallable()
      .call(request,
          GrpcCallContext.createDefault().withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
}

É possível definir o tempo limite para 2 horas ou mais, mas a API ainda pode esgotar o tempo limite de solicitações extremamente longas e retornar um erro DEADLINE_EXCEEDED. Se isso se tornar um problema, geralmente é melhor dividir a consulta e executar os blocos em paralelo. Isso evita a situação em que uma solicitação demorada falha e a única maneira de recuperar é acionar a solicitação novamente desde o início.

Tentar novamente as configurações

A biblioteca Java também fornece uma plataforma para configurar as configurações de nova tentativa em um nível por chamada. Para usar esse recurso, use o objeto que pode ser chamado diretamente. Por exemplo, se você chamar GoogleAdsService.searchStream(), as configurações de nova tentativa serão configuradas da seguinte maneira:

// Creates a context object with the custom retry settings.
GrpcCallContext context = GrpcCallContext.createDefault()
    .withRetrySettings(RetrySettings.newBuilder()
    .setInitialRetryDelay(Duration.ofMillis(10L))
    .setMaxRetryDelay(Duration.ofSeconds(10L))
    .setRetryDelayMultiplier(1.4)
    .setMaxAttempts(10)
    .setLogicalTimeout(Duration.ofSeconds(30L))
    .build());

// Creates and issues a search Google Ads stream request.
ServerStream<SearchGoogleAdsStreamResponse> stream =
    googleAdsServiceClient.searchStreamCallable().call(request, context);

Otimização de desempenho no tempo de inicialização

Talvez você perceba um pequeno atraso na primeira vez que uma instância GoogleAdsClient é criada. Isso ocorre devido à interface fluída para serviços (GoogleAdsClient.getVersionXX()), que carrega todas as classes de API de uma só vez para fornecer um mecanismo mais conveniente para a construção de classes de serviço.

Se a performance da primeira solicitação estiver no caminho crítico do aplicativo, siga estas etapas:

1. Crie o GoogleAdsClient na inicialização, antes de atender às solicitações do usuário.

2. Envie algumas solicitações de aquecimento para a API Google Ads quando o processo começar. Exemplo:

   // Runs some warm-up requests.
   try (GoogleAdsServiceClient googleAdsServiceClient =
       googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
     // Runs 5 warm-up requests. In our profiling we see that 90% of performance
     // loss is only experienced on the first API call. After 3 subsequent calls we
     // saw a negligible improvement in performance.
     for (int i = 0; i < 5; ++i) {
       // Warm-up queries are run with a nonexistent CID so the calls will fail. If
       // you have a CID that you know will be accessible with the OAuth
       // credentials provided you may want to provide that instead and avoid the
       // try-catch.
       try {
         googleAdsServiceClient.search("-1", "Warm-up query");
       } catch (GoogleAdsException ex) {
         // Do nothing, we're expecting this to fail.
       }
     }
   }
   

As solicitações de aquecimento só precisam ser executadas uma vez por processo. Cada criação de cliente de serviço subsequente reutilizará automaticamente as classes pré-carregadas.

Reutilização do cliente do serviço

Reutilize as instâncias do cliente de serviço sempre que possível, já que cada chamada para GoogleAdsClient.getVersionXXX().createYYYServiceClient() cria uma nova conexão TCP.

É necessário fechar o cliente quando ele não for mais necessário. Isso pode ser feito em um bloco try-with-resources ou chamando close() no cliente de serviço.

Se você tentar usar um cliente de serviço fechado para fazer solicitações de API, o método do cliente de serviço vai gerar uma java.util.concurrent.RejectedExecutionException.

O App Engine não consegue implantar se o JAR for maior que 32 MB

O App Engine tem uma cota de 32 MB para cada arquivo enviado. O JAR para google-ads será consideravelmente maior do que isso, ainda mais usando implantações de JAR sombreado. Se você implantar os JARs manualmente, poderá receber erros como:

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-34.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

Em vez disso, implante usando o plug-in do Gradle ou o plug-in do Maven do App Engine. Cada um tem uma opção para enableJarSplitting, que vai dividir cada jar em blocos de 10 MB e fazer o upload deles.

Dependências de sombra

Se o projeto tiver dependências que conflitam com as da biblioteca, inspecione as dependências do projeto usando um dos comandos abaixo e, em seguida, modifique-as conforme necessário.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se a resolução de conflitos de dependência for inviável, você poderá depender da versão sombreada da biblioteca.

Maven

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads-shadowjar</artifactId>
  <version>34.0.0</version>
</dependency>

Gradle

implementation 'com.google.api-ads:google-ads-shadowjar:34.0.0'