שימוש מתקדם

במדריך הזה מוסבר איך להתאים אישית כמה מההיבטים המתקדמים יותר של ספריית הלקוח של Java. דפוס נפוץ הוא שהרבה מהתכונות האלה מסתמכות על Callable הבסיס ולא על השיטות הסטנדרטיות. בדרך כלל, אפשר להשתמש בקריאה לתכונות אחרות לכל RPC, שלא מתועדות כאן.

חסימה זמנית

ספריית Java מספקת משטח להגדרת זמנים קצובים לתפוגת שיחה. ערך ברירת המחדל נקבע על סמך ההגדרה method_config/timeout ב-googleads_grpc_service_config.json. אם רוצים לאכוף מגבלה קצרה יותר על משך הזמן המקסימלי לקריאה ל-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)));
}

אפשר להגדיר את הזמן הקצוב לתפוגה של שעתיים או יותר, אבל ה-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 גדול מ-32MB

ב-App Engine יש מכסה של 32MB לכל קובץ שהועלה. ה-JAR של google-ads יהיה גדול משמעותית מזה, ועוד יותר באמצעות פריסות של צנצנות הצל והצלליות. אם תפרסו את הצנצנות באופן ידני, יכול להיות שתקבלו הודעות כמו:

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])

במקום זאת, צריך לפרוס את המדיניות באמצעות הפלאגין Gradle או Maven של AppEngine. לכל צנצנת יש אפשרות ל-enableJarSplitting, שתפצל כל צנצנת למקטעים של 10MB ותעלה אותם במקום זאת.

יחסי תלות עם אזורים כהים

אם בפרויקט יש יחסי תלות שמתנגשים עם יחסי התלות של הספרייה, צריך לבדוק את יחסי התלות של הפרויקט באמצעות אחת מהפקודות הבאות, ולשנות את יחסי התלות של הפרויקט לפי הצורך.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

אם אי אפשר לפתור את התנגשויות התלות, אפשר להשתמש במקום זאת בגרסה shaded של הספרייה.

Maven

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

Gradle

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