Panoramica dell'API Cloud Quotas

L'API Cloud Quotas consente di modificare in modo programmatico le quote a livello di progetto e automatizzare le richieste di modifica delle quote a livello di progetto. Ad esempio, puoi utilizzare l'API Cloud Quotas per:

  • Automatizzare le modifiche delle quote: puoi utilizzare l'API Cloud Quotas per richiedere modifiche delle quote in base ai tuoi criteri. Ad esempio, per evitare errori di superamento della quota, puoi utilizzare l'API per richiedere in modo programmatico una modifica della quota quando le risorse di Compute Engine raggiungono l'80% della quota disponibile.

  • Riutilizzare le configurazioni delle quote tra i progetti: l'API Cloud Quotas può clonare le configurazioni delle quote da un progetto all'altro. Se esiste un insieme noto di quote che devono essere aumentate per ogni nuovo Google Cloud progetto, puoi utilizzare l'API Cloud Quotas per automatizzare questa operazione nella logica di creazione del progetto. Le richieste di modifica delle quote sono soggette ad Google Cloud approvazione.

  • Gestire le richieste di quote dei clienti: se sei un fornitore SaaS integrato con Google Cloud, potresti ricevere richieste di aumento delle quote tramite un portale rivolto ai clienti diverso dalla Google Cloud console. Queste richieste devono essere inoltrate a Google Cloud per l'elaborazione. L'API Cloud Quotas può inoltrare automaticamente le richieste dei clienti.

  • Abilitare il controllo delle versioni della configurazione del client: l'API Cloud Quotas è dichiarativa. Puoi trattare le configurazioni delle quote come codice e archiviarle nel tuo sistema di controllo delle versioni per la cronologia e il rollback.

Limitazioni

Cloud Quotas presenta le seguenti limitazioni:

  • Nella maggior parte dei casi, le modifiche di aumento delle quote devono essere apportate a livello di progetto. Un numero limitato di prodotti supporta le modifiche di aumento delle quote a livello di organizzazione. Per verificare se un Google Cloud prodotto supporta le modifiche di aumento delle quote a livello di organizzazione, consulta la documentazione del prodotto.

  • Puoi richiedere modifiche di diminuzione delle quote per le quote a livello di cartella, organizzazione e progetto.

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 a questo endpoint:

https://cloudquotas.googleapis.com

Ruoli obbligatori

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

Questo ruolo predefinito include le autorizzazioni necessarie per accedere alle risorse cloudquotas_quotaPreferences, cloudquotas_quotaInfos e cloudquotas_quotaAdjusterSettings. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

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

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

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

Modello di risorsa API

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

Preferenza di quota

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

Impostare un valore preferito per una regione

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

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

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

Verificare il valore concesso

Visualizza la tua preferenza di quota e guarda il campo grantedValue per verificare il valore concesso.

Per visualizzare la tua preferenza di quota utilizzando Google Cloud CLI, esegui il seguente comando nel terminale:

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

Sostituisci quanto segue:

  • QUOTA_PREFERENCE_ID: l'ID della tua preferenza di quota. Questo è il valore specificato quando è stata creata la preferenza di quota.
  • PROJECT: l'ID o il numero del tuo Google Cloud progetto.

Se hai effettuato una richiesta di modifica della quota e la richiesta è stata approvata parzialmente, dopo il campo grantedValue viene visualizzato un campo stateDetail. Il campo grantedValue mostra la modifica apportata, mentre il campo stateDetail descrive lo stato di approvazione parziale.

Per verificare se il valore concesso è il valore finale approvato, guarda il campo reconciling. Se la richiesta è ancora in fase di valutazione, il campo reconciling è impostato su true. Se il campo reconciling è impostato su false o viene omesso, il valore concesso è il valore finale approvato.

I seguenti snippet di codice mostrano esempi dell'oggetto della preferenza di quota. Utilizzano una preferenza di quota demo con l'ID compute_googleapis_com-gpus-us-central1.

gcloud

Se visualizzi la tua preferenza di quota utilizzando gcloud CLI, l'output è simile al seguente:

createTime: '2023-01-15T01:30:15.01Z'
dimensions:
    region: us-central1
name: projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1
quotaConfig:
    grantedValue: '100'
    preferredValue: '100'
    traceId: 123acd-345df23
    requestOrigin: ORIGIN_UNSPECIFIED
service: compute.googleapis.com
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
updateTime: '2023-01-16T02:35:16.01Z'

REST

Se visualizzi la tua preferenza di quota utilizzando l'API Cloud Quotas, l'output è simile al seguente:

{
    "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 dimensioni diverse sono risorse QuotaPreference diverse. Ad esempio, QuotaPreference per le CPU nelle regioni us-central1 e us-east1 sono due risorse distinte.

La preferenza di quota è obbligatoria

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

  • Richieste QuotaPreference effettuate da te.

  • Richieste di aumento delle quote approvate da Google Cloud.

  • Modifiche alle quote avviate da Google Cloud.

La possibilità di eliminare una QuotaPreference non è supportata. Tuttavia, puoi impostare un valore di quota preferito inferiore al valore Google Cloud approvato per aggiungere ulteriori misure di sicurezza.

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

Per saperne di più sulle query QuotaPreference, consulta Implementare i 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 da le quote definite dai Google Cloud servizi e le modifiche delle quote soddisfatte avviate dai clienti. La risorsa QuotaInfo contiene informazioni come i metadati, il tipo di container e le dimensioni.

Impostare valori di quota diversi per regione

Il seguente esempio di risorsa QuotaInfo mostra che la quota per le 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.

Impostare 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, il che indica che si tratta di una quota globale. Tutte le quote senza una dimensione di 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 saperne di più sulla risorsa QuotaInfo, consulta il Riferimento API Cloud Quotas.

Per saperne di più sulle query QuotaPreference, consulta Implementare i casi d'uso comuni.

Impostazioni di aggiustamento delle quote

La risorsa QuotaAdjusterSettings (anteprima) rappresenta le impostazioni di aggiustamento delle quote per un determinato progetto. Se abilitato, l'aggiustamento delle quote monitora l'utilizzo delle risorse specificate ed emette richieste di modifica delle quote quando l'utilizzo delle risorse si avvicina al valore della quota.

  • Per visualizzare le impostazioni di aggiustamento delle quote correnti per un progetto, utilizza un' operazione GET per recuperare la risorsa QuotaAdjusterSettings.

  • Per abilitare l'aggiustamento delle quote per un progetto, utilizza un' PATCH operazione per impostare le seguenti opzioni della risorsa QuotaAdjusterSettings:

      "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}

    Sostituisci PROJECT_NUMBER con l'identificatore univoco del progetto.

Per i dettagli, consulta Abilitare l'aggiustamento delle quote e Disabilitare l'aggiustamento delle quote.

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 il proprio nome risorsa univoco. Ogni nome risorsa è codificato da un insieme di campi.

Risorsa di preferenza di 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. Ti consigliamo di utilizzare uno schema di denominazione quotaPreferenceId che codifichi il nome del servizio, l'ID della quota, la località e altre dimensioni. quotaPreferenceId deve essere univoco per il progetto, la cartella o l'organizzazione.

Ad esempio, quotaPreference un pattern per codificare l'ID della preferenza di quota è il seguente: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

Il seguente esempio illustra questo pattern: 

compute_us-central1_nvidia-200

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

Risorsa di 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

Risorsa di impostazioni di aggiustamento delle quote

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

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

Passaggi successivi