本指南將概述如何自訂 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()
) 的 fluent 介面會同時載入所有 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'