שימוש ב-API – המלצות

בדף הזה מוסבר איך להציג ולנהל המלצות ב-Recommender באמצעות פקודות gcloud או REST API.

אינטראקציה אופיינית עם Recommender API:

  1. הצגת רשימת ההמלצות לפרויקט ספציפי.

  2. מסמנים המלצה שמתכוונים ליישם באמצעות הסמל claimed, או מסמנים המלצה שלא מתכוונים ליישם באמצעות הסמל dismissed.

  3. מיישמים את ההמלצה. אפשר לעשות את זה באופן אוטומטי באמצעות Active Assist במסוף Google Cloud , או באופן ידני באמצעות פקודות Google Cloud CLI, קריאות ל-API בארכיטקטורת REST או כלים אחרים.

    כשמיישמים את ההמלצה באופן ידני, הפקודות או הקריאות שבהן משתמשים הן ספציפיות לסוג המשאב. לדוגמה, כדי לשנות את הגודל של מכונת VM בתגובה להמלצה של שירות ההמלצות על גודל מכונת VM, משתמשים בפקודות gcloud של Compute Engine או בקריאות ל-API בארכיטקטורת REST של Compute Engine.

    כשמבצעים את הפעולות האלה, מזהים את משאב היעד באמצעות הערך של השדה resource במערך OperationsGroup בישות Recommendation שמוחזרת. השדה הזה הוא בפורמט הבא:

    //API_NAME/RESOURCE_PATH

    לדוגמה:

    //compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1

  4. מסמנים את ההמלצה כsucceeded או כfailed.

חשוב לזכור שאפשר לבצע פעולות רק בהמלצות שאוחזרו באמצעות ה-API, באמצעות ה-API או BigQuery Export.

במאמרי העזרה בנושא Active Assist או בנושא שירות ההמלצות הרלוונטי מוסבר איך לשנות את הסטטוס של ההמלצות במסוףGoogle Cloud .

הגדרת פרויקט ברירת מחדל

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

gcloud config set project PROJECT_ID

כאשר PROJECT_ID הוא מזהה הפרויקט.

הגדרה של משתני סביבה

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

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

where:

  • ‫TARGET_PROJECT_ID הוא הפרויקט שרוצים להציג את ההמלצות לגביו. זה יכול להיות פרויקט שונה מהפרויקט הנוכחי.

    • בפקודות gcloud, צריך להשתמש במזהה הפרויקט
    • בבקשות API, אפשר להשתמש במספר הפרויקט או במזהה הפרויקט. מומלץ להזין מספר פרויקט.

    מספר הפרויקט מוחזר בתשובות גם מה-API וגם מפקודות gcloud.

  • ‫LOCATION_ID הוא Google Cloud המיקום שבו נמצאים המשאבים שמשויכים להמלצות (לדוגמה, global או us-central1-a).

  • ‫RECOMMENDER_ID הוא מזהה שירות ההמלצות המוגדר במלואו (לדוגמה, google.compute.instance.MachineTypeRecommender).

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

הגדרת ההרשאות

צריכות להיות לכם הרשאות גישה להמלצות בפרויקט היעד.

  • מגישי בקשות שכוללים פרויקט לחיוב בבקשה שלהם. הפרויקט שצוין בבקשה צריך להיות בניהול תקין, ולמשתמש צריך להיות תפקיד בפרויקט שכולל את ההרשאה serviceusage.services.use. התפקיד Service Usage Consumer כולל את ההרשאה הנדרשת.
  • לכל כלי להמלצות נדרשות הרשאות ספציפיות. בקטע שירותי המלצות יש טבלה עם קישורים למידע על כל שירות המלצות, כולל ההרשאות הנדרשות.

המלצות לרשימות

כפי שמוצג בכרטיסייה gcloud Beta, אפשר לראות רשימה של כל ההמלצות לפרויקט בלי לציין מיקום או כלי להמלצות. התכונה הזו נמצאת בגרסת טרום-השקה (Preview).

כדי להשתמש בתכונה של GA, צריך לציין פרויקט, מיקום ומערכת המלצות. פרטים נוספים זמינים בכרטיסייה gcloud.

gcloud Beta

כתבו:

gcloud beta recommender recommendations list \
    --project=${PROJECT} \
    --format=FORMAT

כאשר FORMAT הוא פורמט פלט נתמך של gcloud, כמו json.

לדוגמה:

‫
gcloud beta recommender recommendations list \
    --project=example-project \
    --format=json

gcloud

כתבו:

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

כאשר FORMAT הוא gcloud פורמט פלט נתמך (לדוגמה, json).

לדוגמה:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --format=json

REST

כתבו:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations"

לדוגמה:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

הפעולה הזו מחזירה את ההמלצות הנוכחיות לגבי גודל המכונה הווירטואלית בפרויקט היעד כרשימה של ישויות Recommendation בפורמט שצוין.

הפלט אמור להיראות כך:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "test",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "valueMatcher": {
                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"
              }
            },
            {
              "action": "replace",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "value": "zones/us-central1-a/machineTypes/custom-2-5120"
            }
          ]
        }
      ]
    },
    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
    "etag": "\"280b34810bba8a1a\"",
    "lastRefreshTime": "2019-06-28T06:49:21Z",
    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "primaryImpact": { ... },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "recommenderSubtype": "CHANGE_MACHINE_TYPE"
  }
]

שימו לב שההמלצות שמוחזרות כוללות את השדות הבאים:

  • השדה name בפורמט הבא:

    projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

    כאשר RECOMMENDATION_ID הוא המזהה הייחודי של ההמלצה

  • שדה etag שמשויך למצב הנוכחי של ההמלצה.

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

שינוי המצב של המלצה

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

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

אחרי שמיישמים המלצה, אפשר לסמן אותה כהצלחה או ככישלון.

כדי לשנות את הסטטוס של המלצה:

gcloud

כתבו:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=ETAG \
    --state-metadata=STATE_METADATA \
    --format=FORMAT

כאשר:

  • ‫STATE_CHANGE הוא השינוי שרוצים לבצע בהמלצה. הערכים התקינים הם:
    • mark-claimed כדי לסמן את ההמלצה כהמלצה שיושמה.
    • mark-dismissed כדי לסמן שההמלצה נדחתה.
    • mark-succeeded כדי לסמן שההמלצה יושמה בהצלחה.
    • ‫mark-failed כדי לסמן שההמלצה נכשלה.
  • ‫RECOMMENDATION_ID הוא מזהה של המלצה שאוחזרה מקריאה קודמת לפונקציה list recommendations.
  • ‫ETAG הוא ה-etag שמוחזר ומייצג את מצב ההמלצה
  • ‫STATE_METADATA הם מטא-נתונים אופציונליים לגבי הפעולה. מציינים את המטא-נתונים כרשימה מופרדת בפסיקים של זוגות KEY=VALUE. האפשרות הזו זמינה כשמסמנים שהמלצה מסוימת בוצעה, הצליחה או נכשלה.

לדוגמה:

gcloud recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --state-metadata=priority=high,tracking_number=12345 \
    --format=json

REST

מזינים את הפרטים הבאים

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "ETAG"
  "stateMetadata": STATE_METADATA
}
EOM

where:

  • ‫RECOMMENDATION_ID הוא מזהה של המלצה שאוחזרה מקריאה קודמת לפונקציה list recommendations.
  • ‫STATE_CHANGE הוא השינוי שרוצים לבצע בהמלצה. הערכים התקינים הם:
    • markClaimed כדי לסמן את ההמלצה כהמלצה שיושמה.
    • markDismissed כדי לסמן שההמלצה נדחתה.
    • markSucceeded כדי לסמן שההמלצה יושמה בהצלחה.
    • ‫markFailed כדי לסמן שההמלצה נכשלה.
  • ‫ETAG הוא ה-etag שמוחזר ומייצג את מצב ההמלצה
  • ‫STATE_METADATA הוא שדה אופציונלי עם מטא-נתונים נוספים על הפעולה. מציינים את המטא-נתונים כזוגות key:value. השדה הזה זמין כשמסמנים המלצה כהמלצה שיושמה, הצליחה או נכשלה.

לדוגמה:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

הפעולה הזו מחזירה את היישות Recommendation בפורמט שצוין אחרי שהפעולה בוצעה.

הפלט אמור להיראות כך:

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e053c\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

שימו לב שהערך של השדה state השתנה ל-SUCCEEDED.