本頁面由 Cloud Translation API 翻譯而成。

進階用法

本指南將概述如何自訂 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 將大於這個值，甚至在使用陰影/陰影 jar 部署的情況下更大。如果手動部署 jar，則可能會看見下列錯誤：

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

請改用 AppEngine Gradle 外掛程式或 Maven 外掛程式進行部署。每個 enableJarSplitting 都有一個選項，可將每個 jar 分割為 10 MB 的區塊，並改為上傳這些區塊。

陰影依附元件

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

如果無法解決依附元件衝突，您可以改用程式庫的shaded版本。

Maven

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

Gradle

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