Erweiterte Nutzung

In dieser Anleitung wird beschrieben, wie Sie einige der erweiterten Aspekte der Java-Clientbibliothek anpassen. Ein gängiges Muster ist, dass viele dieser Features auf dem zugrunde liegenden Callable und nicht auf den Standardmethoden basieren. Das Callable ist im Allgemeinen eine gute Möglichkeit, nach anderen RPC-Funktionen zu suchen, die hier nicht dokumentiert sind.

Zeitlimit

Die Java-Bibliothek bietet eine Oberfläche zum Festlegen von Zeitüberschreitungen pro Aufruf. Der Standardwert wird anhand 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üssen.

Um diese Funktion zu nutzen, müssen Sie das aufrufbare Objekt direkt verwenden. Beim Aufrufen von GoogleAdsService.searchStream() wird das Zeitlimit beispielsweise so festgelegt:

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

Sie können das Zeitlimit auf 2 Stunden oder mehr festlegen. Es kann aber trotzdem passieren, dass die API bei Anfragen mit extrem langer Ausführungszeit das Zeitlimit überschreitet und den Fehler DEADLINE_EXCEEDED zurückgibt. Wenn dies zu einem Problem wird, ist es in der Regel am besten, die Abfrage aufzuteilen und die Blöcke parallel auszuführen. So vermeiden Sie, dass eine lang andauernde Anfrage fehlschlägt und die einzige Möglichkeit zur Wiederherstellung darin besteht, die Anfrage noch einmal von Anfang an auszulösen.

Einstellungen für Wiederholungsversuche

Die Java-Bibliothek bietet auch eine Oberfläche zum Konfigurieren von Wiederholungseinstellungen auf Aufrufebene. Um diese Funktion zu nutzen, müssen Sie das aufrufbare Objekt direkt verwenden. Wenn Sie beispielsweise GoogleAdsService.searchStream() aufrufen, werden die Einstellungen für die Wiederholung so konfiguriert:

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

Leistungsoptimierung beim Start

Beim ersten Erstellen einer GoogleAdsClient-Instanz kann es zu einer kleinen Verzögerung kommen. Dies liegt an der flüssigen Schnittstelle für Dienste (GoogleAdsClient.getVersionXX()), die alle API-Klassen gleichzeitig lädt, um einen bequemeren Mechanismus zum Erstellen von Dienstklassen zu bieten.

Wenn sich die Leistung der ersten Anfrage im kritischen Pfad für Ihre Anwendung befindet, sollten Sie so vorgehen:

  1. Erstellen Sie die GoogleAdsClient beim Start, bevor Sie Nutzeranfragen verarbeiten.

  2. Zu Beginn des Prozesses einige Aufwärmanfragen an die Google Ads API senden. 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 (GoogleAdsException ex) {
      // Do nothing, we're expecting this to fail.
    }
  }
}

Die Aufwärmanfragen müssen nur einmal pro Prozess ausgeführt werden. Bei jeder nachfolgenden Dienstclient-Erstellung werden die vorab geladenen Klassen automatisch wiederverwendet.

Wiederverwendung des Dienstclients

Sie sollten Dienstclient-Instanzen wenn möglich wiederverwenden, da bei jedem Aufruf von GoogleAdsClient.getVersionXXX().createYYYServiceClient() eine neue TCP-Verbindung hergestellt wird.

Sie müssen den Client schließen, wenn er nicht mehr benötigt wird. Dies kann in einem try-with-resources-Block oder durch Aufrufen von close() auf dem Dienstclient erfolgen.

Wenn Sie versuchen, einen geschlossenen Dienstclient für API-Anfragen zu verwenden, gibt die Dienstclientmethode eine java.util.concurrent.RejectedExecutionException aus.

App Engine kann nicht bereitgestellt werden, wenn JAR größer als 32 MB ist

App Engine hat ein Kontingent von 32 MB für jede hochgeladene Datei. Die JAR-Datei für google-ads wird erheblich größer sein, noch mehr bei Verwendung von Shadow-/Shadow-JAR-Bereitstellungen. Wenn Sie JAR-Dateien manuell bereitstellen, erhalten Sie möglicherweise Fehler wie:

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

Stellen Sie sie stattdessen mit dem Gradle-Plug-in von AppEngine oder dem Maven-Plug-in bereit. Jede hat eine Option für enableJarSplitting, die jede JAR-Datei in Blöcke von 10 MB aufteilt und stattdessen diese hochlädt.

Schattenabhängigkeiten

Wenn Abhängigkeiten Ihres Projekts mit denen der Bibliothek in Konflikt stehen, sollten Sie die Abhängigkeiten Ihres Projekts mit einem der folgenden Befehle überprüfen und die Abhängigkeiten Ihres Projekts dann nach Bedarf ändern.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Wenn das Lösen von Abhängigkeitskonflikten nicht möglich ist, können Sie stattdessen die shaded-Version der Bibliothek verwenden.

Maven

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

Gradle

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