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 subjacente em vez dos métodos padrão. O objeto chamável geralmente é um bom lugar para procurar outros recursos por RPC que não estão documentados aqui.

Tempo limite

A biblioteca Java oferece uma interface para definir tempos limite em nível de 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 impor um limite mais curto no tempo máximo de uma chamada de API.

Para usar esse recurso, use o objeto chamável diretamente. Por exemplo, se você chamar 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 como duas horas ou mais, mas a API ainda pode atingir o tempo limite de solicitações de execução extremamente longa 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 de longa duração falha e a única maneira de se recuperar é acionar a solicitação novamente desde o início.

Tentar novamente as configurações

A biblioteca Java também oferece uma interface para configurar as configurações de nova tentativa em um nível por chamada. Para usar esse recurso, use o objeto chamável 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 performance do tempo de inicialização

Você pode notar um pequeno atraso na primeira vez que uma instância GoogleAdsClient é criada. Isso ocorre devido à interface fluente para serviços (GoogleAdsClient.getVersionXX()), que carrega todas as classes de API de uma só vez para oferecer um mecanismo mais conveniente de construção de classes de serviço.

Se a performance da primeira solicitação estiver no caminho crítico do seu 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 for iniciado. 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. Toda criação subsequente de cliente de serviço reutilizará automaticamente as classes pré-carregadas.

Reutilização do cliente de serviço

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

Feche 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 um java.util.concurrent.RejectedExecutionException.

O App Engine não implanta 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 de sombra/sombreamento. Se você implantar jars manualmente, poderá receber erros como:

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

Em vez disso, faça a implantação usando o plug-in do Gradle ou plug-in do Maven do App Engine. Cada um tem uma opção para enableJarSplitting, que divide cada arquivo JAR em partes de 10 MB e faz upload delas.

Dependências de sombra

Se o projeto tiver dependências que entram em conflito com a biblioteca, inspecione as dependências do projeto usando um dos seguintes comandos e modifique-as conforme necessário.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se não for possível resolver conflitos de dependência, use a versão sombreada da biblioteca.

Maven

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

Gradle

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