Visão geral da API Cloud Quotas

A API Cloud Quotas permite que você ajuste programaticamente cotas em nível de projeto e automatize solicitações de ajuste de cotas em nível de projeto. Por exemplo, é possível usar a API Cloud Quotas para:

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

  • Reutilizar configurações de cota em projetos: a API Cloud Quotas pode clonar suas configurações de cota de projeto em projeto. Se houver um conjunto conhecido de cotas que precisam ser aumentadas para cada novo projeto do Google Cloud, você poderá usar a API Cloud Quotas para automatizar isso na lógica de criação do seu projeto. As solicitações de ajuste de cota estão sujeitas à aprovação do Google Cloud.

  • Atender às solicitações de cota do cliente: se você for um provedor de SaaS integrado ao Google Cloud, poderá receber solicitações de aumento de cota por um portal voltado para o cliente que não seja o console do Google Cloud. Essas solicitações precisam ser encaminhadas ao Google Cloud para processamento. A API Cloud Quotas pode encaminhar automaticamente as solicitações dos clientes.

  • Ativar o controle de versão da configuração do cliente: a API Cloud Quotas é declarativa. É possível tratar as configurações de cota como código e armazenar as configurações no seu próprio sistema controlado por versão para fins de histórico e reversão.

Limitações

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

  • Os ajustes de aumento de cota precisam ser feitos no nível do projeto e estão sujeitos à aprovação do Google Cloud.

  • É possível solicitar ajustes de diminuição de cota para project-, folder- e as cotas no nível da organização.

  • A API Cloud Quotas é compatível apenas com operações no nível do projeto. Operações em nível de pasta e organização não são compatíveis.

Endpoint de serviço

Um endpoint de 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 Cotas tem o endpoint a seguir e todos os URIs são relacionados a ele:

https://cloudquotas.googleapis.com

Funções exigidas

Para ter as permissões necessárias para acessar os recursos cloudquotas_quotaPreferences e cloudquotas_quotaInfos, peça ao administrador para conceder a você o Administrador de cotas do Cloud (cloudquotas.admin ) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para acessar os recursos cloudquotas_quotaPreferences e cloudquotas_quotaInfos. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para acessar os recursos cloudquotas_quotaPreferences e cloudquotas_quotaInfos:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Modelo de recurso de API

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

Preferência de cota

O recurso QuotaPreference representa sua preferência de cota por uma determinada combinação de dimensões. Use esse recurso para ajustar as cotas nos seus projetos, pastas ou organizações.

Definir um valor preferencial para uma região

O exemplo a seguir mostra um recurso QuotaPreference em um método CreateQuotaPreference.

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

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

Verificar o valor concedido

O exemplo a seguir mostra um recurso QuotaPreference em um método 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"
}

Esta saída inclui os seguintes valores:

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

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

A preferência de cota é obrigatória

Os recursos de QuotaPreference são usados para indicar o valor preferido de uma cota específica. O valor atual de uma cota específica é baseado em:

  • QuotaPreference solicitações feitas por você.

  • Solicitações de aumento de cota aprovadas pelo Google Cloud.

  • Mudanças nas cotas iniciadas pelo Google Cloud.

Não há suporte para a capacidade de excluir um QuotaPreference. No entanto, é possível definir um valor de cota preferencial menor que o aprovado pelo Google Cloud para adicionar mais proteções.

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

Para mais informações sobre as consultas QuotaPreference, acesse Implementar casos de uso comuns.

Informações de cota

QuotaInfo é um recurso somente leitura que fornece informações sobre uma cota específica para um determinado projeto, pasta ou organizações. Ela exibe informações das cotas definidas pelos serviços do Google Cloud e quaisquer ajustes de cotas iniciados pelos clientes. O recurso QuotaInfo contém informações como metadados, tipo de contêiner e dimensão.

Definir valores de cota diferentes por região

O exemplo de recurso QuotaInfo a seguir mostra que a cota de CPU para o projeto é de 200 para a região us-central1 e 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 seu projeto.

Definir uma cota global

O exemplo de recurso QuotaInfo a seguir mostra uma cota de taxa com um intervalo de atualização por minuto. As dimensões estão em branco, o que indica que essa é uma cota global. Todas as cotas sem 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 seu projeto.

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

Para mais detalhes sobre as consultas QuotaPreference, consulte Implementar casos de uso comuns.

Nomes de recursos

Recursos são entidades nomeadas e são identificados por nomes de recursos. Os nomes dos recursos são usados em todas as solicitações e respostas, e cada recurso precisa ter o próprio nome exclusivo. Cada nome de recurso é codificado por um conjunto de campos.

Recurso de preferência de cota

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

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

É possível definir quotaPreferenceId ao criar uma preferência de cota. Caso contrário, um ID será gerado. É recomendável que um esquema de nomenclatura quotaPreferenceId codifique o nome do serviço, o ID da cota, o local e outras dimensões. O quotaPreferenceId precisa ser exclusivo para o projeto, a pasta ou as organizações.

Por exemplo, quotaPreference Este é um padrão para codificar seu ID de preferência de cota: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

O exemplo abaixo demonstra esse padrão. 

compute_us-central1_nvidia-200

Com um nome de recurso, use o método GET para extrair um QuotaPreference. Você também pode chamar o método UPDATE com a opção allow_missing ativada para criar ou atualizar um QuotaPreference.

Recurso de informações de cota

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

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

A seguir