การใช้งานขั้นสูง

คู่มือนี้อธิบายวิธีปรับแต่งแง่มุมขั้นสูงบางอย่างของไลบรารีของไคลเอ็นต์ 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 =
      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. ส่งคำขอวอร์มอัพ 2-3 รายการไปยัง 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

App Engine จะติดตั้งใช้งานไม่สำเร็จหาก JAR มีขนาดมากกว่า 32 MB

App Engine มีโควต้า 32 MB สำหรับไฟล์ที่อัปโหลดแต่ละไฟล์ JAR สำหรับ google-ads มีขนาดใหญ่กว่านี้มาก โดยเฉพาะเมื่อใช้การติดตั้งใช้งาน JAR แบบ Shade หรือ Shadow หากคุณติดตั้งใช้งาน 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])

แต่ให้ใช้การติดตั้งใช้งานโดยใช้ปลั๊กอิน Gradle หรือปลั๊กอิน Maven ของ App Engine แทน ปลั๊กอินแต่ละตัวมีenableJarSplitting ตัวเลือกที่แยกแต่ละ JAR ออกเป็น 10 MB และอัปโหลดแทน

ทรัพยากร Dependency ของ Shadow

หากโปรเจ็กต์มี Dependency ที่ขัดแย้งกับ Dependency ของไลบรารี ให้ตรวจสอบลำดับชั้นของ Dependency ของโปรเจ็กต์โดยใช้คำสั่งใดคำสั่งหนึ่งต่อไปนี้ จากนั้นแก้ไข Dependency ของโปรเจ็กต์ตามที่จำเป็น (หรือใช้Bill of Materials)

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

หากแก้ไขความขัดแย้งของทรัพยากร Dependency ไม่ได้ คุณสามารถใช้ไลบรารีเวอร์ชันที่ซ่อนแทนได้

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'