Zaawansowane użycie

Z tego przewodnika dowiesz się, jak dostosować kilka bardziej zaawansowanych aspektów biblioteki klienta Java. Wiele z tych funkcji opiera się na bazowym obiekcie Callable, a nie na standardowych metodach ułatwiających. Obiekt Callable jest zwykle dobrym miejscem do szukania innych funkcji RPC, które nie są tu opisane.

Czas oczekiwania

Biblioteka Java udostępnia interfejs do ustawiania limitów czasu na poziomie poszczególnych wywołań. Wartość domyślna jest ustawiana na podstawie ustawienia method_config/timeout w googleads_grpc_service_config.json. Jeśli chcesz wymusić krótszy limit maksymalnego czasu wywołania interfejsu API, ustaw niższą wartość.

Aby użyć tej funkcji, wywołaj bezpośrednio obiekt Callable. Na przykład podczas wywoływania GoogleAdsService.searchStream() ustaw limit czasu w ten sposób:

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

Możesz ustawić limit czasu na 2 godziny lub więcej, ale interfejs API może nadal przekroczyć limit czasu w przypadku bardzo długotrwałych żądań i zwrócić błąd DEADLINE_EXCEEDED. Jeśli to się stanie, zwykle najlepiej jest podzielić zapytanie i wykonać fragmenty równolegle. Pozwoli to uniknąć sytuacji, w której długotrwałe żądanie nie powiedzie się, a jedynym sposobem na odzyskanie danych jest ponowne uruchomienie żądania od początku.

Ustawienia ponawiania

Biblioteka Java udostępnia też interfejs do konfigurowania ustawień ponawiania na poziomie poszczególnych wywołań. Aby użyć tej funkcji, wywołaj bezpośrednio obiekt Callable. Na przykład podczas wywoływania GoogleAdsService.searchStream() skonfiguruj ustawienia ponawiania w ten sposób:

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

Optymalizacja czasu uruchamiania

Przy pierwszym utworzeniu instancji GoogleAdsClient możesz zauważyć niewielkie opóźnienie. Wynika to z płynnego interfejsu usług (GoogleAdsClient.getLatestVersion()), który ładuje klasy usług interfejsu API jednocześnie, aby zapewnić wygodny mechanizm tworzenia klientów usług.

Jeśli skuteczność pierwszego żądania jest na ścieżce krytycznej aplikacji, wykonaj te czynności:

  1. Utwórz GoogleAdsClient podczas uruchamiania, zanim zaczniesz obsługiwać żądania użytkowników.

  2. Gdy proces się uruchomi, wyślij kilka żądań rozgrzewających do interfejsu Google Ads API. Na przykład:

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

Żądania rozgrzewające trzeba uruchomić tylko raz na proces. Każde kolejne utworzenie klienta usługi automatycznie ponownie wykorzystuje wstępnie załadowane klasy.

Ponowne użycie klienta usługi

W miarę możliwości należy ponownie używać instancji klienta usługi, ponieważ każde wywołanie GoogleAdsClient.getLatestVersion().createYYYServiceClient() (lub akcesora specyficznego dla wersji, np. getVersion26()) tworzy nowe połączenie bazowe i powiązane zasoby.

Gdy klient usługi nie jest już potrzebny, zamknij go. Możesz to zrobić w bloku try-with-resources lub wywołując close() w kliencie usługi.

Jeśli spróbujesz użyć zamkniętego klienta usługi do wysyłania żądań do interfejsu API, metoda klienta usługi zgłosi wyjątek java.util.concurrent.RejectedExecutionException.

Nie można wdrożyć App Engine, jeśli plik JAR ma więcej niż 32 MB

App Engine ma limit 32 MB na każdy przesłany plik. Plik JAR google-ads jest znacznie większy, zwłaszcza w przypadku korzystania z wdrożeń JAR z zacienieniem lub cieniem. Jeśli wdrażasz pliki JAR ręcznie, możesz zobaczyć takie błędy:

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

Zamiast tego wdróż za pomocą wtyczki App Engine Gradle lub Maven. Każda wtyczka udostępnia opcję enableJarSplitting, która dzieli każdy plik JAR na fragmenty o rozmiarze 10 MB i przesyła je.

Zależności cienia

Jeśli Twój projekt ma zależności, które są sprzeczne z zależnościami biblioteki, sprawdź hierarchię zależności projektu za pomocą jednego z tych poleceń, a następnie zmodyfikuj zależności projektu zgodnie z potrzebami (lub użyj zestawienia materiałów):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Jeśli rozwiązanie konfliktów zależności jest niemożliwe, możesz zamiast tego polegać na zacienionej wersji biblioteki:

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'