שימוש מתקדם

במדריך הזה מוסבר איך להתאים אישית כמה מהמאפיינים המתקדמים יותר של ספריית הלקוח של Java. דפוס נפוץ הוא שרבות מהתכונות האלה מסתמכות על Callable הבסיסי במקום על השיטות הרגילות. בדרך כלל, ה-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)));
}

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

פריסת App Engine נכשלת אם קובץ ה-JAR גדול מ-32MB

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

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-36.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

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

יחסי תלות בצל

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

MavenGradle

mvn dependency:tree

./gradlew dependencies

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

MavenGradle

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

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