このページは Cloud Translation API によって翻訳されました。

一般的なユースケースの実装

このページでは、Cloud Quotas API を使用して一般的なユースケースを実装する方法について説明します。この API を使用すると、Google Cloud のプロジェクト、フォルダ、組織での割り当てをプログラムで調整し、割り当ての調整を自動化できます。

詳細については、Cloud Quotas API の概要とリファレンスをご覧ください。

制限事項

Cloud Quotas API には次の制限があります。

この API は Google Cloud CLI をサポートしていません。
この API は、プロジェクトレベルの割り当ての調整をサポートしています。割り当ての減少は、プロジェクトレベル、フォルダレベル、組織レベルの割り当てに対してリクエストできます。
この API は VPC Service Controls をサポートしていません。

使用率を追跡し、使用率が 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"
                ]
            }
        ]
    },
      …
]

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

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
    }
}

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

使用率を確認するには、Cloud Monitoring API からのレスポンスを処理します。Cloud Monitoring の値と前の手順の quotaValue を比較して、使用状況を確認します。

次の例のレスポンスで、Cloud Monitoring の使用率の値は us-central1 リージョンで 19 です。すべてのリージョンの 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
    }
  }
}

この出力には次の値が含まれます。

PROJECT_ID: 実際のプロジェクトのグローバル固有識別子。

割り当て設定の重複を避けるには、まず 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": [
    "mapField": {
    "key": "region",
    "value": "us-central1"
    }
    ],
    }
```
この出力には次の値が含まれます。
- PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。
割り当て設定のディメンションを調整するには、次の操作を行います。
- 割り当て設定をすべてのリージョンに適用する場合は、リージョン情報を削除します。
- 割り当てがゾーンごとに定義されている場合は、リージョン情報をゾーン情報に置き換えます。
GetQuotaPreference を呼び出して、割り当て設定の変更ステータスを確認します。
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
```
PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。Google Cloud でリクエストされた割り当て値が評価されている間、調整ステータスは true になります。
```
"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": [
    "mapField": {
        "key": "region",
        "value": "us-central1"
    }
],
"reconciling": true
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
```
この出力には次の値が含まれます。
- PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。
割り当ての設定が処理されると、reconciling フィールドが false に設定されます。grantedValue は preferredValue と同じです。優先割り当てが完全に付与されます。

Google Cloud がユーザーのリクエストを拒否または部分的に承認した場合でも、付与される割り当て値が推奨値より小さくなる場合があります。

割り当てを減らす

次の例では、各リージョンの TPU の数を 10 に減らしています。

ListQuotaInfos を呼び出して、割り当て ID と現在の割り当て値を取得します。
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。

レスポンスフィールドを調べて、V2-TPUS-per-project-region の QuotaInfo エントリを見つけます。

"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"
                ]
            }
        ]
    },
      …
]

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

このレスポンスでは、割り当て ID は V2-TPUS-per-project-region で、現在の quotaValue は 20 です。

CreateQuotaPreferenceRequest を使用して、各リージョンの TPU 割り当てを 10 に減らします。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",
}
```
この出力には次の値が含まれます。
- PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

割り当て ID を V2-TPUS-per-project-region として定義する GetQuotaInfo 呼び出しで、新しい割り当て値を確認します。

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"
        ]
    }
]

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

割り当て設定を別のプロジェクトにコピーする

次の例では、プロジェクト間ですべての割り当て設定をコピーします。

ソースプロジェクトでフィルタを使用せずに 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())
        .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": [
            "map_field": {
                "key": "region",
                "value": "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"
    }
]

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

グループの割り当ての増加をリクエストする

新しいプロジェクトの割り当てグループの増加をリクエストするには、サービス名、割り当て ID、優先割り当て値、ディメンションの値を含む CSV ファイルに新しいプロジェクトの優先割り当てを保存します。

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)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。

ターゲットプロジェクトは新しいため、フィールドの読み取りと割り当てを行うときに CreateQuotaPreference メソッドを呼び出しても安全です。また、allow_missing を true に設定して UpdateQuotaPreference メソッドを呼び出すこともできます。

buildYourOwnQuotaPreferenceId メソッドは、サービス名、割り当て ID、命名規則に応じたディメンションのマップから割り当て設定 ID を作成します。また、割り当て設定 ID を設定しないようにすることもできます。割り当て設定 ID が生成されます。

サービス固有のディメンションの割り当て情報を取得する

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": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            },
            "mapField": {
                "key": "gpu_family",
                "value": "NVIDIA_H200"
            }
        ],
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "gpu_familly",
                "value": "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"
        ]
    }
]

この出力には次の値が含まれます。

PROJECT_NUMBER: プロジェクトに対して自動的に生成される固有識別子。

サービス固有のディメンションの割り当て設定を作成する

次の例は、特定のリージョンと GPU ファミリーの割り当てを優先値 100 で作成する方法を示しています。ターゲットロケーションは、キー region を使用してディメンションのマップに指定します。ターゲット GPU ファミリーは、キー gpu_family を使用して指定します。

次の CreateQuotaPreference の例では、GPU ファミリーとして NVIDIA_H100 を、リージョンとして us-central1 を指定しています。PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。

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": [
        "mapField": {
            "key": "region",
            "value": "us-central1"
        }
          "mapField": {
            "key": "gpu_family",
            "value": "NVIDIA_H100"
        }
    ],
}

サービス固有のディメンションの割り当て設定を更新する

次のサンプルコードでは、ディメンション {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} の現在値を取得し、優先値にその 2 倍の値を設定します。PROJECT_NUMBER は、プロジェクトのプロジェクト番号に置き換えます。

// 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)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

次のステップ

Cloud Quotas API について
Cloud Quotas API リファレンス
割り当てについて学習する