進階用法

本指南說明如何自訂 Java 用戶端程式庫的幾項進階功能。常見模式是，許多這類功能都依賴基礎 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 小時以上，但對於執行時間極長的要求，API 仍可能逾時並傳回 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 執行個體時，會稍微延遲。這是因為服務的流暢介面 (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.
    }
  }
}

每個程序只需要執行一次暖機要求。後續建立的每個服務用戶端都會自動重複使用預先載入的類別。

重複使用服務用戶端

您應盡可能重複使用服務用戶端執行個體，因為每次呼叫 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 會比這個大得多，如果使用 shade/shadow JAR 部署作業，則會更大。如果您手動部署 JAR，可能會收到類似下列內容的錯誤：

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

請改用 App Engine Gradle 外掛程式或 Maven 外掛程式進行部署。每個 JAR 都有 enableJarSplitting 選項，可將每個 JAR 分割成 10 MB 的區塊，然後上傳這些區塊。

陰影依附元件

如果專案的依附元件與程式庫的依附元件衝突，請使用下列其中一個指令檢查專案的依附元件，然後視需要修改專案的依附元件。

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

如果無法解決依附元件衝突，可以改為依附程式庫的陰影版本。

Maven

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

Gradle

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