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 具有宣告性。您可以將配額設定視為程式碼，並將設定儲存在自己的版本控管系統中，以便查看記錄和回溯。

限制

Cloud Quotas 具有下列限制：

在大多數情況下，配額調高作業必須在專案層級進行。只有少數產品支援機構層級的配額調高調整。如要瞭解 Google Cloud 產品是否支援組織層級的配額調高調整，請參閱該產品的說明文件。
您可以要求調降專案、機構和資料夾層級的配額。

服務端點

服務端點是基本網址，可指定 API 服務的網路位址。一項服務可能有多個端點，Cloud Quotas API 服務的端點如下，所有 URI 都與此端點相關：

https://cloudquotas.googleapis.com

必要的角色

如要取得存取 cloudquotas_quotaPreferences、cloudquotas_quotaInfos 和 cloudquotas_quotaAdjusterSettings 資源所需的權限，請要求管理員授予您專案的 Cloud Quotas 管理員 (cloudquotas.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備存取 cloudquotas_quotaPreferences、cloudquotas_quotaInfos 和 cloudquotas_quotaAdjusterSettings 資源所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要存取 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:
    grantedValue: '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：系統自動為專案產生的專屬 ID。

回應會顯示 grantedValue 為 100，表示上一個範例中的 preferredValue 已獲准並完成。不同維度的偏好設定是不同的QuotaPreference資源。舉例來說，QuotaPreference 中 CPU 在 us-central1 和 us-east1 區域的配額是兩個不同的資源。

必須選取配額偏好設定

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：系統自動為專案產生的專屬 ID。

設定全域配額

下列 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：系統自動為專案產生的專屬 ID。

如要進一步瞭解 QuotaInfo 資源，請參閱 Cloud Quotas API 參考資料。

如要進一步瞭解 QuotaPreference 查詢，請參閱「實作常見用途」。

配額調整工具設定

QuotaAdjusterSettings 資源 (預覽版) 代表特定專案的配額調整器設定。啟用後，配額調整工具會監控指定資源的用量，並在資源用量接近配額值時，發出配額調整要求。

如要查看專案目前的配額調整器設定，請使用 GET 作業擷取 QuotaAdjusterSettings 資源。

如要為專案啟用配額調整工具，請使用 PATCH 作業設定下列 QuotaAdjusterSettings 資源選項：

  "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}

將 PROJECT_NUMBER 替換為專案的專屬 ID。

詳情請參閱「啟用配額調整工具」和「停用配額調整工具」。

資源名稱

資源是具名實體，並以資源名稱識別。所有要求和回應都會使用資源名稱，且每個資源都必須有自己的專屬資源名稱。每個資源名稱都是由一組欄位編碼而成。

配額偏好資源

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。您也可以呼叫 PATCH 方法並啟用 allow_missing 選項，藉此建立或更新 QuotaPreference。

配額資訊資源

QuotaInfo 資源的命名慣例採用下列模式：

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

配額調整工具設定資源

QuotaAdjusterSettings 資源的命名慣例採用下列模式：

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

後續步驟

實作常見用途
Cloud Quotas API 參考資料
瞭解配額

Cloud Quotas API 總覽 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

限制

服務端點

必要的角色

所需權限

API 資源模型

配額偏好

為區域設定偏好值

確認授予的值

gcloud

REST

必須選取配額偏好設定

配額資訊

依區域設定不同的配額值

設定全域配額

配額調整工具設定

資源名稱

配額偏好資源

配額資訊資源

配額調整工具設定資源

後續步驟

Cloud Quotas API 總覽