Fortgeschrittene Nutzung

In diesem Leitfaden wird beschrieben, wie Sie einige der komplexeren Aspekte der Java-Clientbibliothek anpassen können. Ein gängiges Muster ist, dass viele dieser Funktionen auf dem zugrunde liegenden Callable und nicht auf den Standard-Convenience-Methoden basieren. Das Callable ist im Allgemeinen ein guter Ort, um nach anderen RPC-spezifischen Funktionen zu suchen, die hier nicht dokumentiert sind.

Zeitüberschreitung

Die Java-Bibliothek bietet eine Oberfläche zum Festlegen von Zeitlimits auf Aufrufebene. 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.

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. Die API kann jedoch bei extrem lang laufenden Anfragen trotzdem ein Zeitlimit überschreiten und den Fehler DEADLINE_EXCEEDED zurückgeben. Wenn dies zu einem Problem wird, ist es in der Regel am besten, die Abfrage aufzuteilen und die Blöcke parallel auszuführen. So wird vermieden, dass eine lang andauernde Anfrage fehlschlägt und die einzige Möglichkeit zur Wiederherstellung darin besteht, die Anfrage noch einmal von vorn zu starten.

Einstellungen für Wiederholungsversuche

Die Java-Bibliothek bietet auch eine Oberfläche zum Konfigurieren von Wiederholungseinstellungen auf Aufrufebene. Wenn Sie diese Funktion verwenden möchten, rufen Sie das Callable-Objekt direkt auf. Wenn Sie beispielsweise GoogleAdsService.searchStream() aufrufen, konfigurieren Sie die Wiederholungseinstellungen 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 kleinen Verzögerung kommen. Das liegt an der flüssigen Schnittstelle für Dienste (GoogleAdsClient.getLatestVersion()), die die API-Dienstklassen auf einmal lädt, um einen praktischen Mechanismus zum Erstellen von Dienstclients bereitzustellen.

Wenn die Leistung der ersten Anfrage für Ihre Anwendung kritisch ist, gehen Sie so vor:

  1. Erstellen Sie den GoogleAdsClient beim Start, bevor Nutzeranfragen verarbeitet werden.

  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 Aufwärmanfragen müssen nur einmal pro Prozess ausgeführt werden. Bei jeder nachfolgenden Erstellung eines Dienstclients werden die vorab geladenen Klassen automatisch wiederverwendet.

Wiederverwendung von Dienstclients

Sie sollten Dienstclientinstanzen nach Möglichkeit wiederverwenden, da jeder Aufruf von GoogleAdsClient.getLatestVersion().createYYYServiceClient() (oder eines versionsspezifischen Accessors wie getVersion26()) eine neue zugrunde liegende Verbindung und zugehörige Ressourcen erstellt.

Achten Sie darauf, den Dienstclient zu schließen, wenn er nicht mehr benötigt wird. Sie können dies in einem try-with-resources-Block oder durch Aufrufen von close() auf dem Dienstclient tun.

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

App Engine kann nicht bereitgestellt werden, wenn JAR > 32 MB

App Engine hat ein Kontingent von 32 MB für jede hochgeladene Datei. Die JAR-Datei für google-ads ist erheblich größer, insbesondere bei Verwendung von Shade- oder Shadow-JAR-Bereitstellungen. Wenn Sie JARs manuell bereitstellen, können Fehler wie die folgenden auftreten:

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

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 stattdessen diese hochgeladen werden.

Schattenabhä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 dann die Abhängigkeiten Ihres Projekts nach Bedarf (oder verwenden Sie die Materialliste):

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>48.1.0</version>
</dependency>

Gradle

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