高级用法

本指南概述了如何自定义 Java 客户端库。一种常见的模式是，其中的许多特征依赖于 底层 Callable，而不是标准方法。Callable 为 通常非常适合查找未记录的其他每个 RPC 的功能 此处。

超时

Java 库提供了一个用于在每次调用级别设置超时的途径。 默认值是根据 method_config/timeout googleads_grpc_service_config.json. 如果您需要对最长时间限制较短，请设置一个较低的值 API 调用。

如需使用此功能，您应直接使用 Callable 对象。例如，如果 调用 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 库还提供了一个 Surface，用于在 。如需使用此功能，您应直接使用 Callable 对象。 例如，如果调用 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 连接。

您必须确保在不再需要客户端时将其关闭。这个 使用 Cloud Build try-with-resources 或在服务客户端上调用 close()。

如果您尝试使用关闭的服务客户端发出 API 请求， 客户端方法将抛出 java.util.concurrent.RejectedExecutionException。

如果 JAR 超过32 MB

对于上传的文件，App Engine 有 32 MB 的配额。google-ads 的 JAR 将远远大于此大小，甚至使用阴影/阴影 jar Deployment如果您手动部署 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 插件。 每个 jar 都有一个 enableJarSplitting 选项，可将每个 jar 拆分为 10 MB 的块， 请改为上传这些文件。

阴影依赖项

如果您的项目中的依赖项与库的依赖项冲突，您应该 使用以下命令之一检查项目的依赖项 根据需要修改项目的依赖项。

mvn dependency:tree

./gradlew dependencies

如果解决依赖项冲突不可行，您可以依赖 阴影 库版本

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

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