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.

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

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 testar a API, siga as instruções neste guia e use o comando curl para testar a API sem configurar um ambiente de desenvolvimento de aplicativo completo.

Antes de começar

Para gerenciar cotas de serviço, você precisará dos seguintes itens:

Para este tutorial, usaremos uma variável de ambiente PROJECT_NUMBER definida como um número de projeto de sua propriedade e o serviço serviceusage.googleapis.com como o serviço de interesse.

Para localizar rapidamente o número do projeto que você tem com o ID PROJECT_ID, use o seguinte comando:

PROJECT_NUMBER=`gcloud projects list --filter="${PROJECT_ID}" --format="value(PROJECT_NUMBER)"`

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/serviceusage.googleapis.com/consumerQuotaMetrics

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:

{
  "metrics": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests",
      "displayName": "Default requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject",
          "unit": "1/min/{project}",
          "metric": "serviceusage.googleapis.com/default_requests",
          "quotaBuckets": [
            {
              "effectiveLimit": "240",
              "defaultLimit": "240"
            }
          ]
        }
      ],
      "metric": "serviceusage.googleapis.com/default_requests"
    },
    {
      "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fmutate_requests",
      "displayName": "Mutate requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fmutate_requests/limits/%2Fmin%2Fproject",
          "unit": "1/min/{project}",
          "metric": "serviceusage.googleapis.com/mutate_requests",
          "quotaBuckets": [
            {
              "effectiveLimit": "120",
              "defaultLimit": "120"
            }
          ]
        }
      ],
      "metric": "serviceusage.googleapis.com/mutate_requests"
    }
  ]
}

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/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests"
gcurl https://serviceusage.googleapis.com/v1beta1/${METRIC_RESOURCE_NAME}

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/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject"
gcurl https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}

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 a ser modificado, primeiro use um dos métodos acima para encontrar o limite de cota pretendido e, em seguida, use o campo de nome para criar uma nova modificação de consumidor no grupo de modificações desse limite. O exemplo a seguir destina-se a um limite de cota específico:

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

Se a chamada for bem-sucedida, ela retornará um identificador de operação, que representa o trabalho em andamento no servidor, conforme a mudança 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.

Também é possível verificar se uma alteração foi aplicada repetindo a chamada de obtenção original no limite específico. O limite agora precisa ter um campo consumerOverride extra.

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 modificação regional em um limite de cota regional do Cloud ML como este:

REGIONAL_LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/ml.googleapis.com/consumerQuotaMetrics/ml.googleapis.com%2Foptimizer_management_requests"
gcurl https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides -d '{"overrideValue": "550", "dimensions": {"region": "asia-south1"} }'

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/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"

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

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"
gcurl https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME} -X PATCH -d '{"overrideValue": "230"}'

Se a chamada for bem-sucedida, ela retornará um identificador de operação, que representa o trabalho em andamento no servidor, conforme a mudança 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.

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/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"

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

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

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/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject"
gcurl https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides?force=true -d '{"overrideValue": "40"}'