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

คู่มือนี้จะอธิบายวิธีปรับแต่งแง่มุมขั้นสูงหลายๆ ด้านของไลบรารีของไคลเอ็นต์ 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() (หรือตัวเข้าถึงเฉพาะเวอร์ชัน เช่น getVersion26()) แต่ละครั้งจะสร้างการเชื่อมต่อพื้นฐานใหม่และทรัพยากรที่เกี่ยวข้อง

ตรวจสอบว่าคุณปิดไคลเอ็นต์บริการเมื่อไม่จำเป็นต้องใช้อีกต่อไป คุณสามารถทำได้ในบล็อก 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-48.1.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

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

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

หากโปรเจ็กต์ของคุณมีทรัพยากร 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>48.1.0</version>
</dependency>

Gradle

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