Cloud Quotas API 概览

借助 Cloud Quotas API，您能够在项目级层以程序化方式调整配额并自动执行配额调整。Cloud Quotas API 可用于：

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

限制

Cloud Quotas API 具有以下限制：

该 API 不支持 Google Cloud CLI。
该 API 不支持针对文件夹级和组织级配额的配额增加请求。

服务端点

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

https://cloudquotas.googleapis.com

所需的角色

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

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

所需权限

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

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。

验证授予的值

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

{
    "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 查询，请参阅实现常见使用场景。

资源名称

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

配额偏好设置资源

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 选项的情况下调用 UPDATE 方法以创建或更新 QuotaPreference。

配额信息资源

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

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

维度优先级

Cloud Quotas API 的某些应用场景具有复杂的维度设置。配额可以在更精细的级别上进行配置，而不仅仅是按区域和可区域。使用特定于服务的维度时，您可以实现这种细化程度。例如，gpu_family 和 network_id 是 Compute Engine 服务中特定于服务的维度。维度由每种服务定义，且每种服务可能具有一组不同的特定于服务的维度。

在处理位置维度或特定于服务的维度时，系统会采用以下优先级：

指定了所有位置维度和特定于服务的维度的配额偏好设置配置优先于任何其他配置。
仅指定位置维度的配置优先于仅包含特定于服务的维度的配置。

组合维度

在配额偏好设置配置中，您可以通过以下方式组合多个维度：

配置可以同时包含位置维度和特定于服务的维度。这是优先级最高的配置。
配置可以仅包含位置维度。此配置适用于所有特定于服务的维度（通过方法 1 明确配置的维度除外）。
配置可以仅包含特定于服务的维度。此配置适用于所有位置（通过方法 1 或方法 2 明确配置的位置除外）。
如果配置包含任何特定于服务的维度，则必须包含所有特定于服务的维度。
您的配置可以没有任何维度。此类配置适用于所有位置和所有特定于服务的维度（明确配置的维度除外）。

Cloud Quotas API 概览

限制

服务端点

所需的角色

所需权限

API 资源模型

配额偏好设置

设置区域的首选值

验证授予的值

配额偏好设置为必填项

配额信息

按区域设置不同的配额值

设置全球配额

资源名称

配额偏好设置资源

配额信息资源

维度优先级

组合维度

后续步骤