סקירה כללית על Cloud Quotas API

באמצעות Cloud Quotas API אפשר לשנות באופן פרוגרמטי מכסות ברמת הפרויקט ולשלוח בקשות לשינוי מכסות ברמת הפרויקט באופן אוטומטי. לדוגמה, אפשר להשתמש ב-Cloud Quotas API כדי:

התאמות אוטומטיות של מכסות: אתם יכולים להשתמש ב-Cloud Quotas API כדי לבקש התאמות של מכסות על סמך קריטריונים משלכם. לדוגמה, כדי להימנע משגיאות של חריגה מהמכסה, אפשר להשתמש ב-API כדי לבקש באופן אוטומטי התאמה של המכסה כשמשאבי Compute Engine מגיעים ל-80% מהמכסה הזמינה.
שימוש חוזר בהגדרות מכסה בפרויקטים שונים: אפשר להשתמש ב-Cloud Quotas API כדי לשכפל את הגדרות המכסה מפרויקט לפרויקט. אם יש קבוצה ידועה של מכסות שצריך להגדיל בכל פרויקט חדש Google Cloud , אפשר להשתמש ב-Cloud Quotas API כדי לבצע את זה באופן אוטומטי בלוגיקה של יצירת הפרויקט. בקשות לשינוי מכסות כפופות Google Cloud לאישור.
טיפול בבקשות של לקוחות להגדלת מכסות: אם אתם ספקי SaaS שמשולבים עםGoogle Cloud, יכול להיות שתקבלו בקשות להגדלת מכסות דרך פורטל שפונה ללקוחות ולא דרך מסוף Google Cloud . הבקשות האלה צריכות להיות מועברות אל Google Cloud לעיבוד. ‫Cloud Quotas API יכול להעביר באופן אוטומטי בקשות של לקוחות.
הפעלת ניהול גרסאות של הגדרות לקוח: Cloud Quotas API הוא דקלרטיבי. אפשר להתייחס להגדרות של מכסות כמו לקוד, ולאחסן את ההגדרות במערכת לניהול גרסאות משלכם כדי לשמור את ההיסטוריה ולאפשר חזרה לגרסאות קודמות.

מגבלות

אלו המגבלות שחלות על מכסות ב-Cloud:

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

נקודת קצה של שירות

נקודת הקצה של השירות היא כתובת URL בסיסית שמציינת את כתובת הרשת של שירות API. יכול להיות שלשירות אחד יהיו כמה נקודות קצה. לשירות Cloud Quotas API יש את נקודת הקצה הבאה, וכל מזהי ה-URI הם יחסי אליה:

https://cloudquotas.googleapis.com

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לגישה למשאבים cloudquotas_quotaPreferences, cloudquotas_quotaInfos ו-cloudquotas_quotaAdjusterSettings, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד אדמין של מכסות ב-Cloud ‏ (cloudquotas.admin) בפרויקט. להסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד המוגדר מראש הזה מכיל את ההרשאות שנדרשות לגישה למשאבים cloudquotas_quotaPreferences, cloudquotas_quotaInfos ו-cloudquotas_quotaAdjusterSettings. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי לגשת למשאבים cloudquotas_quotaPreferences, cloudquotas_quotaInfos ו-cloudquotas_quotaAdjusterSettings, נדרשות ההרשאות הבאות:

cloudquotas.quotas.update
cloudquotas.quotas.get
monitoring.timeSeries.list
resourcemanager.projects.get
resourcemanager.projects.list

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

מודל משאבי API

מודל המשאבים של Cloud Quotas API מורכב משני משאבים: QuotaPreference ו-QuotaInfo.

העדפת מכסה

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

הגדרת ערך מועדף לאזור

בדוגמה הבאה מוצג משאב QuotaPreference בשיטה CreateQuotaPreference.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

הערך preferredValue של 100 מציין שמגיש הבקשה רוצה שהמכסה GPUS-PER-GPU-FAMILY-per-project-region יוגדר לערך הזה. שדה המימדים מציין שההעדפה חלה רק על אזור us-central1.

אימות הערך שהוענק

בודקים את העדפת המכסה ואת השדה grantedValue כדי לוודא את הערך שהוקצה.

כדי לראות את העדפת המכסה באמצעות Google Cloud CLI, מריצים את הפקודה הבאה במסוף:

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

מחליפים את מה שכתוב בשדות הבאים:

‫QUOTA_PREFERENCE_ID: המזהה של העדפת המכסה. זהו הערך שצוין כשנוצרה העדפת המכסה.
‫PROJECT: המזהה או המספר של הפרויקט ב- Google Cloud.

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

כדי לראות אם הערך שאושר הוא הערך הסופי, בודקים את השדה reconciling. אם הבקשה שלך עדיין בבדיקה, הערך של השדה reconciling הוא true. אם השדה reconciling מוגדר ל-false או מושמט, הערך שמאושר הוא הערך הסופי.

קטעי הקוד הבאים מציגים דוגמאות לאובייקט העדפת המכסה. הם משתמשים בהעדפה של מכסת הדגמה עם המזהה compute_googleapis_com-gpus-us-central1.

gcloud

אם מציגים את העדפת המכסה באמצעות ה-CLI של gcloud, הפלט נראה בערך כך:

createTime: '2023-01-15T01:30:15.01Z'
dimensions:
    region: us-central1
name: projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1
quotaConfig:
    grantedValue: '100'
    preferredValue: '100'
    traceId: 123acd-345df23
    requestOrigin: ORIGIN_UNSPECIFIED
service: compute.googleapis.com
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
updateTime: '2023-01-16T02:35:16.01Z'

REST

אם מציגים את העדפת המכסה באמצעות Cloud Quotas API, הפלט נראה בערך כך:

{
    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1",
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 100,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
    },
    "dimensions": {
        "region": "us-central1"
    },
    "createTime": "2023-01-15T01:30:15.01Z",
    "updateTime": "2023-01-16T02:35:16.01Z"
}

הפלט הזה כולל את הערכים הבאים:

‫PROJECT_NUMBER: מזהה ייחודי שנוצר באופן אוטומטי עבור הפרויקט.

התגובה מראה grantedValue של 100, כלומר preferredValue מהדוגמה הקודמת אושרה ובוצעה. העדפות לגבי מאפיינים שונים הן QuotaPreference משאבים שונים. לדוגמה, QuotaPreference למעבד באזורים us-central1 ו-us-east1 הם שני משאבים נפרדים.

חובה לציין העדפה לגבי מכסת השימוש

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

בקשות שהגשתם אל QuotaPreference.
בקשות להגדלת מכסות שאושרו על ידי Google Cloud.
שינויים במכסות שבוצעו על ידי Google Cloud.

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

מידע נוסף על משאב QuotaPreference זמין במאמר Cloud Quotas API Reference.

מידע נוסף על שאילתות QuotaPreference זמין במאמר יישום תרחישים נפוצים.

פרטי המכסה

‫QuotaInfo הוא משאב לקריאה בלבד שמספק מידע על מכסה מסוימת בפרויקט, בתיקייה או בארגון נתונים. מוצג בו מידע על המכסות שהוגדרו על ידי שירותי Google Cloud ועל כל שינוי במכסות שבוצע לבקשת לקוחות. המשאב QuotaInfo מכיל מידע כמו מטא-נתונים, סוג המאגר ומאפיינים.

הגדרת ערכי מכסה שונים לפי אזור

בדוגמה הבאה של משאב QuotaInfo אפשר לראות שמכסת המעבד (CPU) לפרויקט היא 200 באזור us-central1 ו-100 בכל האזורים האחרים.

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region",
    "quotaId": "CPUS-per-project-region",
    "metric": "compute.googleapis.com/cpus",
    "containerType": "PROJECT",
    "dimensions": [
        "region"
    ],
    "isPrecise": true,
    "quotaDisplayName": "CPUs per project per region",
    "metricDisplayName": "CPUs",
    "dimensionsInfo": [
        {
            "dimensions": {
                "region": "us-central1"
            },
            "details": {
                "quotaValue": 200,
                "resetValue": 200
            },
            "applicableLocations": [
                "us-central1",
            ]
        },
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 100
            },
            "applicableLocations": [
                "us-central2",
                "us-west1",
                "us-east1"
            ]
        }
    ]
}

הפלט הזה כולל את הערכים הבאים:

‫PROJECT_NUMBER: מזהה ייחודי שנוצר באופן אוטומטי עבור הפרויקט.

הגדרת מכסת נפח גלובלית

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

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject",
    "quotaId": "ReadRequestsPerMinutePerProject",
    "metric": "compute.googleapis.com/read_requests",
    "refreshInterval": "minute",
    "containerType": "PROJECT",
    "dimensions": [],
    "isPrecise": false,
    "quotaDisplayName": "Read Requests per Minute",
    "metricDisplayName": "Read Requests",
    "dimensionsInfo": [
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 200
            },
            "applicableLocations": [
                "global"
            ]
        }
    ]
}

הפלט הזה כולל את הערכים הבאים:

‫PROJECT_NUMBER: מזהה ייחודי שנוצר באופן אוטומטי עבור הפרויקט.

פרטים נוספים על משאב QuotaInfo זמינים במאמר בנושא Cloud Quotas API Reference.

פרטים נוספים על שאילתות QuotaPreference זמינים במאמר הטמעה של תרחישי שימוש נפוצים.

הגדרות של כלי ההתאמה של המכסה

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

כדי לראות את ההגדרות הנוכחיות של הכוונון של המכסה בפרויקט, משתמשים בפעולת GET כדי לאחזר את המשאב QuotaAdjusterSettings.
כדי להפעיל את הכלי לשינוי מכסות בפרויקט, משתמשים בפעולת PATCH כדי להגדיר את אפשרויות המשאב QuotaAdjusterSettings הבאות:
```
  "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}
```
מחליפים את PROJECT_NUMBER במזהה הייחודי של הפרויקט.

פרטים נוספים זמינים במאמרים הפעלת הכלי לשינוי המכסות והשבתת הכלי לשינוי המכסות.

שמות המשאבים

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

משאב העדפת המכסה

המוסכמה למתן שמות למשאב QuotaPreference היא לפי הדפוס הבא:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

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

לדוגמה, quotaPreferenceאחת מהתבניות לקידוד מזהה העדפת המכסה היא:

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

הדוגמה הבאה ממחישה את התבנית הזו:

compute_us-central1_nvidia-200

השדה location בשם משאב הוא תמיד global. ‫Cloud Quotas API הוא שירות גלובלי.

כדי לאחזר QuotaPreference באמצעות שם משאב, צריך להשתמש בשיטה GET. אפשר גם להפעיל את השיטה PATCH עם האפשרות allow_missing כדי ליצור או לעדכן QuotaPreference.

מקור מידע על מכסה

המוסכמה למתן שמות למשאב QuotaInfo היא לפי הדפוס הבא:

projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID

‫Quota adjuster settings resource

המוסכמה למתן שמות למשאב QuotaAdjusterSettings היא לפי הדפוס הבא:

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

סקירה כללית על Cloud Quotas API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מגבלות

נקודת קצה של שירות

התפקידים הנדרשים

ההרשאות הנדרשות

מודל משאבי API

העדפת מכסה

הגדרת ערך מועדף לאזור

אימות הערך שהוענק

gcloud

REST

חובה לציין העדפה לגבי מכסת השימוש

פרטי המכסה

הגדרת ערכי מכסה שונים לפי אזור

הגדרת מכסת נפח גלובלית

הגדרות של כלי ההתאמה של המכסה

שמות המשאבים

משאב העדפת המכסה

מקור מידע על מכסה

‫Quota adjuster settings resource

מה השלב הבא?

סקירה כללית על Cloud Quotas API