進階用法

本指南將概略說明如何自訂 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 類別，以便提供更方便的機制來建構服務類別。

如果第一個要求效能是應用程式的關鍵路徑，請按照下列步驟操作：

請在啟動時建立 GoogleAdsClient，再處理使用者要求。

在程序剛開始時，請向 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-34.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

請改用 App Engine Gradle 外掛程式或 Maven 外掛程式進行部署。每個檔案都有 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>34.0.0</version>
</dependency>

Gradle

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