高级用法

本指南概述了如何自定义 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 类,以便提供更便捷的机制来构建服务类。

如果首次请求性能对您的应用至关重要,您应按以下步骤操作:

  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 连接。

您必须确保在不再需要客户端时将其关闭。这可以在 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-39.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

如果无法解决依赖项冲突,您可以改为依赖库的阴影版本。

Maven

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

Gradle

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