Ringkasan Cloud Quotas API

Cloud Quotas API memungkinkan Anda menyesuaikan kuota tingkat project secara terprogram dan mengotomatiskan permintaan penyesuaian kuota tingkat project. Misalnya, Anda dapat menggunakan Cloud Quotas API untuk:

  • Mengotomatiskan penyesuaian kuota: Anda dapat menggunakan Cloud Quotas API untuk meminta penyesuaian kuota berdasarkan kriteria Anda sendiri. Misalnya, untuk menghindari error kuota yang terlampaui, Anda dapat menggunakan API untuk meminta penyesuaian kuota secara terprogram saat resource Compute Engine mencapai 80% dari kuota yang tersedia.

  • Menggunakan kembali konfigurasi kuota di seluruh project: Cloud Quotas API dapat meng-clone konfigurasi kuota Anda dari project ke project. Jika ada kumpulan kuota yang diketahui dan perlu ditingkatkan untuk setiap project Google Cloud baru, Anda dapat menggunakan Cloud Quotas API untuk mengotomatiskan hal ini dalam logika pembuatan project. Permintaan penyesuaian kuota harus mendapatkan Google Cloud persetujuan.

  • Melayani permintaan kuota pelanggan: Jika Anda adalah penyedia SaaS yang terintegrasi denganGoogle Cloud, Anda mungkin menerima permintaan penambahan kuota melalui portal yang ditampilkan kepada pelanggan selain konsol Google Cloud. Permintaan ini harus diteruskan ke Google Cloud untuk diproses. Cloud Quotas API dapat otomatis meneruskan permintaan pelanggan.

  • Mengaktifkan kontrol versi konfigurasi klien: Cloud Quotas API bersifat deklaratif. Anda dapat memperlakukan konfigurasi kuota sebagai kode dan menyimpan konfigurasi di sistem yang dikontrol versi Anda sendiri untuk histori dan rollback.

Batasan

Kuota Cloud memiliki batasan berikut:

  • Pada umumnya, penyesuaian peningkatan kuota harus dilakukan di tingkat project. Sejumlah produk terbatas mendukung penyesuaian peningkatan kuota tingkat organisasi. Untuk melihat apakah produk Google Cloud mendukung penyesuaian peningkatan kuota tingkat organisasi, lihat dokumentasi untuk produk tersebut.

  • Anda dapat meminta penyesuaian pengurangan kuota untuk kuota tingkat folder, organisasi, dan project.

  • Cloud Quotas API hanya mendukung operasi tingkat project. Operasi tingkat folder dan tingkat organisasi tidak didukung.

Endpoint layanan

Endpoint layanan adalah URL dasar yang menentukan alamat jaringan layanan API. Satu layanan dapat memiliki beberapa endpoint. Layanan Cloud Quotas API memiliki endpoint berikut dan semua URI bersifat relatif terhadapnya:

https://cloudquotas.googleapis.com

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengakses resource cloudquotas_quotaPreferences, cloudquotas_quotaInfos, dan cloudquotas_quotaAdjusterSettings, minta administrator untuk memberi Anda peran IAM Cloud Quotas Admin (cloudquotas.admin) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk mengakses resource cloudquotas_quotaPreferences, cloudquotas_quotaInfos, dan cloudquotas_quotaAdjusterSettings. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengakses resource cloudquotas_quotaPreferences, cloudquotas_quotaInfos, dan cloudquotas_quotaAdjusterSettings:

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

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Model resource API

Model resource Cloud Quotas API terdiri dari dua resource: QuotaPreference dan QuotaInfo.

Preferensi kuota

Resource QuotaPreference mewakili preferensi kuota Anda untuk kombinasi dimensi tertentu. Gunakan referensi ini untuk menyesuaikan kuota di project, folder, atau organisasi Anda.

Menetapkan nilai pilihan untuk wilayah

Contoh berikut menunjukkan resource QuotaPreference dalam metode CreateQuotaPreference.

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

preferredValue 100 menunjukkan bahwa pemohon ingin kuota GPUS-PER-GPU-FAMILY-per-project-region ditetapkan ke nilai tersebut. Kolom dimensi menunjukkan bahwa preferensi hanya berlaku untuk wilayah us-central1.

Memverifikasi nilai yang diberikan

Lihat preferensi kuota Anda dan lihat kolom grantedValue untuk memverifikasi nilai yang diberikan.

Untuk melihat preferensi kuota menggunakan Google Cloud CLI, jalankan perintah berikut di terminal Anda:

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

Ganti kode berikut:

  • QUOTA_PREFERENCE_ID: ID preferensi kuota Anda. Ini adalah nilai yang ditentukan saat preferensi kuota dibuat.
  • PROJECT: ID atau nomor project Google Cloud Anda.

Jika Anda membuat permintaan penyesuaian kuota dan permintaan tersebut disetujui sebagian, kolom stateDetail akan muncul setelah kolom grantedValue. grantedValue menampilkan penyesuaian yang dilakukan, dan kolom stateDetail menjelaskan status yang disetujui sebagian.

Untuk melihat apakah nilai yang diberikan adalah nilai akhir yang disetujui, lihat kolom reconciling. Jika permintaan Anda masih dalam evaluasi, kolom reconciling akan ditetapkan ke true. Jika kolom reconciling ditetapkan ke false atau dihilangkan, nilai yang diberikan adalah nilai akhir yang disetujui.

Cuplikan kode berikut menunjukkan contoh objek preferensi kuota. Project ini menggunakan preferensi kuota demo dengan ID compute_googleapis_com-gpus-us-central1.

gcloud

Jika Anda melihat preferensi kuota menggunakan gcloud CLI, outputnya akan terlihat seperti berikut:

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:
    granteddValue: '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

Jika Anda melihat preferensi kuota menggunakan Cloud Quotas API, output-nya akan terlihat seperti berikut:

{
    "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"
}

Output ini mencakup nilai-nilai berikut:

  • PROJECT_NUMBER: ID unik yang dibuat secara otomatis untuk project Anda.

Respons menunjukkan grantedValue 100, yang berarti preferredValue dari contoh sebelumnya telah disetujui dan dipenuhi. Preferensi untuk dimensi yang berbeda adalah resource QuotaPreference yang berbeda. Misalnya, QuotaPreference untuk CPU di region us-central1 dan us-east1 adalah dua resource yang berbeda.

Preferensi kuota wajib diisi

Resource QuotaPreference digunakan untuk menunjukkan nilai pilihan Anda untuk kuota tertentu. Nilai saat ini untuk kuota tertentu didasarkan pada:

  • Permintaan QuotaPreference yang Anda buat.

  • Permintaan penambahan kuota yang disetujui oleh Google Cloud.

  • Perubahan pada kuota yang dimulai oleh Google Cloud.

Kemampuan untuk menghapus QuotaPreference tidak didukung. Namun, Anda dapat menetapkan nilai kuota pilihan yang lebih rendah dari Google Cloud nilai yang disetujui untuk menambahkan pembatasan lebih lanjut.

Untuk informasi selengkapnya tentang resource QuotaPreference, lihat Referensi Cloud Quotas API.

Untuk informasi selengkapnya tentang kueri QuotaPreference, lihat Menerapkan kasus penggunaan umum.

Info kuota

QuotaInfo adalah resource hanya baca yang memberikan informasi tentang kuota tertentu untuk project, folder, atau organisasi tertentu. Halaman ini menampilkan informasi dari kuota yang ditentukan oleh layanan Google Cloud dan penyesuaian kuota yang terpenuhi yang dimulai oleh pelanggan. Resource QuotaInfo berisi informasi seperti metadata, jenis penampung, dan dimensi.

Menetapkan nilai kuota yang berbeda menurut wilayah

Contoh resource QuotaInfo berikut menunjukkan bahwa kuota CPU untuk project adalah 200 untuk region us-central1 dan 100 untuk semua region lainnya.

{
    "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"
            ]
        }
    ]
}

Output ini mencakup nilai-nilai berikut:

  • PROJECT_NUMBER: ID unik yang dibuat secara otomatis untuk project Anda.

Menetapkan kuota global

Contoh resource QuotaInfo berikut menunjukkan kuota kapasitas dengan interval pembaruan per menit. Dimensi kosong, yang menunjukkan bahwa ini adalah kuota global. Semua kuota tanpa dimensi region atau zona bersifat global.

{
    "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"
            ]
        }
    ]
}

Output ini mencakup nilai-nilai berikut:

  • PROJECT_NUMBER: ID unik yang dibuat secara otomatis untuk project Anda.

Untuk mengetahui detail selengkapnya tentang resource QuotaInfo, lihat Referensi Cloud Quotas API.

Untuk mengetahui detail selengkapnya tentang kueri QuotaPreference, lihat Menerapkan kasus penggunaan umum.

Setelan pengatur kuota

Resource QuotaAdjusterSettings (Pratinjau) mewakili setelan pengatur kuota untuk project tertentu. Jika diaktifkan, pengatur kuota akan memantau penggunaan resource yang ditentukan dan mengeluarkan permintaan penyesuaian kuota saat penggunaan resource mendekati nilai kuotanya.

  • Untuk melihat setelan penyesuai kuota saat ini untuk project, gunakan operasi GET untuk mengambil resource QuotaAdjusterSettings.

  • Untuk mengaktifkan pengatur kuota untuk project, gunakan operasi PATCH untuk menetapkan opsi resource QuotaAdjusterSettings berikut:

      "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}

    Ganti PROJECT_NUMBER dengan ID unik untuk project Anda.

Untuk mengetahui detailnya, lihat Mengaktifkan pengatur kuota dan Menonaktifkan pengatur kuota.

Nama resource

Resource adalah entitas bernama dan diidentifikasi dengan nama resource. Nama resource digunakan dalam semua permintaan dan respons, dan setiap resource harus memiliki nama resource unik tersendiri. Setiap nama resource dienkode oleh serangkaian kolom.

Resource preferensi kuota

Konvensi penamaan untuk resource QuotaPreference menggunakan pola berikut:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Anda dapat menetapkan quotaPreferenceId saat membuat preferensi kuota. Jika tidak, ID akan dibuat. Sebaiknya skema penamaan quotaPreferenceId encode nama layanan, ID kuota, lokasi, dan dimensi lainnya. quotaPreferenceId harus unik untuk project, folder, atau organisasi.

Sebagai contoh quotaPreference Salah satu pola untuk mengenkode ID preferensi kuota Anda adalah sebagai berikut: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

Contoh berikut menunjukkan pola ini: 

compute_us-central1_nvidia-200

Dengan nama resource, Anda harus menggunakan metode GET untuk mengambil QuotaPreference. Anda juga dapat memanggil metode PATCH dengan opsi allow_missing diaktifkan untuk membuat atau memperbarui QuotaPreference.

Referensi info kuota

Konvensi penamaan untuk resource QuotaInfo menggunakan pola berikut:

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

Referensi setelan pengatur kuota

Konvensi penamaan untuk resource QuotaAdjusterSettings menggunakan pola berikut:

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

Apa langkah selanjutnya?