高度な使用方法

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このガイドでは、Java クライアント ライブラリの高度な機能のカスタマイズ方法について概説します。一般的なパターンとして、これらの機能の多くは標準メソッドではなく、基盤となる Callable に依存しています。通常、Callable は、ここでは説明されていない他の RPC ごとの機能を探すのに適した場所です。

タイムアウト

Java ライブラリには、呼び出しレベルでタイムアウトを設定するサーフェスが用意されています。デフォルト値は、googleads_grpc_service_config.json の method_config/timeout 設定に基づいて設定されます。API 呼び出しの最大時間を短く制限する必要がある場合は、より低い値を設定します。

この機能を使用するには、呼び出し可能なオブジェクトを直接使用する必要があります。たとえば、GoogleAdsService.searchStream() を呼び出す場合、タイムアウトは次のように設定されます。

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

タイムアウトを 2 時間以上に設定できますが、非常に長時間実行されるリクエストでタイムアウトが発生し、DEADLINE_EXCEEDED エラーが返されることがあります。これが問題になる場合は、通常、クエリを分割してチャンクを並行して実行することをおすすめします。これにより、長時間実行されるリクエストが失敗し、復元する唯一の方法がリクエストを最初から再度トリガーすることになる状況を回避できます。

設定の再試行

Java ライブラリには、呼び出しレベルで再試行設定を構成するためのサーフェスも用意されています。この機能を使用するには、呼び出し可能なオブジェクトを直接使用する必要があります。たとえば、GoogleAdsService.searchStream() を呼び出す場合、再試行設定は次のように構成されます。

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

起動時間のパフォーマンスの最適化

GoogleAdsClient インスタンスが初めて作成されるときに、わずかな遅延が生じることがあります。これは、サービスの fluent インターフェース（GoogleAdsClient.getVersionXX()）によるものです。このインターフェースは、サービスクラスの作成に便利なメカニズムを提供するため��、すべての API クラスを一度に読み込みます。

最初のリクエストのパフォーマンスがアプリケーションのクリティカル パスにある場合は、次の手順を実施する必要があります。

1. 起動時に、ユーザー リクエストを処理する前に GoogleAdsClient を作成します。

2. プロセスの開始時に、Google Ads API にいくつかのウォームアップ リクエストを送信します。次に例を示します。

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

ウォームアップ リクエストは、プロセスごとに 1 回だけ実行する必要があります。その後、サービス クライアントを作成すると、プリロードされたクラスが自動的に再利用されます。

サービス クライアントの再利用

GoogleAdsClient.getVersionXXX().createYYYServiceClient() の呼び出しごとに新しい TCP 接続が作成されるため、可能であればサービス クライアント インスタンスを再利用する必要があります。

クライアントが不要になったら、必ずクローズする必要があります。これは、try-with-resources ブロックで行うことができます。または、サービス クライアントで close() を呼び出すこともできます。

クローズド サービス クライアントを使用して API リクエストを実行しようとすると、サービス クライアント メソッドが java.util.concurrent.RejectedExecutionException をスローします。

JAR が 32 MB を超えると App Engine がデプロイされない

App Engine には、アップロードされるファイルごとに 32 MB の割り当てがあります。google-ads の JAR は、シェード/シャドウ JAR デプロイを使用すると、これよりもかなり大きくなります。JAR を手動でデプロイすると、次のようなエラーが発生することがあります。

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

代わりに、AppEngine の Gradle プラグインまたは Maven プラグインを使用してデプロイします。各ファイルには enableJarSplitting のオプションがあり、各 jar を 10 MB のチャンクに分割してアップロードします。

シャドウ依存関係

プロジェクトにライブラリと競合する依存関係がある場合は、次のいずれかのコマンドを使用してプロジェクトの依存関係を検査し、必要に応じてプロジェクトの依存関係を変更する必要があります。

mvn dependency:tree

./gradlew dependencies

依存関係の競合を解決できない場合は、代わりにライブラリのシャドウ化バージョンに依存できます。

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

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