本页面介绍如何使用 Cloud Quotas API 实现常见应用场景。借助此 API，您能够在 Google Cloud 项目、文件夹或组织中以编程方式调整配额并自动执行配额调整。
如需了解详情，请参阅 Cloud Quotas API 概览和参考文档。
限制
Cloud 配额具有以下限制：
配额“增加”调整必须在项目级进行，并需要获得 Google Cloud 批准。
Cloud Quotas API 仅支持项目级操作。文件夹级和组织级操作不受支持。
跟踪用量，并在用量超过 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" ] } ] }, ... ]
- 调用 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" } }
- 如需确定您的用量，请处理来自 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 } } }
- 如需避免重复的配额偏好设置，请先调用
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": { "region": "us-central1" } }
- 调用
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": { "region": "us-central1" }, "reconciling": true, "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z"
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" ] } ] }, ... ]
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", "contactEmail": EMAIL }
- 使用将配额 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" ] } ]
将配额偏好设置复制到另一个项目
以下示例将所有配额偏好设置从一个项目复制到另一个项目。
- 在不使用过滤条件的情况下对源项目调用
ListQuotaPreferences：GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
- 对于响应中的每个配额偏好设置，请调用
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": { "region": "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" } ]
请求增加群组配额
如需请求增加新项目中的一组配额，请通过以下值将新项目的首选配额存储在 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。
请求调整无用量配额
对于尚未有配额用量且具有服务专属维度（例如 vm_family）的配额，这些配额可能无法显示在 Google Cloud 控制台中。您可能需要改用 Cloud Quotas API。
例如，您可以克隆项目并提前知道需要增加 compute.googleapis.com/gpus_per_gpu_family 的值。此值仅会针对您已使用的 GPU 系列显示在 Google Cloud 控制台中。如需使用 Cloud Quotas API 请求增加 us-central1 中的 NVIDIA_H100 GPU，您可以发送如下请求：
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": { "region": "us-central1", "gpu_family": "NVIDIA_H100" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}
替换以下内容：
PROJECT_NUMBER：您的项目的唯一标识符。JUSTIFICATION：此请求的原因。EMAIL：可用作联系人的电子邮件地址（如果 Google Cloud 需要更多信息来做出决定，然后才能授予额外的配额）。
获取特定于服务的维度的配额信息
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": { "region": "us-central1", "gpu_family": "NVIDIA_H200" }, "details": { "quotaValue": 30, "resetValue": 30, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": { "region": "us-central1" } "details": { "quotaValue": 100, "resetValue": 100, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": { "gpu_familly": "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" ] } ]
为特定于服务的维度创建配额偏好设置
以下示例演示了如何为给定区域和 GPU 系列创建首选值为 100 的配额。目标位置在具有键 region 的维度映射以及具有键 gpu_family 的目标 GPU 系列中指定。
以下 CreateQuotaPreference 示例指定了 NVIDIA_H100 GPU 系列和 us-central1 区域。
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": {"region": "us-central1", "gpu_family": "NVIDIA_H100"}, "contactEmail": EMAIL" }
替换以下内容：
PROJECT_NUMBER：您的项目的唯一标识符。EMAIL：可用作联系人的电子邮件地址（如果 Google Cloud 需要更多信息来做出决定，然后才能授予额外的配额）。
为特定于服务的维度更新配额偏好设置
以下示例代码获取维度 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, 的当前值，然后将首选值设为该值的两倍。
// 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);
将 PROJECT_NUMBER 替换为您的项目的唯一标识符。