實作常見用途

本頁說明如何使用 Cloud Quotas API 實作常見用途。透過這項 API,您可以利用程式調整配額,並自動調整配額 Google Cloud 專案、資料夾或機構的配額。

詳情請參閱 Cloud Quotas API 的總覽參考資料

限制

Cloud Quotas 具有下列限制:

  • 在大多數情況下,配額調高調整作業必須在專案層級進行。只有少數產品支援機構層級配額調高調整。如要確認 Google Cloud 產品是否支援組織層級的配額提高調整,請參閱該產品的說明文件。

  • 您可以要求調降專案、機構和資料夾層級的配額。

追蹤用量,並在用量超過 80% 時要求增加配額

這個範例會使用 Cloud Monitoring 追蹤配額用量,並在用量超過 80% 時申請增加配額。

  1. 請呼叫服務的 QuotaInfo資源,判斷目前的 quotaValue。本範例中的服務為 compute.googleapis.com

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    PROJECT_NUMBER 替換為專案的專案編號。

  2. 如要找出每個專案的 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"
                  ]
              }
          ]
      },
      ...
    ]
  3. 呼叫 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"
      }
    }
  4. 如要判斷用量,請處理 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
      }
    }
    }
  5. 為避免重複設定配額偏好設定,請先呼叫 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 替換為專案的專案編號。

  6. 請撥打 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 需要更多資訊才能核發額外配額,可將這個電子郵件地址做為聯絡方式。
  7. 呼叫 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 欄位會設為 falsegrantedValuepreferredValue 相同。系統已完全核准偏好配額。

    當 Google Cloud 拒絕或部分核准客戶要求時,核准的配額值仍可能低於偏好值。

調降配額

以下範例會將每個區域的 TPU 數量減少至 10 個。

  1. 使用 ListQuotaInfos 呼叫取得配額 ID 和目前的配額值:

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    PROJECT_NUMBER 替換為專案的專案編號。

  2. 查看回應欄位,找出 QuotaInfoV2-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。

  3. 將各區域的 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 需要更多資訊才能核發額外配額,可將這個電子郵件地址做為聯絡方式。
  4. 使用 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 編寫,但您可以使用任何程式設計語言。

  1. 在來源專案上呼叫 ListQuotaPreferences,不使用任何篩選器:

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 是來源專案的專案號碼。回應包含來源專案的所有配額偏好設定。

  2. 針對回應中的每個配額偏好設定,呼叫 UpdateQuotaPreference 並定義下列欄位:

    • name:更新後的名稱欄位取自回應,且來源專案編號 (PROJECT_NUMBER1) 會替換為目的地專案編號 (PROJECT_NUMBER2)。

    • servicequotaIdpreferredValuedimensions - 這些欄位可直接從回應中取得。

    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);
    }
  3. 呼叫 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 檔案中的每個資料列,將內容讀取至 serviceNamequotaIdpreferredValuedimensionMap 欄位。

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 鍵,quotaValueapplicableLocations 都不相同:

"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。

後續步驟