本页面介绍如何使用 Cloud Quotas API 实现常见应用场景。借助此 API，您能够在 Google Cloud 项目、文件夹或组织中以编程方式调整配额并自动执行配额调整。
如需了解详情，请参阅 Cloud Quotas API 概览和参考文档。
限制
Cloud Quotas API 具有以下限制：
该 API 不支持 Google Cloud CLI。
该 API 支持针对项目级配额的配额调整。您可以针对项目、文件夹和组织级请求减少配额。
该 API 不支持 VPC Service Controls。
跟踪用量，并在用量超过 80% 时请求增加配额
此示例通过 Cloud Monitoring 跟踪配额用量，然后在用量超过 80% 时请求增加配额。
- 调用服务的
QuotaInfo资源以确定当前quotaValue。此示例中的服务为compute.googleapis.com：GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
将PROJECT_NUMBER替换为您的项目编号。 - 如需了解每个项目的 CPU 数量以及适用的位置，请在
QuotaInfo响应中查找CPUS-per-project-region配额 ID。quotaValue为 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" ] } ] }, … ]此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
- 调用 Cloud Monitoring API 以了解配额用量。在以下示例中，指定了区域
us-central1。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 } }此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
- 如需确定您的用量，请处理来自 Cloud Monitoring API 的响应。
将来自 Cloud Monitoring 的值与前面步骤中的
quotaValue进行比较以确定用量。
在以下示例响应中，Cloud Monitoring 中的用量值在us-central1区域中 为 19。所有区域的quotaValue为 20。用量超过配额的 80%，您可以发起配额偏好设置更新。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 } } }此输出包括以下值：PROJECT_ID：项目的全局唯一标识符。
- 如需避免重复的配额偏好设置，请先调用
ListQuotaPreferences来检查是否存在任何待处理的请求。reconciling=true标志会调用待处理的请求。GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
将PROJECT_NUMBER替换为您的项目编号。 - 调用
UpdateQuotaPreference以增加区域us-central1的配额值。在以下示例中，指定了新的首选值 100。
字段allow_missing设置为true。这会指示系统使用所提供的名称创建其中不存在任何内容的QuotaPreference资源。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" } ], }此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
- 调用
GetQuotaPreference以检查配额偏好设置更改的状态：GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
将PROJECT_NUMBER替换为您的项目编号。 Google Cloud 评估请求的配额值时，正在调整状态会设置为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"此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
reconciling字段会设置为false。grantedValue与preferredValue相同。首选配额已完整授予。
如果 Google Cloud 拒绝或部分批准客户请求，则授予的配额值仍然可能小于首选值。
减少配额
以下示例将每个区域中的 TPU 数量减少到 10。
- 使用
ListQuotaInfos调用获取配额 ID 和当前配额值：GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
将PROJECT_NUMBER替换为您的项目编号。 - 浏览响应字段以查找
V2-TPUS-per-project-region的QuotaInfo条目。"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" ] } ] }, … ]此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
V2-TPUS-per-project-region，当前quotaValue为 20。 - 使用
CreateQuotaPreferenceRequest将每个区域中的 TPU 配额减少到 10。 将preferredValue设置为 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", }此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
- 使用将配额 ID 定义为
V2-TPUS-per-project-region的GetQuotaInfo调用确认新的配额值。GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region
将PROJECT_NUMBER替换为您的项目编号。 以下是示例响应，value为 10，适用于所有区域。"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" ] } ]此输出包括以下值：PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
将配额偏好设置复制到另一个项目
以下示例将所有配额偏好设置从一个项目复制到另一个项目。
- 在不使用过滤条件的情况下对源项目调用
ListQuotaPreferences：GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
PROJECT_NUMBER1 是源项目的项目编号。响应包含源项目的所有配额偏好设置。 - 对于响应中的每个配额偏好设置，请调用
UpdateQuotaPreference并定义以下字段：name- 更新后的名称字段从响应中获取，源项目编号 (PROJECT_NUMBER1) 会替换为目标项目编号 (PROJECT_NUMBER2)。service、quotaId、preferredValue、dimensions- 这些字段可以直接从响应中按原样获取。
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); } - 调用
ListQuotaPreferences以验证目标项目的配额偏好设置的状态：GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
将PROJECT_NUMBER2替换为目标项目的项目编号。
列出待处理的配额请求
如需列出项目的所有待处理配额偏好设置请求，请使用过滤条件 reconciling=true 调用 ListQuotaPreferences。
Get projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true
将 PROJECT_NUMBER 替换为您的项目编号。
此请求的响应会返回最新的待处理配额偏好设置。由于 Cloud Quotas API 是声明式 API，因此最新的配额偏好设置是系统尝试实现的目标。
这是一个示例响应：
"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"
}
]
此输出包括以下值：
PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
请求增加群组配额
如需请求增加新项目中的一组配额，请通过以下值将新项目的首选配额存储在 CSV 文件中：服务名称、配额 ID、首选配额值、维度。
对于 CSV 文件中的每一行，请将内容读取到字段 serviceName、quotaId、preferredValue 和 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);
将 PROJECT_NUMBER 替换为您的项目编号。
由于目标项目是新项目，因此在读取和分配字段时，可以安全地调用 CreateQuotaPreference 方法。或者，您可以调用 UpdateQuotaPreference 方法，其中将 allow_missing 设置为 true。
buildYourOwnQuotaPreferenceId 方法会根据命名方案，通过服务名称、配额 ID 和维度映射构建配额偏好设置 ID。或者，您可以选择不设置配额偏好设置 ID。系统会为您生成配额偏好设置 ID。
获取特定于服务的维度的配额信息
GPU 系列是特定于服务的维度。以下示例请求使用 GPUS-PER-GPU-FAMILY-per-project-region 配额 ID 获取 QuotaInfo 资源。
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region
将 PROJECT_NUMBER 替换为您的项目编号。
这是一个示例响应。对于每个唯一的 gpu_family 键，quotaValue 和 applicableLocations 是不同的：
"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"
]
}
]
此输出包括以下值：
PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。
为特定于服务的维度创建配额偏好设置
以下示例演示了如何为给定区域和 GPU 系列创建首选值为 100 的配额。目标位置在具有键 region 的维度映射以及具有键 gpu_family 的目标 GPU 系列中指定。
以下 CreateQuotaPreference 示例指定了 NVIDIA_H100 GPU 系列和 us-central1 区域。将 PROJECT_NUMBER 替换为您的项目编号。
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"
}
],
}
为特定于服务的维度更新配额偏好设置
以下示例代码获取维度 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} 的当前值，然后将首选值设为该值的两倍。将 PROJECT_NUMBER 替换为您的项目编号。
// 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);