Ringkasan Cloud Quotas API

Cloud Quotas API memungkinkan Anda menyesuaikan quotas secara terprogram dan mengotomatiskan penyesuaian kuota di project, folder, atau organisasi Google Cloud Anda. Penyesuaian dapat dilakukan untuk menambah atau mengurangi nilai kuota. Semua permintaan untuk menambah nilai kuota tunduk pada peninjauan dan persetujuan Google Cloud.

Cloud Quotas API dapat digunakan untuk:

Mengotomatiskan penyesuaian kuota
Anda dapat menggunakan Cloud Quotas API untuk meminta peningkatan kuota saat kondisi tertentu terpenuhi. Misalnya, untuk menghindari error kuota terlampaui, Anda dapat menggunakan API untuk meminta penambahan kuota secara terprogram saat resource Compute Engine mencapai 80% dari kuota yang tersedia.
Menskalakan konfigurasi kuota di seluruh project
Cloud Quotas API dapat meng-clone konfigurasi kuota Anda dari satu project ke project lain. Jika ada serangkaian kuota yang diketahui yang perlu ditingkatkan untuk setiap project Google Cloud baru, Anda dapat mengintegrasikan API ke dalam logika pembuatan project untuk mengeluarkan QIR secara otomatis. Semua peningkatan kuota tunduk pada peninjauan dan persetujuan Google Cloud.
Melayani permintaan kuota pelanggan
Jika Anda adalah penyedia SaaS yang terintegrasi dengan Google Cloud, Anda dapat menerima permintaan penambahan kuota melalui portal yang berhubungan langsung dengan pelanggan selain konsol Google Cloud. Permintaan ini harus diteruskan ke Google Cloud untuk diproses. Cloud Quotas API dapat meneruskan permintaan pelanggan secara otomatis.
Aktifkan kontrol versi konfigurasi klien
Cloud Quotas API bersifat deklaratif. Anda dapat memperlakukan konfigurasi kuota sebagai kode dan konfigurasi penyimpanan di sistem terkontrol versi Anda sendiri untuk histori dan rollback.

Batasan

Cloud Quotas API memiliki batasan berikut:

  • API tidak mendukung Google Cloud CLI.

  • API tidak mendukung permintaan penambahan kuota untuk kuota tingkat folder dan tingkat organisasi.

Endpoint layanan

Endpoint layanan adalah URL dasar yang menentukan alamat jaringan layanan API. Satu layanan mungkin 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 untuk mengakses resource cloudquotas_quotaPreferences dan cloudquotas_quotaInfos, minta administrator untuk memberi Anda peran IAM Cloud Quotas Admin (cloudquotas.admin) pada project tersebut. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk mengakses resource cloudquotas_quotaPreferences dan cloudquotas_quotaInfos. Untuk melihat izin persis yang diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengakses resource cloudquotas_quotaPreferences dan cloudquotas_quotaInfos:

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

Anda mung juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaanlainnya.

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 resource ini untuk menyesuaikan kuota di project, folder, atau organisasi Anda.

Menetapkan nilai pilihan untuk sebuah 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 dari 100 menunjukkan bahwa pemohon ingin kuota GPUS-PER-GPU-FAMILY-per-project-region ditetapkan ke nilai tersebut. Kolom dimensi menunjukkan preferensi hanya berlaku untuk wilayah us-central1.

Memverifikasi nilai yang diberikan

Contoh berikut menunjukkan resource QuotaPreference dalam metode GetQuotaPreference.

{
    "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 dihasilkan secara otomatis untuk project Anda.

Respons menunjukkan grantedValue 100, yang berarti preferredValue dari contoh sebelumnya telah disetujui dan terpenuhi. 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:

  • QuotaPreference permintaan dibuat oleh Anda.

  • Menyetujui permintaan penambahan kuota 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 nilai yang disetujui Google Cloud untuk menambah batasan lebih lanjut.

Untuk mengetahui 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 apa pun yang terpenuhi yang dimulai oleh pelanggan. Resource QuotaInfo berisi informasi seperti metadata, jenis penampung, dan dimensi.

Menetapkan nilai kuota yang berbeda berdasarkan region

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

{
    "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 dihasilkan secara otomatis untuk project Anda.

Menetapkan kuota global

Contoh resource QuotaInfo berikut menunjukkan kuota kapasitas dengan interval refresh per menit. Dimensi ini 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 dihasilkan secara otomatis untuk project Anda.

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

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

Nama resource

Resource adalah entity bernama dan diidentifikasi berdasarkan nama resource. Nama resource digunakan dalam semua permintaan dan respons, dan setiap resource harus memiliki nama resource uniknya sendiri. Setiap nama resource dienkode oleh sekumpulan kolom.

Resource preferensi kuota

Konvensi penamaan untuk resource QuotaPreference menggunakan pola berikut:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFENCE_ID

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

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

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

Contoh berikut menunjukkan pola tersebut: 

compute_us-central1_nvidia-200

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

Resource info kuota

Konvensi penamaan untuk resource QuotaInfo menggunakan pola berikut:

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

Prioritas dimensi

Beberapa kasus penggunaan untuk Cloud Quotas API memiliki penyiapan dimensi yang kompleks. Kuota dapat dikonfigurasi pada level yang lebih terperinci, bukan hanya region dan zona. Anda dapat mencapai perincian ini saat menggunakan dimensi khusus layanan. Misalnya, gpu_family dan network_id adalah dimensi khusus layanan dalam layanan Compute Engine. Dimensi ditentukan oleh masing-masing layanan dan setiap layanan dapat memiliki kumpulan dimensi khusus layanan yang berbeda.

Saat menangani dimensi lokasi atau dimensi khusus layanan, prioritas berikut akan diterapkan:

  1. Konfigurasi preferensi kuota dengan semua dimensi khusus lokasi dan layanan yang ditentukan akan diprioritaskan daripada konfigurasi lainnya.

  2. Konfigurasi yang menentukan dimensi lokasi hanya lebih diprioritaskan daripada konfigurasi yang hanya berisi dimensi khusus layanan.

Menggabungkan dimensi

Dalam konfigurasi preferensi kuota, Anda dapat menggabungkan dimensi dengan cara berikut:

  1. Konfigurasi tersebut dapat berisi kedua dimensi lokasi dan dimensi khusus layanan. Ini adalah urutan tertinggi yang diprioritaskan.

  2. Konfigurasi hanya dapat berisi dimensi lokasi. Konfigurasi ini berlaku untuk semua dimensi khusus layanan, kecuali dimensi yang secara eksplisit dikonfigurasi dengan metode 1.

  3. Konfigurasi hanya dapat berisi dimensi khusus layanan. Konfigurasi ini berlaku untuk semua lokasi kecuali yang dikonfigurasi secara eksplisit dengan metode 1 atau 2.

  4. Jika konfigurasi berisi dimensi khusus layanan apa pun, konfigurasi tersebut harus berisi semua dimensi khusus layanan.

  5. Anda dapat memiliki konfigurasi tanpa dimensi apa pun. Konfigurasi tersebut berlaku untuk semua lokasi dan semua dimensi khusus layanan, kecuali yang dikonfigurasi secara eksplisit.

Apa langkah selanjutnya?