Utilizzo avanzato

Questa guida descrive come personalizzare alcuni degli aspetti più avanzati della libreria client Java. Un pattern comune è che molte di queste funzionalità si basano sull'oggetto Callable sottostante anziché sui metodi di convenienza standard. In genere, l'oggetto callable è 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 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 al tempo massimo per 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 scadere per le richieste di lunga durata e restituire un DEADLINE_EXCEEDED errore. Se questo diventa un problema, in genere è 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 recuperare è attivare di nuovo la richiesta dall'inizio.

Impostazioni di ripetizione

La libreria Java fornisce anche una superficie per configurare le impostazioni di ripetizione a livello di chiamata. Per utilizzare questa funzionalità, chiama direttamente l'oggetto Callable. Ad esempio, quando chiami GoogleAdsService.searchStream(), configura le impostazioni di ripetizione 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 del rendimento 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 di servizi API per fornire un meccanismo pratico per la creazione di client di servizi.

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'avvio 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 riscaldamento devono essere eseguite una sola volta per processo. Ogni creazione successiva del client di servizi riutilizza automaticamente le classi precaricate.

Riutilizzo del client di servizi

Ti consigliamo di riutilizzare le istanze del client di servizi quando possibile, perché ogni chiamata a GoogleAdsClient.getLatestVersion().createYYYServiceClient() (o a un accessor specifico della versione, ad esempio getVersion26()) crea una nuova connessione sottostante e le risorse associate.

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

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

App Engine non esegue il deployment se il file JAR è > 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 di file 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.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

Esegui invece il deployment utilizzando il plug-in Gradle di App Engine o il plug-in Maven. Ogni plug-in fornisce un'opzione 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, esamina 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 materiali):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Se la risoluzione dei conflitti di dipendenza non è fattibile, puoi invece dipendere dalla versione shaded della libreria:

Maven

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

Gradle

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