Utilizzo avanzato

Questa guida descrive come personalizzare diversi aspetti più avanzati della libreria client Java. Un pattern comune è che molte di queste funzionalità si basano sul Callable sottostante anziché sui metodi standard. La chiamata è in genere un buon punto di partenza per cercare altre funzionalità per RPC non documentate qui.

Timeout

La libreria Java fornisce una superficie per impostare i timeout a livello di singola chiamata. Il valore predefinito è 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 al tempo massimo per una chiamata API.

Per utilizzare questa funzionalità, devi utilizzare direttamente l'oggetto chiamabile. Ad esempio, se chiami GoogleAdsService.searchStream(), il timeout verrà impostato come segue:

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)));
}

Puoi impostare il timeout su 2 ore o più, ma l'API potrebbe comunque andare in timeout per le richieste a esecuzione molto lunga e restituire un errore DEADLINE_EXCEEDED. Se questo diventa un problema, in genere è meglio dividere 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 recuperare è riavviarla dall'inizio.

Impostazioni di nuovi tentativi

La libreria Java fornisce anche una superficie per configurare le impostazioni di nuovi tentativi a livello di chiamata. Per utilizzare questa funzionalità, devi utilizzare direttamente l'oggetto chiamabile. Ad esempio, se chiami GoogleAdsService.searchStream(), le impostazioni di ripetizione verranno configurate come segue:

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

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.getVersionXX()), che carica tutte le classi API contemporaneamente per fornire un meccanismo più conveniente per la costruzione delle classi di servizio.

Se il rendimento della prima richiesta è 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 riscaldamento all'API Google Ads all'inizio della procedura. 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 (GoogleAdsException ex) {
      // Do nothing, we're expecting this to fail.
    }
  }
}

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

Riutilizzo del client di servizio

È consigliabile riutilizzare le istanze del client di servizio quando possibile, poiché ogni chiamata a GoogleAdsClient.getVersionXXX().createYYYServiceClient() creerà una nuova connessione TCP.

Devi assicurarti di chiudere il client quando non è più necessario. Questa operazione può essere eseguita 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 genererà un errore java.util.concurrent.RejectedExecutionException.

Il deployment di App Engine non riesce se il file JAR è superiore a 32 MB

App Engine ha una quota di 32 MB per ogni file caricato. Il file JAR per google-ads sarà molto più grande, soprattutto se utilizzi distribuzioni di file JAR shade/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-39.0.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 per App Engine. Ognuno ha un'opzione per enableJarSplitting che suddivide ogni file JAR in blocchi da 10 MB e carica questi ultimi.

Dipendenze shadow

Se il tuo progetto ha dipendenze in conflitto con quelle della libreria, devi ispezionare le dipendenze del progetto utilizzando uno dei seguenti comandi, quindi modificare le dipendenze del progetto in base alle esigenze.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se la risoluzione dei conflitti di dipendenza non è fattibile, puoi utilizzare la versione ombreggiata della libreria.

Maven

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

Gradle

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