此页面由 Cloud Translation API 翻译。

Cloud Quotas API 概览

借助 Cloud Quotas API，您能够以编程方式调整项目级配额并自动执行项目级配额调整请求。例如，您可以使用 Cloud Quotas API 执行以下操作：

自动调整配额：您可以使用 Cloud Quotas API 来根据您自己的条件申请配额调整。例如，为了避免超出配额错误，您可以在 Compute Engine 资源达到可用配额的 80% 时使用该 API 以编程方式申请配额调整。
在各个项目中重复使用配额配置：Cloud Quotas API 可以在项目之间克隆配额配置。如果对每个新的 Google Cloud 项目都需要增加一组已知的配额，您可以使用 Cloud Quotas API 在项目的创建逻辑中自动执行此操作。配额调整请求需要获得 Google Cloud 批准。
处理客户配额请求：如果您是与Google Cloud集成的 SaaS 提供商，可以通过面向客户的门户（除 Google Cloud 控制台以外）接收配额增加请求。这些请求必须转发到 Google Cloud 进行处理。Cloud Quotas API 可以自动转发客户请求。
启用客户端配置版本控制：Cloud Quotas API 是声明式 API。您可以将配额配置视为代码，并将配置存储在您自己的版本控制系统中，以实现历史记录和回滚。

限制

Cloud 配额具有以下限制：

在大多数情况下，配额“增加”调整必须在项目级进行。只有少数产品支持组织级配额增加调整。如需了解某个 Google Cloud 产品是否支持组织级配额增加调整，请参阅该产品的文档。
您可以针对项目、组织和文件夹级配额请求配额减少调整。
Cloud Quotas API 仅支持项目级操作。文件夹级和组织级操作不受支持。

服务端点

服务端点是指定 API 服务的网络地址的基础网址。一个服务可能有多个端点。Cloud Quotas API 服务具有以下端点，所有 URI 都与它相关：

https://cloudquotas.googleapis.com

所需的角色

如需获得访问 cloudquotas_quotaPreferences、cloudquotas_quotaInfos 和 cloudquotas_quotaAdjusterSettings 资源所需的权限，请让您的管理员为您授予项目的 Cloud Quotas Admin (cloudquotas.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供访问 cloudquotas_quotaPreferences、cloudquotas_quotaInfos 和 cloudquotas_quotaAdjusterSettings 资源所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

访问 cloudquotas_quotaPreferences、cloudquotas_quotaInfos 和 cloudquotas_quotaAdjusterSettings 资源需要以下权限：

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

您也可以使用自定义角色或其他预定义角色来获取这些权限。

API 资源模型

Cloud Quotas API 资源模型由两个资源组成：QuotaPreference 和 QuotaInfo。

配额偏好设置

QuotaPreference 资源表示特定维度组合的配额偏好设置。使用此资源可在项目、文件夹或组织中调整配额。

设置区域的首选值

以下示例展示了 CreateQuotaPreference 方法中的 QuotaPreference 资源。

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

preferredValue 为 100 表示请求者希望将 GPUS-PER-GPU-FAMILY-per-project-region 配额设置为该值。维度字段表示偏好设置仅适用于区域 us-central1。

验证授予的值

查看您的配额偏好设置，并查看 grantedValue 字段以验证授予的值。

如需使用 Google Cloud CLI 查看配额偏好设置，请在终端中运行以下命令：

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

替换以下内容：

QUOTA_PREFERENCE_ID：配额偏好设置的 ID。这是在创建配额偏好设置时指定的值。
PROJECT：您的 Google Cloud项目的 ID 或编号。

如果您发出了配额调整请求，并且该请求已部分获批，则 grantedValue 字段后面会显示 stateDetail 字段。grantedValue 显示所做的调整，stateDetail 字段描述部分获批的状态。

如需查看授予的值是否为最终批准的值，请查看 reconciling 字段。如果您的请求仍在接受评估，则 reconciling 字段会设置为 true。如果 reconciling 字段设置为 false 或省略，则授予的值是最终批准的值。

以下代码段展示了配额偏好设置对象的示例。它们使用 ID 为 compute_googleapis_com-gpus-us-central1 的演示配额偏好设置。

gcloud

如果您使用 gcloud CLI 查看配额偏好设置，输出内容如下所示：

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

如果您使用 Cloud Quotas API 查看配额偏好设置，输出内容如下所示：

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

此输出包括以下值：

PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。

响应显示 grantedValue 为 100，表示上一个示例中的 preferredValue 已经过批准并完成。不同维度的偏好设置是不同的 QuotaPreference 资源。例如，区域 us-central1 和 us-east1 中针对 CPU 的 QuotaPreference 是两个不同的资源。

配额偏好设置为必填项

QuotaPreference 资源用于表示特定配额的首选值。特定配额的当前值基于：

您发出的 QuotaPreference 请求。
Google Cloud批准的配额增加请求。
由 Google Cloud发起的配额更改。

系统不支持删除 QuotaPreference。但是，您可以设置低于 Google Cloud 批准值的首选配额值，以添加额外一层保护。

如需详细了解 QuotaPreference 资源，请参阅 Cloud Quotas API 参考文档。

如需详细了解 QuotaPreference 查询，请参阅实现常见使用场景。

配额信息

QuotaInfo 是一种只读资源，用于提供与给定项目、文件夹或组织的特定配额相关的信息。它会显示 Google Cloud 服务定义的配额中的信息，以及客户发起的任何已完成配额调整。QuotaInfo 资源包含元数据、容器类型和维度等信息。

按区域设置不同的配额值

以下 QuotaInfo 资源示例显示，项目的 CPU 配额对于 us-central1 为 200，对于所有其他区域为 100。

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

此输出包括以下值：

PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。

设置全球配额

以下 QuotaInfo 资源示例显示了具有每分钟刷新间隔时间的速率配额。维度为空，表示这是全球配额。所有没有区域或可用区维度的配额都是全球配额。

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

此输出包括以下值：

PROJECT_NUMBER：系统为您的项目自动生成的唯一标识符。

如需详细了解 QuotaInfo 资源，请参阅 Cloud Quotas API 参考文档。

如需详细了解 QuotaPreference 查询，请参阅实现常见使用场景。

配额调整工具设置

QuotaAdjusterSettings 资源（预览）表示特定项目的配额调整工具设置。启用配额调整工具后，该工具会监控您对指定资源的用量，并在资源用量接近配额值时发出配额调整请求。

如需查看项目的当前配额调整工具设置，请使用 GET 操作检索 QuotaAdjusterSettings 资源。
如需为项目启用配额调整工具，请使用 PATCH 操作设置以下 QuotaAdjusterSettings 资源选项：
```
  "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}
```
将 PROJECT_NUMBER 替换为您的项目的唯一标识符。

有关详情，请参阅启用配额调整工具和停用配额调整工具。

资源名称

资源是命名的实体，由资源名称标识。资源名称在所有请求和响应中使用，每个资源都必须有自己的唯一资源名称。每个资源名称都通过一组字段进行编码。

配额偏好设置资源

QuotaPreference 资源的命名惯例使用以下格式：

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

您可以在创建配额偏好设置时设置 quotaPreferenceId，否则系统会生成一个 ID。建议使用 quotaPreferenceId 命名方案对服务名称、配额 ID、位置和其他维度进行编码。quotaPreferenceId 对项目、文件夹或组织必须是唯一的。

例如，一种用于对配额偏好设置 ID 进行编码的 quotaPreference 格式如下所示：

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

以下示例体现了此格式：

compute_us-central1_nvidia-200

资源名称中的 location 字段始终为 global。Cloud Quotas API 是一项全球服务。

使用资源名称时，您应使用 GET 方法检索 QuotaPreference。您也可以在启用 allow_missing 选项的情况下调用 PATCH 方法以创建或更新 QuotaPreference。

配额信息资源

QuotaInfo 资源的命名惯例使用以下格式：

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

配额调整工具设置资源

QuotaAdjusterSettings 资源的命名惯例使用以下格式：

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

Cloud Quotas API 概览

限制

服务端点

所需的角色

所需权限

API 资源模型

配额偏好设置

设置区域的首选值

验证授予的值

gcloud

REST

配额偏好设置为必填项

配额信息

按区域设置不同的配额值

设置全球配额

配额调整工具设置

资源名称

配额偏好设置资源

配额信息资源

配额调整工具设置资源

后续步骤