ניהול פעולות ממושכות

‫Cloud de Confiance by S3NS APIs משתמשים בפעולות ממושכות (LRO) לקריאות שצפויות להימשך זמן משמעותי (לדוגמה, הקצאת מכונה של Compute Engine או הפעלה של צינור Dataflow). ממשקי ה-API האלה לא שומרים על חיבור פעיל לטווח ארוך ולא חוסמים בזמן שהמשימה פועלת. בממשקי LRO API, ספריות הלקוח של Java ב-Cloud מחזירות future כדי שתוכלו לבדוק אותו מאוחר יותר.

איך קובעים אם API הוא LRO

יש שתי דרכים עיקריות לקבוע אם API הוא LRO:

• לממשקי LRO API יש סיומת של Async (לדוגמה, createClusterAsync) או OperationCallable (לדוגמה, createClusterOperationCallable).
• ממשקי API של LRO מחזירים OperationFuture או OperationCallable.

בקטע הקוד הבא מוצגים שני סוגי ההגדרות, באמצעות Java-Dataproc כדוגמה:

// Async suffix (#1) returns OperationFuture (#2)
public final OperationFuture<Cluster, ClusterOperationMetadata> createClusterAsync(CreateClusterRequest request)

// OperationCallable suffix (#1) returns OperationCallable (#2)
public final OperationCallable<CreateClusterRequest, Cluster, ClusterOperationMetadata> createClusterOperationCallable()

אלה שתי וריאציות של אותו API ולא שני ממשקי API שונים (שתי הקריאות יוצרות אשכול Managed Service for Apache Spark). מומלץ להשתמש בווריאנט Async.

תרשים זרימה ברמה גבוהה של פעולת LRO

ממשקי LRO API הם בעצם קריאה ראשונית לבקשה, שאחריה מתבצעת סדרה של קריאות קטנות לבדיקת סטטוס. השיחה הראשונית שולחת את הבקשה ויוצרת 'פעולה' בשרת. כל קריאות הסקר הבאות לשרת עוקבות אחרי הסטטוס של הפעולה. אם הפעולה הסתיימה, התגובה מוחזרת. אחרת, מוחזר סטטוס לא מלא וספריית הלקוח קובעת אם לבצע שוב שאילתת בדיקה.

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

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

ספריות הלקוח של Cloud Java מספקות ממשק לאינטראקציה עם LRO באמצעות OperationFuture.

בקטע הקוד הבא אפשר לראות איך מפעילים פעולה ומחכים לתגובה, באמצעות Java-Dataproc כדוגמה:

try (ClusterControllerClient clusterControllerClient = ClusterControllerClient.create()) {
  CreateClusterRequest request =
      CreateClusterRequest.newBuilder().build();
  OperationFuture<Cluster, ClusterOperationMetadata> future =
      clusterControllerClient.createClusterAsync(request);
  // Blocks until there is a response
  Cluster response = future.get();
} catch (CancellationException e) {
  // Exceeded the timeout without the Operation completing.
  // Library is no longer polling for the Operation's status.
}

ערכי ברירת מחדל של LRO

אפשר למצוא את ערכי ברירת המחדל בכיתה StubSettings של כל לקוח. המתודה initDefaults() מאתחלת את הגדרות ה-LRO בתוך המחלקה המוטמעת Builder.

לדוגמה, ב-Java-Aiplatform v3.24.0, לקריאת ה-LRO‏ deployModel יש את פרמטרי ברירת המחדל הבאים:

OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(5000L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(45000L))
    .setTotalTimeoutDuration(Duration.ofMillis(300000L))
    .setInitialRpcTimeoutDuration(Duration.ZERO) // not used
    .setRpcTimeoutMultiplier(1.0) // not used
    .setMaxRpcTimeoutDuration(Duration.ZERO) // not used
    .build()));

גם ניסיונות חוזרים וגם LRO משתמשים באותו מחלקה RetrySettings. בטבלה הבאה מוצג המיפוי בין השדות בתוך RetrySettings לבין הפונקציונליות של LRO:

מתי כדאי להגדיר ערכי LRO

תרחיש השימוש העיקרי בהגדרה ידנית של ערכי LRO הוא שינוי תדירויות הסקרים בגלל פסק זמן של LRO. ערכי ברירת המחדל מוגדרים כאומדן על ידי צוות השירות, אבל גורמים מסוימים עלולים לגרום לפסק זמן מדי פעם.

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

איך מגדירים ערכי LRO

כדי להגדיר את ערכי ה-LRO, יוצרים אובייקט OperationTimedPollAlgorithm ומעדכנים את אלגוריתם התשאול עבור LRO ספציפי. בקטע הקוד הבא נעשה שימוש ב-Java-Dataproc כדוגמה:

ClusterControllerSettings.Builder settingsBuilder = ClusterControllerSettings.newBuilder();
// Create a new OperationTimedPollAlgorithm object
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(500L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(5000L))
    .setTotalTimeoutDuration(Duration.ofHours(24L))
    .build());
// Set the new polling settings for the specific LRO API 
settingsBuilder.createClusterOperationSettings().setPollingAlgorithm(timedRetryAlgorithm);
ClusterControllerClient clusterControllerClient = ClusterControllerClient.create(settingsBuilder.build());

ההגדרה הזו משנה רק את ערכי ה-LRO של ה-RPC‏ createClusterOperation. שאר קריאות ה-RPC בלקוח עדיין משתמשות בערכי ה-LRO שהוגדרו מראש לכל קריאת RPC, אלא אם הן גם שונו.

פסקי זמן של LRO

הספרייה ממשיכה לשלוח בקשות כל עוד לא חלף הזמן הכולל שהוגדר להפסקת הפעולה. אם חלף הזמן הכולל שהוקצב, הספרייה תציג את השגיאה java.util.concurrent.CancellationException עם ההודעה 'המשימה בוטלה'.

CancellationException לא אומר שהמשימה Cloud de Confiance by S3NS בקצה העורפי בוטלה. החריגה הזו מופעלת מספריית הלקוח כשמשך הזמן הקצוב לתפוגה של קריאה מסוימת חלף ולא התקבלה תשובה. גם אם המשימה תושלם מיד אחרי פסק הזמן, ספריית הלקוח לא תראה את התגובה.