Fortgeschrittene Nutzung

In dieser Anleitung wird beschrieben, wie Sie einige der erweiterten Aspekte der Java-Clientbibliothek anpassen können. Ein häufiges Muster ist, dass viele dieser Funktionen auf der zugrunde liegenden Callable anstelle der Standard-Convenience-Methoden basieren. Die aufrufbare Funktion ist in der Regel ein guter Ort, um nach anderen RPC-Funktionen zu suchen, die hier nicht dokumentiert sind.

Zeitüberschreitung

Die Java-Bibliothek bietet eine Oberfläche zum Festlegen von Zeitüberschreitungen auf Anrufebene. Der Standardwert wird basierend auf der Einstellung method_config/timeout in googleads_grpc_service_config.json festgelegt. Legen Sie einen niedrigeren Wert fest, wenn Sie ein kürzeres Limit für die maximale Zeit für einen API-Aufruf erzwingen möchten.

Wenn Sie diese Funktion verwenden möchten, rufen Sie das Callable-Objekt direkt auf. Wenn Sie beispielsweise GoogleAdsService.searchStream() aufrufen, legen Sie das Zeitlimit so fest:

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

Sie können das Zeitlimit auf 2 Stunden oder mehr festlegen. Bei sehr zeitaufwendigen Anfragen kann es jedoch trotzdem zu einem Zeitlimitüberschreitungsfehler kommen und die API gibt dann den Fehler DEADLINE_EXCEEDED zurück. Wenn dies zu einem Problem wird, ist es in der Regel am besten, die Abfrage aufzuteilen und die Teile parallel auszuführen. So wird vermieden, dass eine lang andauernde Anfrage fehlschlägt und die einzige Möglichkeit zur Wiederherstellung darin besteht, die Anfrage von Anfang an neu zu starten.

Wiederholungseinstellungen

Die Java-Bibliothek bietet auch eine Möglichkeit, die Einstellungen für Wiederholungsversuche auf Anrufebene zu konfigurieren. Wenn Sie diese Funktion verwenden möchten, rufen Sie das Callable-Objekt direkt auf. Wenn Sie beispielsweise GoogleAdsService.searchStream() aufrufen, konfigurieren Sie die Einstellungen für Wiederholungsversuche so:

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

Optimierung der Startzeit

Beim ersten Erstellen einer GoogleAdsClient-Instanz kann es zu einer kurzen Verzögerung kommen. Das liegt an der Fluent-Schnittstelle für Dienste (GoogleAdsClient.getLatestVersion()), die die API-Dienstklassen gleichzeitig lädt, um einen praktischen Mechanismus zum Erstellen von Dienstclients bereitzustellen.

Wenn die Leistung der ersten Anfrage für Ihre Anwendung auf dem kritischen Pfad liegt, gehen Sie so vor:

  1. Erstellen Sie GoogleAdsClient beim Start, bevor Sie Nutzeranfragen bearbeiten.

  2. Senden Sie zu Beginn des Prozesses einige Aufwärmanfragen an die Google Ads API. Beispiel:

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

Die Warm-up-Anfragen müssen nur einmal pro Prozess ausgeführt werden. Bei jeder nachfolgenden Erstellung eines Dienstclients werden die vorab geladenen Klassen automatisch wiederverwendet.

Wiederverwendung von Dienst-Clients

Sie sollten Dienstclientinstanzen nach Möglichkeit wiederverwenden, da bei jedem Aufruf von GoogleAdsClient.getLatestVersion().createYYYServiceClient() (oder einem versionsspezifischen Accessor wie getVersion25()) eine neue zugrunde liegende Verbindung und zugehörige Ressourcen erstellt werden.

Schließen Sie den Dienstclient, wenn er nicht mehr benötigt wird. Sie können dies in einem try-with-resources-Block oder durch Aufrufen von close() für den Dienstclient tun.

Wenn Sie versuchen, mit einem geschlossenen Dienstclient API-Anfragen zu stellen, löst die Dienstclientmethode eine java.util.concurrent.RejectedExecutionException aus.

Fehler bei der App Engine-Bereitstellung, wenn JAR-Datei größer als 32 MB ist

Für jede hochgeladene Datei gilt in App Engine ein Kontingent von 32 MB. Die JAR-Datei für google-ads ist deutlich größer, insbesondere bei Verwendung von Shade- oder Shadow-JAR-Bereitstellungen. Wenn Sie JARs manuell bereitstellen, erhalten Sie möglicherweise Fehlermeldungen wie:

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])

Verwenden Sie stattdessen das Gradle-Plug-in oder das Maven-Plug-in von App Engine für die Bereitstellung. Jedes Plug-in bietet eine enableJarSplitting-Option, mit der jede JAR-Datei in 10‑MB-Blöcke aufgeteilt und diese stattdessen hochgeladen werden.

Nicht verwaltete Abhängigkeiten

Wenn Ihr Projekt Abhängigkeiten hat, die mit den Abhängigkeiten der Bibliothek in Konflikt stehen, prüfen Sie die Abhängigkeitshierarchie Ihres Projekts mit einem der folgenden Befehle und ändern Sie die Abhängigkeiten Ihres Projekts nach Bedarf (oder verwenden Sie die Materialliste):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Wenn es nicht möglich ist, Abhängigkeitskonflikte zu beheben, können Sie stattdessen die verschleierte Version der Bibliothek verwenden:

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'