שימוש ב-API – תובנות

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

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

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

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

gcloud config set project PROJECT_ID

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

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

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

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

where:

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

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

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

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

  • ‫INSIGHT_TYPE_ID הוא מזהה סוג התובנה המלא (לדוגמה, google.iam.policy.Insight).

בקטע סוגי תובנות מופיעה טבלה עם קישורים למידע על כל סוג תובנה, כולל מיקומים נתמכים ומזהים של סוגי תובנות.

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

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

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

תובנות לגבי רשימת המניות למעקב

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

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

gcloud Beta

כתבו:

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

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

לדוגמה:

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

gcloud

כתבו:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

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

לדוגמה:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --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}/insightTypes/${INSIGHT_TYPE}/insights"

לדוגמה:

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/insightTypes/google.iam.policy.Insight/insights"

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

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

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

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

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

    projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

    כאשר INSIGHT_ID הוא המזהה הייחודי של המדד.

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

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

סימון תובנה כמאושרת

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

כדי לסמן תובנה כמאושרת:

gcloud

כתבו:

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

where:

  • ‫INSIGHT_ID הוא המזהה של תובנה שאוחזרה מקריאה קודמת של רשימת התובנות
  • ‫etag הוא ה-etag שמוחזר ומייצג את מצב התובנה
  • ‫STATE_METADATA הם מטא-נתונים אופציונליים לגבי הפעולה. מציינים את המטא-נתונים כרשימה מופרדת בפסיקים של זוגות KEY=VALUE.

לדוגמה:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --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}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

where:

  • ‫INSIGHT_ID הוא המזהה של תובנה שאוחזרה מקריאה קודמת של רשימת התובנות
  • ‫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/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

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

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

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

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