進階用法

本指南將說明如何自訂 Java 用戶端程式庫的幾項進階功能。常見模式是，許多這類功能都依附於基礎 Callable，而非標準便利方法。一般來說，可呼叫的函式是尋找其他未在此處記錄的 RPC 功能的好地方。

逾時

Java 程式庫提供介面，可針對每個呼叫設定逾時。預設值是根據 googleads_grpc_service_config.json 中的 method_config/timeout 設定而定。如要強制縮短 API 呼叫的最長時間限制，請設定較低的值。

如要使用這項功能，請直接呼叫 Callable 物件。舉例來說，呼叫 GoogleAdsService.searchStream() 時，請按照下列方式設定逾時：

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

您可以將逾時時間設為 2 小時以上，但 API 仍可能對執行時間極長的要求逾時，並傳回 DEADLINE_EXCEEDED 錯誤。如果發生這個問題，通常最好將查詢分割，並平行執行這些區塊；這樣可避免長時間執行的要求失敗，且只能從頭再次觸發要求才能復原的情況。

重試設定

Java 程式庫也提供介面，可設定每個呼叫層級的重試設定。如要使用這項功能，請直接呼叫 Callable 物件。舉例來說，呼叫 GoogleAdsService.searchStream() 時，請依下列方式設定重試設定：

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

啟動時間效能最佳化

第一次建立 GoogleAdsClient 執行個體時，您可能會注意到有短暫延遲。這是因為服務的流暢介面 (GoogleAdsClient.getLatestVersion()) 會一次載入 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 (ApiException ex) {
      // Do nothing, we're expecting this to fail.
    }
  }
}

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

重複使用服務用戶端

在實務上，您應盡量重複使用服務用戶端例項，因為每次呼叫 GoogleAdsClient.getLatestVersion().createYYYServiceClient() (或 getVersion25() 等特定版本的存取子)，都會建立新的基礎連線和相關聯的資源。

請務必在不再需要服務用戶端時關閉。您可以在 try-with-resources 區塊中執行這項操作，也可以在服務用戶端上呼叫 close()。

如果您嘗試使用已關閉的服務用戶端提出 API 要求，服務用戶端方法會擲回 java.util.concurrent.RejectedExecutionException。

如果 JAR 大於 32 MB，App Engine 就無法部署

App Engine 為每個上傳的檔案設定 32 MB 的配額。JAR 的大小遠大於此，尤其是在使用陰影或陰影 JAR 部署時。google-ads 如果您手動部署 JAR，可能會收到下列錯誤訊息：

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-46.1.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>46.1.0</version>
</dependency>

Gradle

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