שימוש מתקדם

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

חסימה זמנית

ספריית 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 > 32 MB

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

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

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

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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