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 de conveniência 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 superfície 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 você precisar aplicar um limite menor no tempo máximo de uma chamada de API.

Para usar esse recurso, chame o objeto Callable diretamente. Por exemplo, ao chamar GoogleAdsService.searchStream(), defina o tempo limite da seguinte maneira:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // Executes the API call with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient
          .searchStreamCallable()
          .call(
              request,
              GrpcCallContext.createDefault()
                  .withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

É 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 recuperar é acionar a solicitação novamente desde o início.

Configurações de repetição

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, chame o objeto Callable diretamente. Por exemplo, ao chamar GoogleAdsService.searchStream(), configure as configurações de nova tentativa da seguinte maneira:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // 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());

  // Issues the streaming search request.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient.searchStreamCallable().call(request, context);
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

Otimização da 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.getLatestVersion()), que carrega as classes de serviço da API de uma só vez para fornecer um mecanismo conveniente de construção de clientes 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 (ApiException 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 de clientes de serviço

É recomendável reutilizar instâncias de cliente de serviço sempre que possível, porque cada chamada para GoogleAdsClient.getLatestVersion().createYYYServiceClient() (ou um acessador específico da versão, como getVersion25()) cria uma nova conexão subjacente e recursos associados.

Feche o cliente de serviço quando ele não for mais necessário. É possível fazer isso 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 é consideravelmente maior do que isso, especialmente ao usar implantações de JAR de sombra ou shade. Se você implantar JARs manualmente, poderá receber erros como:

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-46.1.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 Gradle ou o plug-in Maven do App Engine. Cada plug-in oferece uma opção enableJarSplitting que divide cada JAR em partes de 10 MB e faz upload delas.

Dependências ocultas

Se o projeto tiver dependências que entram em conflito com as da biblioteca, inspecione a hierarquia de dependências do projeto usando um dos seguintes comandos e modifique as dependências do projeto conforme necessário (ou use a lista de materiais):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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