本頁說明如何使用 Cloud Quotas API 實作常見用途。透過這項 API,您可以利用程式調整配額,並自動調整配額 Google Cloud 專案、資料夾或機構的配額。
詳情請參閱 Cloud Quotas API 的總覽和參考資料。
限制
Cloud Quotas 具有下列限制:
在大多數情況下,配額調高調整作業必須在專案層級進行。只有少數產品支援機構層級配額調高調整。如要確認 Google Cloud 產品是否支援組織層級的配額提高調整,請參閱該產品的說明文件。
您可以要求調降專案、機構和資料夾層級的配額。
追蹤用量,並在用量超過 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 的用量值為 19,位於
us-central1
區域。所有區域的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" }, "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
更改下列內容:
PROJECT_NUMBER
:專案的專屬 ID。JUSTIFICATION
:說明要求的選用字串。EMAIL
:如果 Google Cloud 需要更多資訊才能核發額外配額,可將這個電子郵件地址做為聯絡方式。
呼叫
GetQuotaPreference
,查看配額偏好設定變更的狀態:GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
將
PROJECT_NUMBER
替換為專案的專案編號。Google Cloud 評估要求的配額值時,配額的對帳狀態會設為
true
。有時 Google Cloud 不會完全核准您的要求,而是只核准部分要求。如果要求部分獲准,配額偏好設定會包含
stateDetail
欄位。stateDetail
欄位說明部分核准狀態。「grantedValue
」欄位會顯示為部分滿足要求而進行的調整。如要查看核准的最終值是否為授予的值,請查看
reconciling
欄位。如果要求仍在評估中,reconciling
欄位會設為true
。如果reconciling
欄位設為false
或省略,則核准值為最終值。在下列範例中,要求的配額值為 100,而
reconciling
欄位表示要求正在審查中。"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
替換為專案的專案編號。查看回應欄位,找出
QuotaInfo
的V2-TPUS-per-project-region
項目。"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" ] } ] }, ... ]
在這個回應中,配額 ID 為
V2-TPUS-per-project-region
,目前的quotaValue
為 20。將各區域的 TPU 配額減少至 10 個,並使用
CreateQuotaPreferenceRequest
。 將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", "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
更改下列內容:
PROJECT_NUMBER
:專案的專屬 ID。JUSTIFICATION
:說明要求的選用字串。EMAIL
:如果 Google Cloud 需要更多資訊才能核發額外配額,可將這個電子郵件地址做為聯絡方式。
使用
GetQuotaInfo
呼叫確認新的配額值,將配額 ID 定義為V2-TPUS-per-project-region
。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" ] } ]
將配額偏好設定複製到其他專案
以下範例會將配額偏好設定從一個專案複製到另一個專案。這項服務是以 Java 編寫,但您可以使用任何程式設計語言。
在來源專案上呼叫
ListQuotaPreferences
,不使用任何篩選器:GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
PROJECT_NUMBER1 是來源專案的專案號碼。回應包含來源專案的所有配額偏好設定。
針對回應中的每個配額偏好設定,呼叫
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()) .setJustification(srcPreference.getJustification()) .setContactEmail(srcPreference.getContactEmail()) .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) .setJustification(justification) .setContactEmail(contactEmail) .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
的值。這個值只會顯示在 Google Cloud 主控台中,適用於您已使用的 GPU 系列。如要使用 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
:專案的專屬 ID。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 系列則是以 gpu_family
鍵指定。
下列 CreateQuotaPreference
範例指定 GPU 系列為 NVIDIA_H100
,區域為 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"}, "justification": "JUSTIFICATION", "contactEmail": ""EMAIL" }
更改下列內容:
PROJECT_NUMBER
:專案的專屬 ID。JUSTIFICATION
:說明要求的選用字串。EMAIL
:如果 Google Cloud 需要更多資訊才能核發額外配額,這個電子郵件地址可用於聯絡。
更新特定服務維度的配額偏好設定
下列程式碼範例會取得維度 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"},
的目前值,然後將偏好值設為該值的兩倍。這項服務是以 Java 編寫,但您可以使用任何程式設計語言。
// 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) .setJustification(justification) .setContactEmail(contactEmail) .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2)) .putAllDimensions(targetDimensions)); UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder() .setQuotaPreference(targetPreference) .setAllowMissing(true) .build(); cloudQuotas.updateQuotaPreference(updateRequest);
將 PROJECT_NUMBER
替換為專案的專屬 ID。