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 での承認が必要です。
Cloud Quotas API は、プロジェクト レベルのオペレーションのみをサポートしています。フォルダレベルと組織レベルのオペレーションはサポートされていません。
サービス エンドポイント
サービス エンドポイントは、API サービスのネットワーク アドレスを指定するベース URL です。1 つのサービスに複数のエンドポイントが存在する場合があります。Cloud Quotas API サービスには次のエンドポイントがあり、すべての URI はこのエンドポイントを基準とします。
https://cloudquotas.googleapis.com
必要なロール
cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするための権限を取得するには、プロジェクトに対する Cloud Quotas 管理者（cloudquotas.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
cloudquotas_quotaPreferences リソースと cloudquotas_quotaInfos リソースにアクセスするには、次の権限が必要です。
-
cloudquotas.quotas.update -
cloudquotas.quotas.get -
monitoring.timeSeries.list -
resourcemanager.projects.get -
resourcemanager.projects.list
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
API リソースモデル
Cloud Quotas API リソースモデルは、QuotaPreference と QuotaInfo の 2 つのリソースで構成されています。
割り当ての設定
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 にのみ適用されることを示しています。
付与された値を確認する
次の例は、GetQuotaPreference メソッドの QuotaPreference リソースを示しています。
{ "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: プロジェクトに対して自動的に生成される固有識別子。
レスポンスで grantedValue が 100 になっています。これは、前の例の preferredValue が承認され、履行されたことを意味します。ディメンションごとに異なる QuotaPreference リソースが設定されています。たとえば、リージョン us-central1 と us-east1 の CPU の QuotaPreference は 2 つの異なるリソースです。
割り当ての設定は必須
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: プロジェクトに対して自動的に生成される固有識別子。
グローバル割り当てを設定する
次の QuotaInfo リソースの例は、1 分あたりの更新間隔が設定された、レートに基づく割り当てを示しています。ディメンションは空白です。これは、グローバル割り当てであることを示します。リージョンまたはゾーンのディメンションがない割り当てはすべてグローバルです。
{ "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: プロジェクトに対して自動的に生成される固有識別子。
QuotaInfo リソースの詳細については、Cloud Quotas API リファレンスをご覧ください。
QuotaPreference クエリの詳細については、一般的なユースケースの実装をご覧ください。
リソース名
リソースは名前付きエンティティであり、リソース名で識別されます。リソース名はすべてのリクエストとレスポンスで使用されます。各リソースには独自の一意のリソース名が必要です。各リソース名は一連のフィールドによってエンコードされます。
割り当て設定リソース
QuotaPreference リソースの命名規則では、次のパターンを使用します。
projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID
割り当て設定を作成するときに quotaPreferenceId を設定できます。設定しない場合は、ID が生成されます。quotaPreferenceId 命名規則では、サービス名、割り当て ID、ロケーションなどのディメンションをエンコードすることをおすすめします。quotaPreferenceId は、プロジェクト、フォルダ、または組織に対して一意である必要があります。
たとえば、quotaPreference の場合、割り当て設定 ID をエンコードするパターンは次のとおりです。
SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER
次の例は、このパターンを示しています。
compute_us-central1_nvidia-200
リソース名の場合、GET メソッドを使用して QuotaPreference を取得する必要があります。allow_missing オプションを有効にして UPDATE メソッドを呼び出し、QuotaPreference を作成または更新することもできます。
割り当て情報リソース
QuotaInfo リソースの命名規則では、次のパターンを使用します。
projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID