Vista geral da Cloud Quotas API

A API Cloud Quotas permite ajustar programaticamente as quotas ao nível do projeto e automatizar os pedidos de ajuste de quotas ao nível do projeto. Por exemplo, pode usar a API Cloud Quotas para:

  • Automatize os ajustes de quotas: pode usar a API Cloud Quotas para pedir ajustes de quotas com base nos seus próprios critérios. Por exemplo, para evitar erros de quota excedida, pode usar a API para pedir programaticamente um ajuste da quota quando os recursos do Compute Engine atingirem 80% da quota disponível.

  • Reutilize as configurações de quotas em vários projetos: a API Cloud Quotas pode clonar as suas configurações de quotas de projeto para projeto. Se existir um conjunto conhecido de quotas que precisam de ser aumentadas para cada novo projeto, pode usar a API Cloud Quotas para automatizar este processo na lógica de criação do seu projeto. Google Cloud Os pedidos de ajuste de quota estão sujeitos a Google Cloud aprovação.

  • Servir pedidos de quota de clientes: se for um fornecedor de SaaS integrado com o Google Cloud, pode receber pedidos de aumento da quota através de um portal virado para o cliente que não seja a consola do Google Cloud.Google CloudGoogle Cloud Estas solicitações têm de ser encaminhadas para a Google Cloud para processamento. A API Cloud Quotas pode encaminhar automaticamente pedidos de clientes.

  • Ative o controlo de versões da configuração do cliente: a API Cloud Quotas é declarativa. Pode tratar as configurações de quotas como código e armazenar as configurações no seu próprio sistema controlado por versões para histórico e reversão.

Limitações

As quotas do Google Cloud têm as seguintes limitações:

  • Na maioria dos casos, os ajustes de aumento da quota têm de ser feitos ao nível do projeto. Um número limitado de produtos suporta ajustes de aumento da quota ao nível da organização. Para ver se um Google Cloud produto suporta ajustes de aumento da quota ao nível da organização, consulte a documentação desse produto.

  • Pode pedir ajustes de diminuição da quota para quotas ao nível do projeto, da organização e da pasta.

Ponto final do serviço

O ponto final do serviço é um URL base que especifica o endereço de rede de um serviço de API. Um serviço pode ter vários endpoints. O serviço da API Cloud Quotas tem o seguinte ponto final e todos os URIs são relativos ao mesmo:

https://cloudquotas.googleapis.com

Funções necessárias

Para receber as autorizações de que precisa para aceder aos recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos e cloudquotas_quotaAdjusterSettings, peça ao seu administrador que lhe conceda a função do IAM de administrador de quotas da nuvem (cloudquotas.admin) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para aceder aos recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos e cloudquotas_quotaAdjusterSettings. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

As seguintes autorizações são necessárias para aceder aos recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos e cloudquotas_quotaAdjusterSettings:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Modelo de recurso da API

O modelo de recursos da Cloud Quotas API consiste em dois recursos: QuotaPreference e QuotaInfo.

Preferência de quota

O recurso QuotaPreference representa a sua preferência de quota para uma determinada combinação de dimensões. Use este recurso para ajustar as quotas nos seus projetos, pastas ou organizações.

Defina um valor preferencial para uma região

O exemplo seguinte mostra um recurso QuotaPreference num método CreateQuotaPreference.

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

O valor preferredValue de 100 indica que o requerente quer que a quota GPUS-PER-GPU-FAMILY-per-project-region seja definida para esse valor. O campo de dimensões indica que a preferência só se aplica à região us-central1.

Valide o valor concedido

Veja a sua preferência de quota e consulte o campo grantedValue para verificar o valor concedido.

Para ver a sua preferência de quota através da CLI Google Cloud, execute o seguinte no seu terminal:

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

Substitua o seguinte:

  • QUOTA_PREFERENCE_ID: o ID da sua preferência de quota. Este é o valor especificado quando a preferência de quota foi criada.
  • PROJECT: o ID ou o número do seu projeto Google Cloud.

Se fez um pedido de ajuste da quota e o pedido for parcialmente aprovado, é apresentado um campo stateDetail após o campo grantedValue. O elemento grantedValue mostra o ajuste que foi feito e o campo stateDetail descreve o estado parcialmente aprovado.

Para ver se o valor concedido é o valor final aprovado, consulte o campo reconciling. Se o seu pedido ainda estiver a ser avaliado, o campo reconciling está definido como true. Se o campo reconciling estiver definido como false ou for omitido, o valor concedido é o valor final aprovado.

Os seguintes fragmentos de código mostram exemplos do objeto de preferência de quota. Usam uma preferência de quota de demonstração com o ID compute_googleapis_com-gpus-us-central1.

gcloud

Se vir a sua preferência de quota através da CLI gcloud, o resultado é semelhante ao seguinte:

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:
    granteddValue: '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 vir a sua preferência de quota através da API Cloud Quotas, o resultado é semelhante ao seguinte:

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

Esta saída inclui os seguintes valores:

  • PROJECT_NUMBER: um identificador exclusivo gerado automaticamente para o seu projeto.

A resposta mostra um grantedValue de 100, o que significa que o preferredValue do exemplo anterior foi aprovado e cumprido. As preferências para diferentes dimensões são QuotaPreference recursos diferentes. Por exemplo, QuotaPreference para a CPU nas regiões us-central1 e us-east1 são dois recursos distintos.

A preferência de quota é obrigatória

Os recursos QuotaPreference são usados para indicar o seu valor preferencial para uma quota específica. O valor atual de uma quota específica baseia-se no seguinte:

  • QuotaPreference pedidos feitos por si.

  • Pedidos de aumento da quota aprovados por Google Cloud.

  • Alterações às quotas iniciadas por Google Cloud.

A capacidade de eliminar um QuotaPreference não é suportada. No entanto, pode definir um valor de quota preferencial inferior ao Google Cloud valor aprovado para adicionar mais restrições.

Para mais informações sobre o recurso QuotaPreference, consulte a referência da API Cloud Quotas.

Para mais informações sobre as consultas QuotaPreference, consulte o artigo Implemente exemplos de utilização comuns.

Informações sobre quotas

QuotaInfo é um recurso só de leitura que fornece informações sobre uma quota específica para um determinado projeto, pasta ou organização. Apresenta informações das quotas definidas pelos serviços do Google Cloud e quaisquer ajustes de quotas cumpridos iniciados pelos clientes. O recurso QuotaInfo contém informações como os metadados, o tipo de contentor e a dimensão.

Defina valores de quota diferentes por região

O exemplo de recurso QuotaInfo seguinte mostra que a quota de CPU para o projeto é de 200 para a região us-central1 e de 100 para todas as outras regiões.

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

Esta saída inclui os seguintes valores:

  • PROJECT_NUMBER: um identificador exclusivo gerado automaticamente para o seu projeto.

Defina uma quota global

O exemplo de recurso QuotaInfo seguinte mostra uma quota de taxa com um intervalo de atualização por minuto. As dimensões estão em branco, o que indica que se trata de uma quota global. Todas as quotas sem uma dimensão de região ou zona são globais.

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

Esta saída inclui os seguintes valores:

  • PROJECT_NUMBER: um identificador exclusivo gerado automaticamente para o seu projeto.

Para mais detalhes sobre o recurso QuotaInfo, consulte a referência da API Cloud Quotas.

Para mais detalhes sobre as consultas QuotaPreference, consulte o artigo Implemente exemplos de utilização comuns.

Definições do ajustador de quotas

O recurso QuotaAdjusterSettings (Preview) representa as definições do ajustador de quota para um projeto específico. Quando ativado, o ajustador de quotas monitoriza a sua utilização dos recursos especificados e emite pedidos de ajuste de quotas quando a utilização de recursos se aproxima do respetivo valor de quota.

  • Para ver as definições atuais do ajustador de quotas de um projeto, use uma operação GET para obter o recurso QuotaAdjusterSettings.

  • Para ativar o ajuste de quota para um projeto, use uma operação PATCH para definir as seguintes opções de recursos QuotaAdjusterSettings:

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

    Substitua PROJECT_NUMBER pelo identificador exclusivo do seu projeto.

Para obter detalhes, consulte os artigos Ative o ajustador de quota e Desative o ajustador de quota.

Nomes de recursos

Os recursos são entidades com nome e são identificados por nomes de recursos. Os nomes dos recursos são usados em todos os pedidos e respostas, e cada recurso tem de ter o seu próprio nome do recurso exclusivo. Cada nome de recurso é codificado por um conjunto de campos.

Recurso de preferência de quota

A convenção de nomenclatura de um recurso QuotaPreference usa o seguinte padrão:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Pode definir o quotaPreferenceId quando criar uma preferência de quota. Caso contrário, é gerado um ID. Recomendamos que um esquema de nomenclatura quotaPreferenceId codifique o nome do serviço, o ID da quota, a localização e outras dimensões. O quotaPreferenceId tem de ser exclusivo para o projeto, a pasta ou as organizações.

Por exemplo, quotaPreference um padrão para codificar o ID de preferência de quota é o seguinte: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

O exemplo seguinte demonstra este padrão: 

compute_us-central1_nvidia-200

Com um nome do recurso, deve usar o método GET para obter um QuotaPreference. Também pode chamar o método PATCH com a opção allow_missing ativada para criar ou atualizar um QuotaPreference.

Recurso de informações sobre quotas

A convenção de nomenclatura de um recurso QuotaInfo usa o seguinte padrão:

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

Recurso de definições do ajustador de quotas

A convenção de nomenclatura de um recurso QuotaAdjusterSettings usa o seguinte padrão:

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

O que se segue?