שימוש ב-Cloud Billing Budget API

במאמר הזה מוסבר איך שולחים כמה בקשות פשוטות ל-Cloud Billing Budget API.

לרשימה המלאה של רכיבי ה-method, כדאי לעיין בחומרי העזר של API ל-REST או RPC API.

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

לפני שתקראו את המדריך הזה, אתם צריכים:

1. לקרוא את המאמר סקירה כללית של Cloud Billing Budget API.
2. לקרוא את המאמר הדרישות המוקדמות ל-Cloud Billing Budget API.
3. לבצע את השלבים להגדרה.

זיהוי של מזהה החשבון לחיוב ב-Cloud

בכל שליחת קריאה ל-Cloud Billing Budget API צריך את מזהה החשבון לחיוב ב-Cloud:

1. נכנסים לדף Manage billing accounts במסוף .
2. בכרטיסייה My billing accounts תוצג רשימה של חשבונות לחיוב ב-Cloud, לפי שם ומזהה. מאתרים את מזהה החשבון לחיוב של החשבון שבו ינוהלו התקציבים.

מושגי מפתח בנושא תקציב

• אפשר להגדיר תקציב לכל החשבון לחיוב או להיקף מסוים (מסונן) באמצעות אפשרויות סינון פרטניות, אם רוצים להשתמש בתקציב כדי לעקוב רק אחרי חלקים ספציפיים מהעלויות.
• תקציב שמוגדר לכל החשבון לחיוב ב-Cloud כולל את העלויות מכל הפרויקטים ב-Google Cloud שהתשלום עליהם מתבצע באמצעות החשבון הזה לחיוב.
• אם יש לכם גישה מוגבלת לחשבון לחיוב ב-Cloud או שאין לכם גישה בכלל, אתם יכולים ליצור תקציבים ברמת הפרויקט רק לפרויקטים שבבעלותכם. באמצעות השדה OwnershipScope בתקציב, משתמשים עם גישה מלאה לחשבון לחיוב ב-Cloud יכולים ליצור תקציבים לפרויקטים ספציפיים שמשתמשים אחרים עם גישה רק ברמת הפרויקט לא יכולים לשנות.
• אתם יכולים לצמצם את היקף התקציב באמצעות מסננים, למשל, קבוצת משנה של ארגונים, תיקיות, פרויקטים, שירותים ומסנני תקציב אחרים שרלוונטיים לחשבון לחיוב ב-Cloud.
• אתם יכולים להגדיר את תקופת התקציב. כברירת מחדל, התקציב עוקב אחרי העלויות שנצברות במהלך החודש הקלנדרי. בעזרת המסנן usage_period ב-Cloud Billing Budget API, אתם יכולים להגדיר לתקציב תקופה מסוג CalendarPeriod או מסוג CustomPeriod. כך תוכלו ליצור תקציבים ולעקוב אחרי מסגרות זמן מעבר לחודש הקלנדרי שמוגדר כברירת מחדל, כמו רבעון, שנה או טווח תאריכים בהתאמה אישית.
• אתם יכולים להגדיר את סכום התקציב לסכום ספציפי, או לקבוע שהוא יתבסס על ההוצאה בתקופה הקלנדרית הקודמת.
• אתם יכולים להגדיר כללים לסף התקציב לקבלת התראות באימייל. כשהעלויות (שצברתם בפועל או העלויות החזויות) גבוהות מאחוז מסוים מהתקציב (על סמך הכללים שהגדרתם), המערכת תשלח התראות באימייל לנמענים שציינתם.
• בכללי ההתראות של התקציב, אתם יכולים לבחור מי יקבל באימייל את ההתראות ולהפעיל התראות פרוגרמטיות באמצעות Pub/Sub.
• תוכלו להשתמש בנושאי Pub/Sub להתראות פרוגרמטיות (למשל, כדי להגדיר העברה אוטומטית של התראות לגבי התקציב לאמצעי תקשורת אחרים כמו Slack, או כדי להגדיר יצירה אוטומטית של משימות לניהול העלויות).

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

קריאה ל-API

הדוגמאות הבאות ממחישות איך לשלוח בקשות פשוטות ל-Cloud Billing Budget API.

הצגה של רשימת התקציבים

רכיב ה-method הזה של ממשק ה-API מפרט את כל התקציבים שזמינים בחשבון לחיוב ב-Cloud.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫billing-account-id: מספר החשבון לחיוב ב-Cloud שהתקציב חל עליו.
• ‫project-id: הפרויקט ב- Google Cloud שבו פועל Cloud Billing Budget API.

שיטת ה-HTTP וכתובת ה-URL:

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "budgets": [
   {
      "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
      "displayName": "Forecasted spend budget with Service Filter",
      "budgetFilter": {
        "projects": [
          "projects/123456789"
        ],
        "services": [
          "services/A1E8-BE35-7EBC"
        ],
        "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
        "calendarPeriod": "MONTH"
      },
      "amount": {
        "lastPeriodAmount": {}
      },
      "thresholdRules": [
        {
          "thresholdPercent": 0.9,
          "spendBasis": "FORECASTED_SPEND"
        }
      ],
      "allUpdatesRule": {},
      "etag": "c9d6c011f6fa6b5c"
    }
  ]
}

קבלת פרטי תקציב

רכיב ה-method הזה של ממשק ה-API מציג את הפרטים של תקציב מסוים.

REST

כדי לקרוא לשיטה הזו אתם צריכים את המזהה budget-id של התקציב שאתם רוצים לעדכן. אתם יכולים לקבל את מזהה התקציב מהפלט createBudget שנוצר כשיוצרים את התקציב, או מהפלט listBudgets שנוצר כשמציגים את רשימת כל התקציבים.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫billing-account-id: מספר החשבון לחיוב ב-Cloud שעליו חל התקציב הזה.
• ‫budget-id: המזהה של התקציב שאתם רוצים להציג.
• ‫project-id: הפרויקט ב- Google Cloud שבו פועל Cloud Billing Budget API.

שיטת ה-HTTP וכתובת ה-URL:

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Forecasted spend budget with Service Filter",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/A1E8-BE35-7EBC"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.9,
      "spendBasis": "FORECASTED_SPEND"
    }
  ],
  "allUpdatesRule": {},
  "etag": "c9d6c011f6fa6b5c"
}

יצירת תקציב

באמצעות ה-method הזה ב-API אפשר ליצור תקציב לחיוב ב-Cloud שיחול על החשבון לחיוב ב-Cloud שצוין.

REST

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫‎projects/budget-scope-project-id‎: מזהה הפרויקט ב- Google Cloud שאותו רוצים להגדיר בתור היקף התקציב (budgetFilter).
• ‫billing-account-id: מספר החשבון לחיוב ב-Cloud שעליו חל התקציב הזה.
• ‫api-user-project-id: הפרויקט ב- Google Cloud שבו פועל Cloud Billing Budget API.

שיטת ה-HTTP וכתובת ה-URL:

POST https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

תוכן בקשת JSON:

{
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

עדכון תקציב

אתם יכולים להשתמש ב-method הזה ב-API כדי לעדכן תקציב קיים לחיוב ב-Cloud, ולשנות את סכום התקציב, את מסנני התקציב (היקף התקציב), את תקופת התקציב או את כללי הסף.

REST

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

כדי לקרוא לשיטה הזו אתם צריכים את המזהה budget-id של התקציב שאתם רוצים לעדכן. אתם יכולים לקבל את מזהה התקציב מהפלט createBudget שנוצר כשיוצרים את התקציב, או מהפלט listBudgets שנוצר כשמציגים את רשימת כל התקציבים.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫‎projects/budget-scope-project-id‎: מזהה הפרויקט ב- Google Cloud שאותו רוצים להגדיר בתור היקף התקציב (budgetFilter).
• ‫billing-account-id: מספר החשבון לחיוב ב-Cloud שעליו חל התקציב הזה.
• ‫budget-id: המזהה של התקציב שאתם רוצים לעדכן.
• ‫api-user-project-id: הפרויקט ב- Google Cloud שבו פועל Cloud Billing Budget API.

שיטת ה-HTTP וכתובת ה-URL:

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

תוכן בקשת JSON:

{
  "budget": {
    "displayName": "My fancy budget",
    "budgetFilter": {
      "projects": [
        "projects/budget-scope-project-id"
      ],
      "calendar_period": "QUARTER"
    },
   "amount": {
      "specifiedAmount": {
        "units": 500
      }
    },
    "thresholdRules": {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    }
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My fancy budget",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "specifiedAmount": {
      "units": 500
    }
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

מחיקת תקציב

אתם יכולים להשתמש ברכיב ה-method הזה של ממשק ה-API כדי למחוק תקציב קיים לחיוב ב-Cloud.

REST

כדי לקרוא לשיטה הזו אתם צריכים את המזהה budget-id של התקציב שאתם רוצים לעדכן. אתם יכולים לקבל את מזהה התקציב מהפלט createBudget שנוצר כשיוצרים את התקציב, או מהפלט listBudgets שנוצר כשמציגים את רשימת כל התקציבים.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫billing-account-id: מספר החשבון לחיוב ב-Cloud שעליו חל התקציב הזה.
• ‫budget-id: המזהה של התקציב שאתם רוצים למחוק.
• ‫project-id: הפרויקט ב- Google Cloud שבו פועל Cloud Billing Budget API.

שיטת ה-HTTP וכתובת ה-URL:

DELETE https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{}