יצירת מלצר

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

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

לפני שמתחילים

יצירת מלצר

כדי ליצור רכיב waiter:

  1. קובעים את תנאי ההצלחה, ואם רוצים, גם את תנאי הכישלון של ה-waiter.

    לדוגמה, בקוד לדוגמה הבא מוגדרים התנאים להצלחה ולכישלון, כך שהפעולה ממתינה להחזרת ערך אם מספר הנתיבים מתחת ל-/status/success הוא שלוש, ונכשלת אם הנתיב מתחת ל-/status/failure הוא שתיים:

    {
    'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]',
    'timeout': '360s',
    'success': {
       'cardinality': {
          'path': '/status/success',
          'number': 3
       }
    },
    'failure': {
       'cardinality': {
          'path': '/status/failure',
          'number': 2
       }
     }
}

    שיטות מומלצות להגדרת רכיב waiter:

    • לכל רכיב waiter יכולה להיות רק תנאי הצלחה אחד ותנאי כישלון אחד.
    • מומלץ להשתמש באובייקט Waiter אחד לכל נתיב.
    • תנאי הכשל תמיד נבדקים לפני תנאי ההצלחה.
    • אל תשתמשו בתחיליות נתיב חופפות בין תנאים.

  2. יוצרים את המלצר.

    Deployment Manager

    כדי ליצור רכיב waiter ב-Deployment Manager, מציינים את סוג ה-waiter:

    runtimeconfig.v1beta1.waiter

    במאפיינים של רכיב ההמתנה, מציינים את name, את location, את timeout ואת תנאי הסיום של רכיב ההמתנה:

    - name: [NAME]
  type: runtimeconfig.v1beta1.waiter
  properties:
    parent: $(ref.[CONFIG_NAME].name)
    waiter: [WAITER_NAME]
    timeout: [TIMEOUT_SECS]
    success:
      cardinality:
        path: [SUCCESS_PATH_PREFIX]
        number: [SUCCESS_NUMBER]

    where:

    • ‫[NAME] הוא שם המשאב.
    • ‫[CONFIG_NAME] הוא משאב ההגדרות של הבקשה הזו.
    • ‫[WAITER_NAME] הוא השם של ה-waiter.
    • ‫[TIMEOUT_SECS] הוא מספר השניות להמתנה לפני שפג הזמן הקצוב לתהליך ההמתנה. לדוגמה, כדי להגדיר 300 שניות, משתמשים ב-300s.
    • ‫[SUCCESS_PATH_PREFIX] היא תחילית הנתיב שצריך לעקוב אחריה כדי לזהות תנאי של הצלחה.
    • ‫[SUCCESS_NUMBER] הוא מספר המשתנים שקיימים בנתיב הזה ונחשבים כמשתנים מוצלחים.

    gcloud

    באמצעות Google Cloud CLI:

    gcloud beta runtime-config configs waiters create [WAITER_NAME] \
    --config-name [CONFIG_NAME] \
    --success-cardinality-path [SUCCESS_PATH_PREFIX] \
    --success-cardinality-number [SUCCESS_NUMBER] --timeout [TIMEOUT_SECS]

    where:

    • ‫[WAITER_NAME] הוא השם של ה-waiter.
    • ‫[CONFIG_NAME] הוא משאב RuntimeConfig של הבקשה הזו.
    • ‫[SUCCESS_PATH_PREFIX] היא התחילית של הנתיב שצריך לעקוב אחריו כדי לזהות תנאי של הצלחה.
    • ‫[SUCCESS_NUMBER] הוא מספר המשתנים שקיימים בנתיב הזה ונחשבים כמשתנים מוצלחים.

    • [TIMEOUT_SECS] מספר השניות להמתנה לפני שההמתנה תסתיים.

      ה-CLI של gcloud מחזיר תשובה כמו:

      נוצר [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/example-waiter].

      אחרי שיוצרים את ה-waiter, הכלי שולח שאילתות למשאב Operations שקשור אליו עד שה-waiter מחזיר אחת מהתגובות הרלוונטיות.

      למידע נוסף על הפקודה gcloud, תוכלו לקרוא את מאמרי העזרה של runtime-config configs waiters.

    API

    ב-API, שולחים בקשת POST ל-URI הבא:

    https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters

    where:

    • ‫[PROJECT_ID] הוא מזהה הפרויקט של הבקשה הזו.
    • ‫[CONFIG_NAME] הוא שם ההגדרה של הבקשה הזו.

    מטען הייעודי (payload) של הבקשה צריך לכלול את שם הממתין, את תנאי ההצלחה ואת משך הזמן הקצוב לתפוגה:

    {
 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]',
 'timeout': '[TIMEOUT_SEC]',
 'success': {
    'cardinality': {
       'path': '[SUCCESS_PATH_PREFIX]',
       'number': '[SUCCESS_NUMBER]'
    }
  }
}

    where:

    • ‫[PROJECT_ID] הוא מזהה הפרויקט של הבקשה הזו.
    • ‫[CONFIG_NAME] הוא שם ההגדרה של הבקשה הזו.
    • ‫[WAITER_NAME] הוא שם ה-waiter שרוצים ליצור.
    • [TIMEOUT_SECS] מספר השניות להמתנה לפני שפסק הזמן של הממתין יפוג.
    • ‫[SUCCESS_PATH_PREFIX] היא תחילית הנתיב שצריך לעקוב אחריה כדי לזהות תנאי של הצלחה.
    • ‫[SUCCESS_NUMBER] הוא מספר המשתנים שקיימים בנתיב הזה ונחשבים כמשתנים מוצלחים.

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

    {
    "name": "projects/[PROJECT_ID]/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

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

    מידע נוסף על השיטה זמין במאמרי העזרה בנושא waiters().create.

איך קוראים למלצר

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

משתמשים ב-gcloud או ב-API כדי לדגום את ה-waiter.

gcloud

כשמשתמשים ב-Google Cloud CLI כדי לשלוח בקשה ליצירת waiter, הכלי מבצע באופן אוטומטי בדיקות חוזרות וממתין עד שה-waiter יחזיר תשובה. הכלי מדפיס תגובה כמו זו שבהמשך בזמן שהוא שולח בקשות ל-waiter:

Waiting for waiter [WAITER_NAME] to finish...

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

API

ב-API בארכיטקטורת REST, שולחים בקשת GET ל-URI הבא כדי לקבל את הסטטוס של פעולת ההמתנה:

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]

where:

  • ‫[PROJECT_ID] הוא מזהה הפרויקט של הבקשה הזו.
  • ‫[CONFIG_NAME] הוא שם ההגדרה של הבקשה הזו.
  • ‫[WAITER_NAME] הוא שם ה-waiter שצריך לבצע עליו סקר.

אם הפעולה עדיין מתבצעת, ה-API מחזיר תגובה כמו בדוגמה הבאה, בלי סטטוס:

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

אם הפעולה הושלמה, היא מסומנת כ-done ומוחזרת אחת מהתגובות שמתוארות בקטע תגובות של Waiter.

מידע נוסף על השיטה זמין במאמרי העזרה בנושא waiters().create.

תשובות של מלצרים

תנאי סיום מוצלח

אם הממתין עמד בתנאי הסיום המוצלח, הפעולה מחזירה את משאב הממתין:

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.runtimeconfig.v1beta1.Waiter",
    "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]",
    "timeout": "360.000s",
    "failure": {
      "cardinality": {
        "path": "[SUCCESS_PATH_PREFIX]",
        "number": "[SUCCESS_NUMBER]"
      }
    },
    "success": {
      "cardinality": {
        "path": "[FAILURE_PATH_PREFIX]",
        "number": [FAILURE_NUMBER]
      }
    },
    "createTime": "2016-04-12T18:02:13.316695490Z",
    "done": true
  }
}

תנאי כשל

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

התנאי לכישלון התקיים

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 9,
    "message": "Failure condition satisfied."
  }
}

פג הזמן הקצוב של ה-Waiter

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 4,
    "message": "Timeout expired."
  }
}

המאמרים הבאים