Menerapkan kasus penggunaan umum

Halaman ini menjelaskan cara menerapkan kasus penggunaan umum menggunakan Cloud Quotas API. API ini memungkinkan Anda menyesuaikan quotas secara terprogram dan mengotomatiskan penyesuaian kuota di project, folder, atau organisasi Google Cloud Anda.

Untuk mempelajari lebih lanjut, lihat ringkasan dan referensi Cloud Quotas API.

Batasan

Cloud Quotas API memiliki batasan berikut:

API tidak mendukung Google Cloud CLI.
API ini mendukung penyesuaian kuota untuk kuota level project. Penurunan kuota dapat diminta untuk kuota tingkat project, folder, dan organisasi.
API tidak mendukung Kontrol Layanan VPC.

Lacak penggunaan dan minta peningkatan saat penggunaan di atas 80%

Contoh ini melacak penggunaan kuota dengan Cloud Monitoring, lalu meminta peningkatan saat penggunaan melebihi 80%.

Panggil resource QuotaInfo untuk layanan Anda guna menentukan quotaValue saat ini. Layanan dalam contoh ini adalah compute.googleapis.com:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Untuk menemukan CPU per project dan lokasi yang berlaku, lihat respons QuotaInfo untuk ID kuota CPUS-per-project-region. quotaValue adalah 20.

"quotaInfos": [
    …
     {
        "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"
        ],
        "dimensionsInfo": [
            {
                "dimensions": [],
                "details": {
                    "quotaValue": 20,
                    "resetValue": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
            }
        ]
    },
      …
]

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Panggil Cloud Monitoring API untuk menemukan penggunaan kuota. Dalam contoh berikut, region us-central1 telah ditentukan. Metrik kuota yang didukung tercantum di bagian serviceruntime.

{
"name": "projects/PROJECT_NUMBER"
    "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND
    metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND
    resource.label.location=\"us-central1\" ",
    "interval": {
    "startTime": "2023-11-10T18:18:18.0000Z",
    "endTime": "2023-11-17T18:18:18.0000Z"
    },
    "aggregation": {
    "alignmentPeriod": "604800s", // 7 days
    "perSeriesAligner": ALIGN_MAX,
    "crossSeriesReducer": REDUCE_MAX
    }
}

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Untuk menentukan penggunaan Anda, tangani respons dari Cloud Monitoring API. Bandingkan nilai dari Cloud Monitoring dengan quotaValue pada langkah-langkah sebelumnya untuk menentukan penggunaan.

Pada contoh respons berikut, nilai penggunaan di Cloud Monitoring adalah 19 di region us-central1. quotaValue untuk semua region adalah 20. Penggunaannya lebih besar dari 80% kuota, dan update preferensi kuota dapat dimulai.

time_series {
 metric {
  labels {
   key: "quota_metric"
   value: "compute.googleapis.com/cpus"
  }
     type: "serviceruntime.googleapis.com/quota/allocation/usage"
  }
  resource {
    type: "consumer_quota"
    labels {
      key: "project_id"
      value: "PROJECT_ID"
    }
    labels {
      key: "location"
      value: "us-central1"
    }
  }
  metric_kind: GAUGE
  value_type: INT64
  points {
    interval {
      start_time {
        seconds: "2023-11-10T18:18:18.0000Z"
      }
      end_time {
        seconds: "2023-11-17T18:18:18.0000Z"
      }
    }
    value {
      int64_value: 19
    }
  }
}

Output ini mencakup nilai berikut:

PROJECT_ID: ID unik global untuk project Anda.

Untuk menghindari preferensi kuota duplikat, panggil ListQuotaPreferences terlebih dahulu untuk memeriksa apakah ada permintaan yang tertunda. Flag reconciling=true memanggil permintaan yang tertunda.
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
```
Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.
Panggil UpdateQuotaPreference guna meningkatkan nilai kuota untuk region us-central1. Dalam contoh berikut, nilai preferensi baru sebesar 100 telah ditentukan.

Kolom allow_missing ditetapkan ke true. Ini akan memberi tahu sistem untuk membuat resource QuotaPreference, sedangkan resource tersebut tidak ada dengan nama yang diberikan.
```
PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true {
    "service": "compute.googleapis.com",
    "quotaId": "CPUS-per-project-region",
    "quotaConfig": {
    "preferredValue": 100
    },
    "dimensions": [
    "mapField": {
    "key": "region",
    "value": "us-central1"
    }
    ],
    }
```
Output ini mencakup nilai berikut:
- PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.
Untuk menyesuaikan dimensi preferensi kuota, Anda dapat melakukan tindakan berikut:
- Jika Anda ingin preferensi kuota berlaku untuk semua region, hapus informasi region.
- Jika kuota Anda ditentukan per zona, ganti informasi region dengan informasi zona.

Panggil GetQuotaPreference untuk memeriksa status perubahan preferensi kuota:

GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda. Saat Google Cloud mengevaluasi nilai kuota yang diminta, status rekonsiliasi ditetapkan ke true.

"name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": {
    "preferredValue": 100,
    "grantedValue": 50,
    "traceId": "123acd-345df23",
    "requestOrigin": "ORIGIN_UNSPECIFIED"
},
"dimensions": [
    "mapField": {
        "key": "region",
        "value": "us-central1"
    }
],
"reconciling": true
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Setelah preferensi kuota diproses, kolom reconciling ditetapkan ke false. grantedValue sama dengan preferredValue. Kuota pilihan diberikan sepenuhnya.

Saat Google Cloud menolak atau menyetujui sebagian permintaan pelanggan, nilai kuota yang diberikan masih bisa kurang dari nilai yang diinginkan.

Mengurangi kuota

Contoh berikut mengurangi jumlah TPU menjadi 10 di setiap region.

Dapatkan ID kuota dan nilai kuota saat ini dengan panggilan ListQuotaInfos:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Periksa kolom respons guna menemukan entri QuotaInfo untuk V2-TPUS-per-project-region.

"quotaInfos": [
    …
     {
        "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
        "quotaId": "V2-TPUS-per-project-region",
        "metric": "compute.googleapis.com/Tpus",
        "containerType": "PROJECT",
        "dimensions": [
            "region"
        ],
        "dimensionsInfo": [
            {
                "dimensions": [],
                "details": {
                    "quotaValue": 20,
                    "resetValue": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
            }
        ]
    },
      …
]

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Dalam respons ini, ID kuotanya adalah V2-TPUS-per-project-region, dan quotaValue saat ini adalah 20.

Kurangi kuota TPU di setiap region menjadi 10 dengan CreateQuotaPreferenceRequest. Tetapkan preferredValue ke 10.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions {
    "quotaConfig": {
        "preferredValue": 10
    },
    "dimensions": [],
    "service": "compute.googleapis.com",
    "quotaId": "V2-TPUS-per-project-region",
}

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Konfirmasi nilai kuota baru dengan panggilan GetQuotaInfo yang menentukan ID kuota sebagai V2-TPUS-per-project-region.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda. Berikut adalah contoh respons, value adalah 10 dan berlaku di semua region.

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
"quotaId": "V2-TPUS-per-project-region",
"metric": "compute.googleapis.com/v2_tpus",
"containerType": "PROJECT",
"dimensions": [
    "region"
],
"dimensionsInfo": [
    {
        "dimensions": [],
        "details": {
            "value": 10,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

Output ini mencakup nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Menyalin preferensi kuota ke project lain

Contoh berikut menyalin semua preferensi kuota dari satu project ke project lainnya.

Panggil ListQuotaPreferences di project sumber tanpa filter:
```
GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
```
PROJECT_NUMBER1 adalah nomor project untuk project sumber. Respons berisi semua preferensi kuota untuk project sumber.

Untuk setiap preferensi kuota dalam respons, panggil UpdateQuotaPreference dan tentukan kolom berikut:

name - Kolom nama yang diperbarui diambil dari respons, dan nomor project sumber (PROJECT_NUMBER1) diganti dengan nomor project tujuan (PROJECT_NUMBER2).
service, quotaId, preferredValue, dimensions - Kolom ini dapat diambil langsung dari respons apa adanya.

for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
    QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
        .setService(srcPreference.getService())
        .setQuotaId(srcPreference.getQuotaId())
        .setQuotaConfig(
            QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
        .putAllDimensions(srcPreference.getDimensionsMap());
    UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
    cloudQuotas.updateQuotaPreference(updateRequest);
}

Panggil ListQuotaPreferences untuk memverifikasi status preferensi kuota untuk project tujuan:
```
GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
```
Ganti PROJECT_NUMBER2 dengan nomor project untuk project tujuan Anda.

Mencantumkan permintaan kuota yang tertunda

Untuk mencantumkan semua permintaan preferensi kuota yang tertunda untuk sebuah project, panggil ListQuotaPreferences dengan filter reconciling=true.

Get projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Respons untuk permintaan ini menampilkan preferensi kuota terbaru yang tertunda. Karena Cloud Quotas API adalah API deklaratif, preferensi kuota terbaru adalah yang coba dipenuhi oleh sistem.

Berikut adalah contoh respons:

"quotaPreferences": [
    {
        "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
        "service": "compute.googleapis.com",
        "quotaId": "CPUS-per-project-region",
        "quotaConfig": {
            "preferredValue": 100,
            "grantedValue": 30,
            "traceId": "123acd-345df23",
            "requestOrigin": "ORIGIN_UNSPECIFIED"
        },
        "dimensions": [
            "map_field": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "reconciling": true
    "createTime": "2023-01-15T01:30:15.01Z",
        "updateTime": "2023-01-16T02:35:16.01Z"
    },
    {
        "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions",
        "service": "compute.googleapis.com",
        "quotaId": "CPUS-per-project-region",
        "quotaConfig": {
            "preferredValue": 10,
            "grantedValue": 5,
            ,
            "traceId": "456asd-678df43",
            "requestOrigin": "ORIGIN_UNSPECIFIED"
        },
        "reconciling": true
    "createTime": "2023-01-15T01:35:15.01Z",
        "updateTime": "2023-01-15T01:35:15.01Z"
    }
]

Output ini mencakup nilai-nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Meminta penambahan kuota grup

Untuk meminta peningkatan kuota dalam project baru, simpan kuota pilihan untuk project baru dalam file CSV dengan nilai berikut: nama layanan, ID kuota, nilai kuota pilihan, dimensi.

Untuk setiap baris dalam file CSV, baca konten di kolom serviceName, quotaId, preferredValue, dan dimensionMap.

CreateQuotaPreferenceRequest request =
  CreateQuotaPreferenceRequest.newBuilder()
     .setParent("projects/PROJECT_NUMBER/locations/global")
     .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap))
     .setQuotaPreference(
        QuotaPreference.newBuilder()
            .setService(serviceName)
            .setQuotaId(quotaId)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Karena project target masih baru, aman untuk memanggil metode CreateQuotaPreference saat Anda membaca dan menetapkan kolom. Atau, Anda dapat memanggil metode UpdateQuotaPreference dengan allow_missing yang ditetapkan ke true.

Metode buildYourOwnQuotaPreferenceId membuat ID preferensi kuota dari nama layanan, ID kuota, dan peta dimensi sesuai dengan skema penamaan Anda. Atau, Anda dapat memilih untuk tidak menetapkan ID preferensi kuota. ID preferensi kuota akan dibuat untuk Anda.

Mendapatkan info kuota untuk dimensi khusus layanan

Kelompok GPU adalah dimensi khusus layanan. Contoh permintaan berikut menggunakan ID kuota GPUS-PER-GPU-FAMILY-per-project-region untuk mendapatkan resource QuotaInfo.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

Ini adalah contoh respons. Untuk setiap kunci gpu_family unik, quotaValue dan applicableLocations berbeda:

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion",
"quotatName": "CPUS-per-project-region",
"metric": "compute.googleapis.com/gpus_per_gpu_family",
"isPrecise": true,
"quotaDisplayName": "GPUs per GPU family",
"metricDisplayName": "GPUs",
"dimensions": [
    "region",
    "gpu_family"
],
"dimensionsInfo": [
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            },
            "mapField": {
                "key": "gpu_family",
                "value": "NVIDIA_H200"
            }
        ],
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "gpu_familly",
                "value": "NVIDIA_H100"
            }
        ],
        "details": {
            "quotaValue": 10,
        },
        "applicableLocations": [
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
      {
        "dimensions": [],
        "details": {
            "quotaValue": 50,
            "resetValue": 50,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

Output ini mencakup nilai-nilai berikut:

PROJECT_NUMBER: ID unik yang dihasilkan secara otomatis untuk project Anda.

Membuat preferensi kuota untuk dimensi khusus layanan

Contoh berikut menunjukkan cara membuat kuota untuk region dan kelompok GPU tertentu dengan nilai 100 yang diutamakan. Lokasi target ditentukan dalam peta dimensi dengan kunci region, dan kelompok GPU target dengan kunci gpu_family.

Contoh CreateQuotaPreference berikut menentukan kelompok GPU NVIDIA_H100 dan region us-central1. Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": [
        "mapField": {
            "key": "region",
            "value": "us-central1"
        }
          "mapField": {
            "key": "gpu_family",
            "value": "NVIDIA_H100"
        }
    ],
}

Memperbarui preferensi kuota untuk dimensi khusus layanan

Kode contoh berikut mendapatkan nilai saat ini untuk dimensi {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, lalu menetapkan nilai pilihan menjadi dua kali lipat. Ganti PROJECT_NUMBER dengan nomor project untuk project Anda.

// Get the current quota value for the target dimensions
Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100");
long currentQuotaValue = 0;
QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo(
    "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId;
for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) {
    If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) {
       currentQuotaValue = dimensionsInfo.getDetails().getValue();
       break;
    })
}

// Set the preferred quota value to double the current value for the target dimensions
QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions))
        .setService(serviceName)
        .setQuotaId(quotaId)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

Langkah selanjutnya

Tentang Cloud Quotas API
Referensi Cloud Quotas API
Pelajari quotas