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 仅支持项目级操作。文件夹级和组织级操作不受支持。

  • 在 Google Cloud 控制台中，配额和系统限制页面不支持通过 Edit 按钮为配额调整请求选择地区或区域。如需在 Google Cloud 控制台中调整地区级或区域级配额，请参阅有关如何申请更高配额的说明。

服务端点

服务端点是指定 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

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

配额信息资源

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

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

后续步骤