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

‫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).
• ממשקי LRO API מחזירים 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 הבאות לשרת עוקבות אחרי הסטטוס של הפעולה. אם הפעולה הסתיימה, התגובה מוחזרת. אחרת, מוחזר סטטוס לא הושלם וספריית הלקוח קובעת אם לבצע שוב שאילתת סטטוס.

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

מנקודת המבט שלכם, השיחה מתנהלת ברקע עד לקבלת תשובה. לקריאות ה-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()));

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

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

תרחיש השימוש העיקרי להגדרה ידנית של ערכי LRO הוא שינוי תדירות השליפה (polling) בגלל פסק זמן של 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 עם ההודעה Task was cancelled (המשימה בוטלה).

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