本文說明如何使用 Cloud Quotas API 實作常見用途。透過這項 API，您可以利用程式調整配額，並自動調整配額 Trusted Cloud by S3NS 專案、資料夾或機構的配額。
詳情請參閱 Cloud Quotas API 的總覽和參考資料。
限制
Cloud Quotas 具有下列限制：
在大多數情況下，配額調高調整作業必須在專案層級進行。只有少數產品支援機構層級的配額調高調整。如要確認 Trusted Cloud by S3NS 產品是否支援組織層級的配額提高調整，請參閱該產品的說明文件。
您可以要求調降專案、機構和資料夾層級的配額。
追蹤用量，並在用量超過 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：如果 Trusted Cloud by S3NS 需要更多資訊才能核發額外配額，可將這個電子郵件地址做為聯絡方式。
呼叫
GetQuotaPreference，查看配額偏好設定變更的狀態：GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1將
PROJECT_NUMBER替換為專案的專案編號。Trusted Cloud by S3NS 評估要求的配額值時，配額的對帳狀態會設為
true。有時 Trusted Cloud by S3NS 不會完全核准您的要求，而是只核准部分要求。如果要求部分獲准，配額偏好設定會包含
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相同。系統已完全核准偏好配額。當 Trusted Cloud by S3NS 拒絕或部分核准客戶要求時，核准的配額值仍可能低於偏好值。
調降配額
以下範例會將每個區域的 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：如果 Trusted Cloud by S3NS 需要更多資訊才能核發額外配額，可將這個電子郵件地址做為聯絡方式。
使用
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/quotaPreferencesPROJECT_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)，則這些配額可能不會顯示在 Trusted Cloud 控制台中。您可能需要改用 Cloud Quotas API。
舉例來說，您可能會複製專案，並事先知道需要增加 compute.googleapis.com/gpus_per_gpu_family 的值。這個值只會顯示在 Trusted 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：如果 Trusted Cloud by S3NS 需要更多資訊才能核發額外配額，這個電子郵件地址可用於聯絡。
取得特定服務維度的配額資訊
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：如果 Trusted Cloud by S3NS 需要更多資訊才能核發額外配額，這個電子郵件地址可用於聯絡。
更新特定服務維度的配額偏好設定
下列程式碼範例會取得維度 {"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。