Como gerenciar uma cota de serviço

Nesta página, descrevemos como visualizar todas as métricas e limites em um projeto do Google Cloud para um serviço específico e como limitar o uso da cota para esse serviço usando uma substituição de cota. É possível usar o Service Usage para gerenciar a cota dos seus projetos para qualquer serviço, incluindo serviços públicos do Google Cloud e serviços privados criados com o Cloud Endpoints. Para mais informações sobre as diferenças entre APIs e serviços públicos e privados, consulte Serviços públicos e privados.

Observação: o Service Usage exibe apenas informações sobre os limites de cota de um projeto, e não o uso da cota. É possível receber dados de uso de cota por meio da API Cloud Monitoring e do recurso consumer_quota.

Na maioria dos casos de uso operacional, a maneira mais simples de gerenciar cotas é usar o console do Google Cloud. Se precisar programar com a API Service Usage, recomendamos que você use uma das bibliotecas de clientes fornecidas. Para fazer testes com a API, siga as instruções deste guia e use o comando gcurl para testar a API sem configurar um ambiente de desenvolvimento de aplicativos completo.

Se você estiver usando o Terraform, consulte Gerenciar recursos de uso de serviço com o Terraform.

Antes de começar

Para usar os exemplos nesta página, conclua todas as etapas listadas no guia Primeiros passos. Essas etapas incluem a definição de gcurl, que é um alias autenticado do comando curl padrão, e a variável de ambiente PROJECT_NUMBER.

Certifique-se de se familiarizar com o modelo de cota de serviço para entender melhor a terminologia usada neste tutorial.

Como exibir a cota de serviço

Para ver todas as métricas e limites de cotas que se aplicam a um consumidor específico em um serviço, use o seguinte comando:

gcurl "https://serviceusage.googleapis.com/v1beta1/projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics"

Observação: este exemplo usa o serviço do Compute Engine, mas é possível conferir métricas de cota e limites de outros serviços substituindo compute.googleapis.com por outro nome de serviço neste comando. Por exemplo, para conferir métricas e limites de cotas do Pub/Sub, substitua compute.googleapis.com por pubsub.googleapis.com.

A chamada responde com uma lista de métricas definidas pelo serviço, cada uma com a lista de limites dessas métricas que se aplicam a esse consumidor, os valores desses limites e todas as modificações. Veja um exemplo de resposta parcial:

{
  "metrics": [
    ...
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus",
      "displayName": "CPUs",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fzone",
          "unit": "1/{project}/{zone}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/cpus",
          "quotaBuckets": [
            {
              "effectiveLimit": "-1",
              "defaultLimit": "-1"
            }
          ]
        },
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion",
          "unit": "1/{project}/{region}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/cpus",
          "quotaBuckets": [
            {
              "effectiveLimit": "24",
              "defaultLimit": "24"
            },
            {
              "effectiveLimit": "72",
              "defaultLimit": "72",
              "dimensions": {
                "region": "asia-northeast1"
              }
            },

            ...

            {
              "effectiveLimit": "72",
              "defaultLimit": "72",
              "dimensions": {
                "region": "australia-southeast1"
              }
            }
          ]
        }
      ],
      "metric": "compute.googleapis.com/cpus",
      "unit": "1"
    },
    ...
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways",
      "displayName": "External VPN gateways",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
          "unit": "1/{project}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/external_vpn_gateways",
          "quotaBuckets": [
            {
              "effectiveLimit": "15",
              "defaultLimit": "15"
            }
          ]
        }
      ],
      "metric": "compute.googleapis.com/external_vpn_gateways",
      "unit": "1"
    },
    ...

Cada métrica na resposta tem um campo name. Para inspecionar as configurações de cota apenas para essa métrica, e não para todas as métricas, use name no URL. Neste tutorial, a variável de ambiente METRIC_RESOURCE_NAME armazena o nome do recurso de métrica da cota:

METRIC_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways"
gcurl "https://serviceusage.googleapis.com/v1beta1/${METRIC_RESOURCE_NAME}"

Como é fornecido um nome de recurso de métrica específico, a chamada retorna somente as informações dessa métrica:

{
  "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways",
  "displayName": "External VPN gateways",
  "consumerQuotaLimits": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
      "unit": "1/{project}",
      "isPrecise": true,
      "metric": "compute.googleapis.com/external_vpn_gateways",
      "quotaBuckets": [
        {
          "effectiveLimit": "15",
          "defaultLimit": "15"
        }
      ]
    }
  ],
  "metric": "compute.googleapis.com/external_vpn_gateways",
  "unit": "1"
}

Da mesma forma, cada limite dentro de uma métrica tem um campo name. Para inspecionar as configurações de cota apenas para o limite em questão nessa métrica, e não para todos os limites de uma métrica ou de todas as métricas, use o name no URL. Neste tutorial, a variável de ambiente LIMIT_RESOURCE_NAME armazena o nome do recurso de limite de cota:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}"

Quando um limite específico é fornecido, a chamada retorna apenas as informações desse limite:

{
  "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
  "unit": "1/{project}",
  "isPrecise": true,
  "metric": "compute.googleapis.com/external_vpn_gateways",
  "quotaBuckets": [
    {
      "effectiveLimit": "15",
      "defaultLimit": "15"
    }
  ]
}

Como criar uma substituição de cota do consumidor

O proprietário de um projeto pode aplicar uma modificação de consumidor a um limite de cota específico nesse projeto. Isso reduzir a quantidade total de cota que o consumidor pode cobrar em relação a esse limite.

Uma modificação do consumidor não pode aumentar a cota disponível além do permitido pelo padrão de serviço nem permite qualquer modificação atual feita por outras partes, como o proprietário do serviço ou o administrador de cotas de uma organização. Para aumentar a cota disponível, use a opção Editar cotas na página de cota principal ou solicite um aumento de cota ao administrador da organização.

Para identificar um limite que será substituído, primeiro use um dos métodos anteriores para encontrar o limite de interesse. Em seguida, use o campo de nome do limite de cota para criar uma nova modificação do consumidor nesse limite. O exemplo a seguir é para o limite de projetos por projeto da métrica de cotas "Gateways de VPN externos" do serviço do Compute Engine:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides" -d '{"overrideValue": "14"}'

Quando a chamada é bem-sucedida, ela retorna um identificador de operação que representa o trabalho em andamento no servidor, já que a alteração de cota se propaga para os sistemas de back-end:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Para verificar o progresso da operação, basta usar o name:

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl "https://serviceusage.googleapis.com/v1/${OPERATION_NAME}"

Se a operação for bem-sucedida, a mensagem de resposta incluirá done: true e conterá o recurso de modificação recém-criado. Se a operação falhar, a mensagem de resposta incluirá done: true, mas conterá detalhes do erro em vez do recurso.

Para verificar se a substituição foi criada, liste todas as substituições do consumidor para o limite:

gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

A substituição recém-criada deve aparecer na lista:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl",
      "overrideValue": "14"
    }
  ]
}

Como criar modificações de cota regionais ou sazonais

Alguns limites de cota são aplicados por região ou zona. Isso é indicado pela presença de {region} ou {zone} no campo unit do limite. Por exemplo, um limite com a unidade "1/{project}/{region}" é aplicado por região. A aplicação de uma modificação a esse limite altera a cota base em cada região ou zona. Para alterar a cota de uma região ou zona específica, adicione uma dimensão de cota usando o campo dimensions ao criar a modificação. Por exemplo, crie uma substituição regional em um limite de cota regional do Compute Engine desta forma:

REGIONAL_LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion"
gcurl "https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides" -d '{"overrideValue": "65", "dimensions": {"region": "southamerica-east1"} }'

Para verificar se a substituição regional foi criada, liste todas as substituições do consumidor para o limite:

gcurl "https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides"

A substituição regional recém-criada aparecerá na lista:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion/consumerOverrides/Cg1RdW90YU92ZXJyaWRlGhwKBnJlZ2lvbhISc291dGhhbWVyaWNhLWVhc3Qx",
      "overrideValue": "65",
      "dimensions": {
        "region": "southamerica-east1"
      }
    }
  ]
}

Como atualizar uma modificação de cota do consumidor

O proprietário de um projeto também pode alterar o valor de uma modificação de consumidor existente no projeto.

Por exemplo, suponha que uma chamada de criação anterior retorne uma modificação com um campo name como este:

name: "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"

Em seguida, use esse nome para identificar a substituição a ser atualizada, desta maneira:

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"
gcurl "https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME}" -X PATCH -d '{"overrideValue": "13"}'

Quando a chamada é bem-sucedida, ela retorna um identificador de operação que representa o trabalho em andamento no servidor, já que a alteração de cota se propaga para os sistemas de back-end:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Para verificar o progresso da operação, basta usar o name:

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl "https://serviceusage.googleapis.com/v1/${OPERATION_NAME}"

Se a operação for bem-sucedida, a mensagem de resposta incluirá done: true e conterá o recurso de modificação atualizado. Se a operação falhar, a mensagem de resposta incluirá done: true, mas conterá detalhes do erro em vez do recurso atualizado.

Para verificar se a substituição foi atualizada, liste todas as substituições de consumidor do limite:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

Agora a substituição deve aparecer na lista com o valor atualizado:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl",
      "overrideValue": "13"
    }
  ]
}

Como excluir uma modificação de cota do consumidor

O proprietário de um projeto também pode remover uma modificação de consumidor do projeto.

Por exemplo, suponha que uma chamada de criação anterior retorne uma modificação com um campo name como este:

name: "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"

Para excluir a modificação, emita a seguinte sequência:

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"
gcurl "https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME}" -X DELETE

Para verificar se a substituição foi excluída, liste todas as substituições do consumidor para o limite:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

A substituição excluída não aparecerá mais na lista.

Como forçar grandes alterações de cota

Se qualquer modificação de substituição de cota fizer com que a cota aplicada diminua em mais de 10%, a chamada será rejeitada, como uma medida de segurança para evitar a redução acidental da cota muito rapidamente. Para desconsiderar essa restrição, use a sinalização force. Por exemplo, esta é uma chamada de criação que recebe o sinalização forçada:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides?force=true" -d '{"overrideValue": "0"}'