Panoramica dell'API Cloud Quotas

L'API Cloud Quotas ti consente di regolare in modo programmatico le quotas e automatizzare gli aggiustamenti delle quote a livello di progetto. L'API Cloud Quotas può essere utilizzata per:

Automatizzare gli aggiustamenti delle quote
Puoi utilizzare l'API Cloud Quotas per richiedere aumenti della quota quando vengono soddisfatte determinate condizioni. Ad esempio, per evitare errori di superamento della quota, puoi utilizzare l'API per richiedere in modo programmatico un aumento della quota quando le risorse Compute Engine raggiungono l'80% della quota disponibile.
Scala le configurazioni delle quote tra progetti
L'API Cloud Quotas può clonare le configurazioni delle tue quote da un progetto all'altro. Se è presente un insieme noto di quote che deve essere aumentato per ogni nuovo progetto Google Cloud, puoi integrare l'API nella logica di creazione del progetto per richiedere automaticamente un aumento della quota. Tutti gli aumenti della quota sono soggetti ad approvazione di Google Cloud.
Gestire le richieste di quota dei clienti
Se sei un provider SaaS integrato con Google Cloud, potresti ricevere richieste di aumento delle quote tramite un portale rivolto ai clienti diverso dalla console Google Cloud. Queste richieste devono essere inoltrate a Google Cloud per l'elaborazione. L'API Cloud Quotas può inoltrare automaticamente le richieste dei clienti.
Abilita il controllo della versione della configurazione del client
L'API Cloud Quotas è dichiarativa: puoi trattare le configurazioni delle quote come configurazioni di codice e di archiviazione nel tuo sistema controllato dalla versione per cronologia e rollback.

Limitazioni

Cloud Quotas presenta le seguenti limitazioni:

  • Tutti gli aggiustamenti relativi all'aumento della quota sono soggetti all'approvazione di Google Cloud.

  • Puoi richiedere aggiustamenti di aumento e riduzione della quota per le quote a livello di progetto.

  • Puoi richiedere aggiustamenti delle diminuzioni delle quote per le quote a livello di project-, folder- e organizzazione.

Endpoint di servizio

L'endpoint di servizio è un URL di base che specifica l'indirizzo di rete di un servizio API. Un servizio può avere più endpoint. Il servizio API Cloud Quotas ha il seguente endpoint e tutti gli URI sono relativi:

https://cloudquotas.googleapis.com

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per accedere alle risorse cloudquotas_quotaPreferences e cloudquotas_quotaInfos, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Cloud Quotas (cloudquotas.admin) per il progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questo ruolo predefinito contiene le autorizzazioni necessarie per accedere alle risorse cloudquotas_quotaPreferences e cloudquotas_quotaInfos. Per visualizzare esattamente le autorizzazioni necessarie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per accedere alle risorse cloudquotas_quotaPreferences e cloudquotas_quotaInfos sono necessarie le seguenti autorizzazioni:

  • cloudquotas.quotas.update
  • cloudquotas.quotas.get
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

Potresti anche riuscire a ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.

Modello di risorsa API

Il modello di risorse dell'API Cloud Quotas è composto da due risorse: QuotaPreference e QuotaInfo.

Preferenza quota

La risorsa QuotaPreference rappresenta la preferenza di quota per una particolare combinazione di dimensioni. Utilizza questa risorsa per modificare le quote nei progetti, nelle cartelle o nelle organizzazioni.

Imposta un valore preferito per una regione

L'esempio seguente mostra una risorsa QuotaPreference in un metodo CreateQuotaPreference.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

preferredValue di 100 indica che il richiedente vuole che la quota GPUS-PER-GPU-FAMILY-per-project-region sia impostata su quel valore. Il campo Dimensioni indica che la preferenza si applica solo alla regione us-central1.

Verifica il valore concesso

L'esempio seguente mostra una risorsa QuotaPreference in un metodo GetQuotaPreference.

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

Questo output include i seguenti valori:

  • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

La risposta mostra un grantedValue di 100, il che significa che il preferredValue dell'esempio precedente è stato approvato e soddisfatto. Le preferenze per le varie dimensioni sono risorse QuotaPreference diverse. Ad esempio, QuotaPreference per la CPU nelle regioni us-central1 e us-east1 sono due risorse distinte.

La preferenza per la quota è obbligatoria

Le risorse QuotaPreference vengono utilizzate per indicare il valore preferito per una determinata quota. Il valore corrente di una determinata quota si basa su:

  • QuotaPreference richieste effettuate da te.

  • Richieste di aumento della quota approvate da Google Cloud.

  • Modifiche alle quote avviate da Google Cloud.

La possibilità di eliminare un QuotaPreference non è supportata. Tuttavia, puoi impostare un valore di quota preferita inferiore al valore approvato da Google Cloud per aggiungere ulteriori sistemi di protezione.

Per saperne di più sulla risorsa QuotaPreference, consulta la documentazione sull'API Cloud Quotas.

Per maggiori informazioni sulle query QuotaPreference, consulta Implementare casi d'uso comuni.

Informazioni sulla quota

QuotaInfo è una risorsa di sola lettura che fornisce informazioni su una determinata quota per un determinato progetto, cartella o organizzazione. Visualizza le informazioni sulle quote definite dai servizi Google Cloud e su eventuali aggiustamenti delle quote completati e avviati dai clienti. La risorsa QuotaInfo contiene informazioni come metadati, tipo di container e dimensione.

Impostare valori di quota diversi in base alla regione

Il seguente esempio di risorsa QuotaInfo mostra che la quota di CPU per il progetto è 200 per la regione us-central1 e 100 per tutte le altre regioni.

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

Questo output include i seguenti valori:

  • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

Imposta una quota globale

Il seguente esempio di risorsa QuotaInfo mostra una quota di frequenza con un intervallo di aggiornamento al minuto. Le dimensioni sono vuote, a indicare che si tratta di una quota globale. Tutte le quote senza una dimensione regione o zona sono globali.

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

Questo output include i seguenti valori:

  • PROJECT_NUMBER: un identificatore univoco generato automaticamente per il progetto.

Per maggiori dettagli sulla risorsa QuotaInfo, consulta la documentazione sull'API Cloud Quotas.

Per maggiori dettagli sulle query QuotaPreference, consulta Implementare casi d'uso comuni.

Nomi delle risorse

Le risorse sono entità denominate e sono identificate dai nomi delle risorse. I nomi delle risorse vengono utilizzati in tutte le richieste e le risposte e ogni risorsa deve avere un proprio nome risorsa univoco. Ogni nome di risorsa è codificato da un insieme di campi.

Risorsa preferenza quota

La convenzione di denominazione per una risorsa QuotaPreference utilizza il seguente pattern:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Puoi impostare quotaPreferenceId quando crei una preferenza di quota, altrimenti viene generato un ID. È consigliabile che uno schema di denominazione quotaPreferenceId codifichi il nome del servizio, l'ID quota, la località e altre dimensioni. quotaPreferenceId deve essere univoco per il progetto, la cartella o le organizzazioni.

Ad esempio, quotaPreference Un pattern per codificare il tuo ID preferenza di quota è il seguente: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

L'esempio seguente dimostra questo pattern: 

compute_us-central1_nvidia-200

Con un nome risorsa, devi utilizzare il metodo GET per recuperare un QuotaPreference. Puoi anche chiamare il metodo UPDATE con l'opzione allow_missing abilitata per creare o aggiornare un QuotaPreference.

Risorsa informazioni sulla quota

La convenzione di denominazione per una risorsa QuotaInfo utilizza il seguente pattern:

projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID

Precedenza dimensioni

Alcuni casi d'uso dell'API Cloud Quotas prevedono configurazioni di dimensioni complesse. Le quote possono essere configurate a un livello più granulare rispetto alle sole regioni e zone. Puoi ottenere questo livello di granularità quando utilizzi dimensioni specifiche del servizio. Ad esempio, gpu_family e network_id sono dimensioni specifiche del servizio Compute Engine. Le dimensioni sono definite da ogni singolo servizio e ogni servizio potrebbe avere un insieme diverso di dimensioni specifiche del servizio.

Quando lavori con dimensioni relative alla località o dimensioni specifiche per i servizi, viene applicata la seguente precedenza:

  1. Una configurazione di preferenze di quota in cui sono specificate tutte le dimensioni specifiche per località e servizio ha la precedenza su qualsiasi altra configurazione.

  2. Le configurazioni che specificano dimensioni relative alla località hanno la precedenza solo su quelle che contengono solo dimensioni specifiche del servizio.

Combinazione di dimensioni

In una configurazione di preferenza di quota, puoi combinare le dimensioni nei seguenti modi:

  1. La configurazione può contenere sia dimensioni relative alla località sia dimensioni specifiche per il servizio. Si tratta dell'ordine di precedenza più alto.

  2. La configurazione può contenere solo le dimensioni relative alla località. Questa configurazione si applica a tutte le dimensioni specifiche del servizio, ad eccezione di quelle configurate esplicitamente con il metodo 1.

  3. La configurazione può contenere solo dimensioni specifiche del servizio. Questa configurazione si applica a tutte le località, ad eccezione di quelle configurate esplicitamente con il metodo 1 o 2.

  4. Se la configurazione contiene qualsiasi dimensione specifica del servizio, deve contenere tutte le dimensioni specifiche del servizio.

  5. Puoi avere configurazioni senza dimensioni. Queste configurazioni si applicano a tutte le località e a tutte le dimensioni specifiche del servizio, tranne quelle configurate esplicitamente.

Che cosa succede dopo?