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

คู่มือนี้สรุปวิธีปรับแต่งลักษณะขั้นสูงบางอย่างของไลบรารีของไคลเอ็นต์ 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.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

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

ทรัพยากร Dependency แบบ Shadow

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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