Uso avançado

Este guia descreve como personalizar vários dos aspectos mais avançados da biblioteca de cliente Java. Um padrão comum é que muitos desses recursos dependem do Callable subjacente em vez de métodos padrão. Geralmente, a chamada é 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 tempos limite por 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 menor no tempo máximo para uma chamada de API.

Para usar esse recurso, use o objeto chamável diretamente. Por exemplo, se 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 expirar solicitações muito 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 de longa duração falha e a única maneira de se recuperar é acionar a solicitação novamente desde o início.

Configurações de nova tentativa

A biblioteca Java também fornece uma superfície para definir configurações de repetição por chamada. Para usar esse recurso, use o objeto chamável diretamente. Por exemplo, se chamar GoogleAdsService.searchStream(), as configurações de nova tentativa serão definidas 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 do desempenho do tempo de inicialização

É possível notar um pequeno atraso na primeira vez que uma instância GoogleAdsClient é criada. Isso se deve à interface fluente para serviços (GoogleAdsClient.getVersionXX()), que carrega todas as classes de API de uma só vez para fornecer um mecanismo mais conveniente para a criação de classes de serviço.

Se o desempenho 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 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. Cada criação subsequente de cliente de serviço reutiliza automaticamente as classes pré-carregadas.

Reutilização do cliente de serviço

Reutilize as instâncias de cliente de serviço quando for prático, já que cada chamada para GoogleAdsClient.getVersionXXX().createYYYServiceClient() criará uma nova conexão TCP.

Você precisa fechar o cliente quando ele não for mais necessário. Para fazer isso, use um bloco try-with-resources ou chame 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 será implantado se o JAR for maior que 32 MB

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

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-14.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 dividirá cada jar em blocos de 10 MB e fará upload deles.

Dependências de sombra

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se resolver conflitos de dependência for inviável, você poderá usar a versão shaded da biblioteca.

Maven

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

Gradle

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