Utilizzo avanzato

Questa guida illustra come personalizzare alcuni degli aspetti più avanzati della libreria client Java. Un pattern comune è che molte di queste funzionalità si basano sul Callable sottostante anziché sui metodi di convenienza standard. L'oggetto chiamabile è in genere un buon punto di partenza per cercare altre funzionalità per RPC non documentate qui.

Timeout

La libreria Java fornisce una superficie per l'impostazione dei timeout a livello di singola chiamata. Il valore predefinito viene impostato in base all'impostazione method_config/timeout in googleads_grpc_service_config.json. Imposta un valore inferiore se devi applicare un limite più breve per il tempo massimo di una chiamata API.

Per utilizzare questa funzionalità, chiama direttamente l'oggetto Callable. Ad esempio, quando chiami GoogleAdsService.searchStream(), imposta il timeout come segue:

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.
  }
}

Puoi impostare il timeout su 2 ore o più, ma l'API potrebbe comunque andare in timeout per le richieste con tempi di esecuzione estremamente lunghi e restituire un errore DEADLINE_EXCEEDED. Se questo diventa un problema, di solito è meglio suddividere la query ed eseguire i blocchi in parallelo. In questo modo si evita la situazione in cui una richiesta di lunga durata non va a buon fine e l'unico modo per recuperarla è attivarla di nuovo dall'inizio.

Impostazioni dei nuovi tentativi

La libreria Java fornisce anche una superficie per configurare le impostazioni dei nuovi tentativi a livello di singola chiamata. Per utilizzare questa funzionalità, chiama direttamente l'oggetto Callable. Ad esempio, quando chiami GoogleAdsService.searchStream(), configura le impostazioni dei nuovi tentativi come segue:

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.
  }
}

Ottimizzazione delle prestazioni del tempo di avvio

Potresti notare un piccolo ritardo la prima volta che viene creata un'istanza GoogleAdsClient. Ciò è dovuto all'interfaccia fluida per i servizi (GoogleAdsClient.getLatestVersion()), che carica contemporaneamente le classi dei servizi API per fornire un meccanismo pratico per la creazione dei client dei servizi.

Se le prestazioni della prima richiesta sono nel percorso critico della tua applicazione, segui questi passaggi:

  1. Crea GoogleAdsClient all'avvio, prima di gestire le richieste degli utenti.

  2. Invia alcune richieste di preparazione all'API Google Ads all'inizio del processo. Ad esempio:

    // 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.
    }
  }
}

Le richieste di warmup devono essere eseguite una sola volta per processo. Ogni creazione successiva di un client di servizio riutilizza automaticamente le classi precaricate.

Riutilizzo del client di servizio

Se possibile, riutilizza le istanze del client di servizio perché ogni chiamata a GoogleAdsClient.getLatestVersion().createYYYServiceClient() (o a un metodo di accesso specifico per la versione come getVersion26()) crea una nuova connessione sottostante e le risorse associate.

Assicurati di chiudere il client di servizio quando non è più necessario. Puoi farlo in un blocco try-with-resources o chiamando close() sul client di servizio.

Se tenti di utilizzare un client di servizio chiuso per effettuare richieste API, il metodo del client di servizio genera un errore java.util.concurrent.RejectedExecutionException.

Il deployment di App Engine non va a buon fine se il file JAR è maggiore di 32 MB

App Engine ha una quota di 32 MB per ogni file caricato. Il file JAR per google-ads è notevolmente più grande, soprattutto quando si utilizzano deployment JAR shade o shadow. Se esegui il deployment dei file JAR manualmente, potresti ricevere errori come:

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

Esegui invece il deployment utilizzando il plug-in Gradle o il plug-in Maven di App Engine. Ogni plug-in fornisce un'opzione enableJarSplitting che suddivide ogni JAR in blocchi da 10 MB e carica questi ultimi.

Dipendenze shadow

Se il tuo progetto ha dipendenze in conflitto con quelle della libreria, controlla la gerarchia delle dipendenze del progetto utilizzando uno dei seguenti comandi, quindi modifica le dipendenze del progetto in base alle esigenze (o utilizza la distinta base):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se non è possibile risolvere i conflitti di dipendenza, puoi utilizzare la versione shaded della libreria:

Maven

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

Gradle

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