Menggunakan Cloud Billing Budget API untuk anggaran batas pembelanjaan

Pelajari cara mengirim beberapa permintaan anggaran batas pembelanjaan ke Cloud Billing Budget API.

Untuk mengetahui daftar lengkap metode, lihat dokumentasi referensi REST API.

Sebelum memulai

Anda harus melakukan hal berikut sebelum membaca panduan ini:

  1. Baca Ringkasan Cloud Billing Budget API.
  2. Baca Prasyarat Cloud Billing Budget API.
  3. Lakukan langkah-langkah penyiapan.

Mengidentifikasi ID akun Penagihan Cloud Anda

Untuk setiap panggilan API Cloud Billing Budget, Anda memerlukan ID akun Penagihan Cloud. Anggaran batas pembelanjaan terbatas untuk pelanggan Google Cloud pihak pertama dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.

  1. Buka Google Cloud halaman Kelola akun penagihan di konsol.
  2. Di tab Akun penagihan Anda, Anda akan melihat daftar akun Penagihan Cloud menurut nama dan ID. Temukan nilai ID Akun untuk akun tempat Anda mengelola anggaran.

Halaman Kelola penagihan yang menampilkan lokasi ID akun penagihan Anda.

Konsep dan batasan utama anggaran batas pembelanjaan

Anggaran batas pembelanjaan menggunakan biaya kotor yang diperkirakan untuk memicu pemberitahuan dan menerapkan batas pembelanjaan, sehingga memblokir penggunaan dan penambahan biaya hingga batas pembelanjaan dicabut.

Batasan kolom anggaran batas pembelanjaan

Jika spendCap ditetapkan pada anggaran, batasan kolom ketat berlaku untuk anggaran. Lihat komentar tingkat kolom di Filters, BudgetAmount, ThresholdRule, NotificationsRule, dan OwnershipScope.

  • billing-account-id: Anggaran batas pembelanjaan terbatas untuk pelanggan pihak pertama Google Cloud dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.

  • BudgetFilters harus menyertakan parameter berikut:

    • Anggaran batas pembelanjaan terbatas pada anggaran yang dicakup (difilter) ke project tunggal Google Cloud dan tunggal layanan yang memenuhi syarat.
    • Rentang waktu periode anggaran untuk anggaran batas pembelanjaan dibatasi hingga CalendarPeriod dari MONTH.
    • Penghitungan biaya untuk batas pembelanjaan didasarkan pada biaya kotor dan tidak mencakup penghematan dan kredit. Anda harus menetapkan creditTypesTreatment ke EXCLUDE_ALL_CREDITS.
    • Filter anggaran lainnya tidak didukung untuk batas pembelanjaan dan harus kosong, termasuk resourceAncestors, credit_types, subaccounts, dan labels.

  • BudgetAmount harus menggunakan specifiedAmount. Pada input, currencyCode bersifat opsional. Jika ditentukan saat membuat anggaran, kode mata uang harus sesuai dengan mata uang akun Penagihan Cloud. currencyCode disediakan pada output.

  • ThresholdRules harus berisi tepat tiga aturan dengan nilai thresholdPercent 0.5, 0.8, dan 1.0 (50%, 80%, dan 100%), dengan spendBasis ditetapkan ke CURRENT_SPEND atau BASIS_UNSPECIFIED (FORECASTED_SPEND tidak didukung untuk batas pembelanjaan).

  • NotificationsRule harus menyetel enableProjectLevelRecipients ke true. Semua parameter NotificationsRule lainnya tidak didukung.

  • OwnershipScope harus ditetapkan ke OWNERSHIP_SCOPE_UNSPECIFIED atau ALL_USERS (BILLING_ACCOUNT tidak didukung untuk batas pembelanjaan).

  • Saat membuat anggaran batas pembelanjaan, parameter inputState harus ditetapkan ke CONFIGURED.

Cara kerja anggaran batas pembelanjaan untuk membantu Anda mengontrol pembelanjaan

  • Perhitungan pembelanjaan yang lebih cepat menggunakan estimasi biaya: Untuk penegakan yang lebih cepat terhadap jumlah batas pembelanjaan, anggaran batas pembelanjaan menggunakan biaya kotor yang diperkirakan untuk memicu pemberitahuan dan menerapkan batas pembelanjaan. Estimasi biaya dihitung berdasarkan harga daftar layanan dan tidak mencakup penghematan dan kredit.

  • Penjeda otomatis penggunaan dan penambahan biaya saat batas pembelanjaan dipicu: Dalam project yang ditentukan, saat biaya penggunaan kotor dan perkiraan untuk layanan tertentu melebihi jumlah target anggaran, batas pembelanjaan akan dipicu dan diterapkan selama sisa periode anggaran. Pada anggaran, parameter outputState ditetapkan ke ENFORCED. Selama batas pembelanjaan diterapkan, hal berikut berlaku:

    • Semua penggunaan baru untuk layanan tertentu dalam project yang ditentukan akan dijeda, termasuk penggunaan on-demand, bayar sesuai penggunaan, dan penggunaan yang tercakup oleh komitmen seperti Diskon abonemen (CUD) dan Throughput yang Disediakan (PT).
    • Semua permintaan dalam proses dari layanan yang ditentukan akan diproses hingga selesai, dengan biaya yang terakumulasi sebagaimana berlaku.
    • Batas pembelanjaan tidak menjeda penggunaan tetap yang sedang berlangsung dan terkait dengan resource persisten (seperti layanan komputasi dan penyimpanan), yang tetap aktif dan terus menimbulkan biaya.
    • Penting: Saat dalam status diterapkan, Anda tidak dapat mengedit setelan anggaran batas pembelanjaan atau menghapus anggaran. Sebelum mengedit atau menghapus anggaran yang diterapkan, Anda harus membatalkan batas pembelanjaan secara manual terlebih dahulu.

  • Mencabut batas pembelanjaan yang diterapkan untuk memulihkan layanan dan pembelanjaan: Jika batas pembelanjaan diterapkan, penggunaan layanan tertentu dalam project yang ditentukan akan diblokir hingga batas pembelanjaan dicabut. Anda dapat meningkatkan batas pembelanjaan dengan cara berikut:

    • Meningkatkan batas pembelanjaan secara otomatis: Batas pembelanjaan yang diterapkan akan otomatis ditingkatkan pada awal periode anggaran berikutnya (biasanya hari pertama bulan berikutnya). Saat batas pembelanjaan otomatis ditingkatkan, jumlah pembelanjaan anggaran akan direset ke nol, status batas pembelanjaan akan direset ke CONFIGURED, dan layanan yang ditentukan akan dibuka blokirnya, sehingga memulihkan fungsi normal pada panggilan API.

    • Mencabut batas pembelanjaan secara manual: Jika Anda perlu membatalkan pemblokiran penggunaan selama periode anggaran yang sama saat batas pembelanjaan diterapkan, Anda dapat mengedit anggaran untuk mencabut batas pembelanjaan secara manual. Mencabut batas pembelanjaan secara manual akan memberikan hasil berikut:

      • Mengangkat batas pembelanjaan secara manual akan memulihkan fungsi normal pada panggilan API.
      • Jika Anda secara manual menghapus batas pembelanjaan dengan menetapkan status batas pembelanjaan ke AWAITING_NEXT_PERIOD, batas pembelanjaan tidak akan dipicu lagi selama sisa periode anggaran, kecuali jika Anda mengedit anggaran selanjutnya untuk menaikkan jumlah batas pembelanjaan dan menetapkan inputState ke CONFIGURED.

    Setelah batas pembelanjaan dihapus, layanan mungkin memerlukan waktu hingga satu jam untuk kembali berfungsi normal sepenuhnya.

  • Reset otomatis anggaran batas pembelanjaan: Di awal periode anggaran berikutnya (biasanya hari pertama bulan berikutnya), semua anggaran batas pembelanjaan akan otomatis direset, sehingga jumlah pembelanjaan kotor yang diperkirakan menjadi nol dan status batas pembelanjaan menjadi CONFIGURED.

Batasan kuota: Setiap akun Penagihan Cloud dapat memiliki beberapa ribu anggaran yang terkait dengannya sekaligus. Lihat Kuota dan batas untuk mengetahui batas saat ini dan informasi tambahan.

Memanggil API

Contoh berikut menunjukkan cara mengirim beberapa permintaan ke Cloud Billing Budget API untuk mengelola anggaran batas pembelanjaan.

Membuat anggaran batas pembelanjaan

Metode API ini membuat anggaran batas pembelanjaan Penagihan Cloud yang diterapkan ke satu project dan layanan yang memenuhi syarat.

REST

Contoh ini menunjukkan cara membuat anggaran batas pembelanjaan untuk penggunaan layanan Gemini API dalam project tertentu. Anggaran dicakup (difilter) ke satu Google Cloud project yang Anda tentukan, satu layanan yang memenuhi syarat, dan ditetapkan untuk jumlah anggaran bulanan sebesar $100.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • projects/budget-scope-project-id: Google Cloud Project ID yang ingin Anda tetapkan sebagai cakupan anggaran (budgetFilter).
  • services/eligible-service_id: Salah satu ID layanan yang memenuhi syarat yang ingin Anda tetapkan sebagai cakupan anggaran (budgetFilter). Dalam contoh, kita menggunakan ID layanan AEFD-7695-64FA untuk layanan Gemini API.
  • billing-account-id: ID akun Penagihan Cloud yang berlaku untuk anggaran ini. Anggaran batas pembelanjaan terbatas untuk pelanggan Google Cloud pihak pertama dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.
  • api-user-project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

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

Meminta isi JSON: 

{
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
 },
 "amount": {
   "specifiedAmount": {
     "units": "100",
     "nanos": 0
   }
 },
 "thresholdRules": [
   { "thresholdPercent": 0.5 },
   { "thresholdPercent": 0.8 },
   { "thresholdPercent": 1.0 }
 ],
 "notificationsRule": {
   "enableProjectLevelRecipients": true
 },
 "spendCap": {
   "inputState": "CONFIGURED"
 }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "100"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Mencabut batas pembelanjaan menggunakan PATCH

Gunakan metode API PATCH untuk mengubah anggaran batas pembelanjaan Penagihan Cloud yang ada guna mencabut batas pembelanjaan yang diterapkan secara manual.

REST

Contoh ini menunjukkan cara mencabut batas pembelanjaan ENFORCED secara manual pada anggaran yang ada dengan memperbarui parameter SpendCap.inputState menjadi AWAITING_NEXT_PERIOD.

Penting:Jika spend_cap.output_state adalah ENFORCED, Anda harus terlebih dahulu menghapus batas pembelanjaan dengan mengirimkan permintaan UpdateBudget untuk mengubah spend_cap.input_state, seperti menyetel input_state ke AWAITING_NEXT_PERIOD yang akan menghapus batas. Jika Anda mencoba mengubah kolom anggaran lain saat anggaran dalam status diterapkan, permintaan pembaruan akan gagal dengan FAILED_PRECONDITION.

Untuk memanggil metode ini, Anda memerlukan budget-id dari anggaran yang ingin Anda perbarui. Anda bisa mendapatkan ID anggaran dari output createBudget saat membuat anggaran, atau output listBudgets jika Anda mencantumkan semua anggaran.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • billing-account-id: ID akun Penagihan Cloud yang berlaku untuk anggaran ini. Anggaran batas pembelanjaan terbatas untuk pelanggan Google Cloud pihak pertama dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.
  • budget-id: ID anggaran yang ingin Anda perbarui.
  • api-user-project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=spendCap.inputState

Meminta isi JSON: 

{
  "spendCap": {
    "inputState": "AWAITING_NEXT_PERIOD"
 }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "100"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "AWAITING_NEXT_PERIOD",
    "reconciling": true
  }
}

Memperbarui anggaran batas pembelanjaan menggunakan PATCH

Gunakan metode API ini untuk mengubah anggaran batas pembelanjaan Penagihan Cloud yang ada guna mengubah jumlah anggaran dan filter anggaran (cakupan anggaran).

REST

Contoh ini menunjukkan cara memperbarui anggaran batas pembelanjaan yang ada untuk mengubah jumlah anggaran. Jika status batas pembelanjaan adalah AWAITING_NEXT_PERIOD, contoh ini juga menunjukkan cara mereset batas pembelanjaan yang dinaikkan dengan memperbarui parameter SpendCap.inputState menjadi CONFIGURED.

Untuk memanggil metode ini, Anda memerlukan budget-id dari anggaran yang ingin Anda perbarui. Anda bisa mendapatkan ID anggaran dari output createBudget saat membuat anggaran, atau output listBudgets jika Anda mencantumkan semua anggaran.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • projects/budget-scope-project-id: Google Cloud Project ID yang ingin Anda tetapkan sebagai cakupan anggaran (budgetFilter).
  • services/eligible-service_id: Salah satu ID layanan yang memenuhi syarat yang ingin Anda tetapkan sebagai cakupan anggaran (budgetFilter). Dalam contoh, kita menggunakan ID layanan AEFD-7695-64FA untuk layanan Gemini API.
  • billing-account-id: ID akun Penagihan Cloud yang berlaku untuk anggaran ini. Anggaran batas pembelanjaan terbatas untuk pelanggan pihak pertama dan akun Penagihan Cloud. Google Cloud Akun penagihan reseller tidak termasuk dalam cakupan.
  • budget-id: ID anggaran yang ingin Anda perbarui.
  • api-user-project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=amount.specifiedAmount,spendCap.inputState

Meminta isi JSON: 

{
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
 },
 "amount": {
   "specifiedAmount": {
     "units": "500",
     "nanos": 0
   }
 },
 "thresholdRules": [
   { "thresholdPercent": 0.5 },
   { "thresholdPercent": 0.8 },
   { "thresholdPercent": 1.0 }
 ],
 "notificationsRule": {
   "enableProjectLevelRecipients": true
 },
 "spendCap": {
   "inputState": "CONFIGURED"
 }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "500"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Cantumkan anggaran

Metode API ini mencantumkan semua anggaran yang tersedia untuk akun Penagihan Cloud tertentu.

REST

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • billing-account-id: ID akun Penagihan Cloud yang menjadi tujuan penerapan anggaran. Anggaran batas pembelanjaan terbatas untuk pelanggan Google Cloud pihak pertama dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.
  • project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON yang mirip seperti berikut:

{
  "budgets": [
   {
      "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
      "displayName": "Gemini API Spend Cap in My Project",
      "budgetFilter": {
        "projects": [
          "projects/987654321"
        ],
        "services": [
          "services/AEFD-7695-64FA"
        ],
        "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
        "calendarPeriod": "MONTH"
      },
      "amount": {
        "specifiedAmount": {
          "currencyCode": "USD",
          "units": "500"
        }
      },
      "thresholdRules": [
        {
          "thresholdPercent": 0.5,
          "spendBasis": "CURRENT_SPEND"
        },
        {
          "thresholdPercent": 0.8,
          "spendBasis": "CURRENT_SPEND"
        },
        {
          "thresholdPercent": 1,
          "spendBasis": "CURRENT_SPEND"
        }
      ],
      "notificationsRule": {
        "enableProjectLevelRecipients": true
      },
      "allUpdatesRule": {},
      "etag": "17fc365289f74138c",
      "spendCap": {
        "outputState": "ENFORCED"
      }
    }
  ]
}

Mendapatkan Anggaran

Metode API ini mendapatkan detail untuk anggaran tertentu.

REST

Untuk memanggil metode ini, Anda memerlukan budget-id dari anggaran yang ingin Anda perbarui. Anda bisa mendapatkan ID anggaran dari output createBudget saat membuat anggaran, atau output listBudgets jika Anda mencantumkan semua anggaran.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • billing-account-id: ID akun Penagihan Cloud yang berlaku untuk anggaran ini. Anggaran batas pembelanjaan terbatas untuk pelanggan Google Cloud pihak pertama dan akun Penagihan Cloud. Akun penagihan reseller tidak termasuk dalam cakupan.
  • budget-id: ID anggaran yang ingin Anda dapatkan.
  • project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Cloud Run Spend Cap in My Project",
  "budgetFilter": {
    "projects": [
      "projects/987654321"
    ],
    "services": [
      "services/152E-C115-5142"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "450"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "allUpdatesRule": {},
  "etag": "c9d6c011f6fa6b5c",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Menghapus anggaran

Gunakan metode API ini untuk menghapus anggaran Penagihan Cloud yang ada.

REST

Untuk memanggil metode ini, Anda memerlukan budget-id dari anggaran yang ingin Anda perbarui. Anda bisa mendapatkan ID anggaran dari output createBudget saat membuat anggaran, atau output listBudgets jika Anda mencantumkan semua anggaran.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • billing-account-id: ID akun Penagihan Cloud yang berlaku untuk anggaran ini.
  • budget-id: ID anggaran yang ingin dihapus.
  • project-id: Project Google Cloud tempat Cloud Billing Budget API diaktifkan.

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON yang mirip seperti berikut:

{}

Sebelumnya
Menggunakan Budget API untuk anggaran khusus pemberitahuan