שימוש מתקדם

במדריך הזה מוסבר איך להתאים אישית כמה מההיבטים המתקדמים יותר של ספריית הלקוח של 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. לכל אחת מהן יש אפשרות של enableJarSplitting, שתפצל כל צנצנת למקטעים של 10MB ותעלו אותם במקום זאת.

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

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

mvn dependency:tree

./gradlew dependencies

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

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

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