Como gerenciar cotas do consumidor

Esta página descreve como usar a API Service Consumer Management para exibir e substituir os limites de cota impostos a consumidores individuais do serviço.

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

Para programar na API Service Infrastructure, recomendamos que você use uma de nossas 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.

Mostrar cota de serviço

Para mostrar as métricas e os limites de cota de serviço, siga estas etapas:

  1. Para usar gcurl, execute o seguinte comando alias com o token de autenticação:

    alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

    Para mais informações, consulte Ativar a API Service Usage.

  2. Para ver todos os limites de cota em todas as métricas aplicáveis a um consumidor específico, use o seguinte método:

    gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/services/SERVICE_NAME/projects/PROJECT_ID/consumerQuotaMetrics

    Substitua:

    • SERVICE_NAME: o nome do serviço.
    • PROJECT_ID: o ID do projeto do consumidor de interesse.

    Essa chamada responde com uma lista de métricas definidas pelo serviço, cada uma com a lista de limites das métricas que se aplicam a esse consumidor, os valores desses limites e quaisquer substituições. Veja um exemplo de resposta:

    {
  "metrics": [
    {
      "name": "services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests",
      "metric": "airport_requests",
      "displayName": "Airport Requests",
      "consumerQuotaLimits": [
        {
          "name": "services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests/limits/%2Fmin%2Fproject",
          "metric": "airport_requests",
          "unit": "1/min/{project}",
          "quotaBuckets": [
            {
              "effectiveLimit": "5",
              "defaultLimit": "5",
            }
          ]
        }
      ],
    }
  ]
}

  3. Cada métrica na resposta tem um campo de nome. Para inspecionar as configurações de cota apenas para essa métrica, e não para todas as métricas, use o nome dela no URL:

    gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/METRIC_NAME

    Substitua METRIC_NAME pelo nome totalmente qualificado da métrica. Exemplo:

    services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests

  4. Cada limite em uma métrica tem um campo de nome. Para inspecionar as configurações de cota apenas para esse limite nessa métrica, e não para todos os limites de uma métrica ou de todas as métricas, use o nome dela no URL:

    gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/LIMIT_NAME

    Substitua LIMIT_NAME pelo nome totalmente qualificado do limite. Exemplo:

    services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests/limits/%2Fmin%2Fproject

Aplicar uma substituição de produtor

O proprietário ou administrador de um serviço pode aplicar uma substituição de produtor a um limite específico para um consumidor específico, concedendo um aumento de cota nesse limite.

  1. Para identificar um limite, primeiro use um dos métodos anteriores para encontrar o limite de cota de interesse e, em seguida, use o campo de nome para aplicar uma substituição de produtor nele:

    gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/LIMIT_NAME/producerOverrides -d '{"override": {"override_value": "12345"} }'

    Essa chamada pode ser usada para aplicar uma nova substituição ou atualizar uma substituição existente para um novo valor. Para conceder cota ilimitada em um limite, use "-1" como o valor de substituição.

    Se a chamada for bem-sucedida, ela vai 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"
}

  2. Para verificar o andamento da operação, use o nome dela:

    gcurl https://serviceconsumermanagement.googleapis.com/v1/OPERATION_NAME

    Quando essa chamada responder com uma mensagem que inclui "done":true, a operação estará concluída. Se a operação falhar, a mensagem vai incluir detalhes do erro.

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

Forçar grandes mudanças de cota

Se uma substituição 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 o sinalizador de força:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/LIMIT_NAME/producerOverrides -d '{"override": {"override_value": "0"}, "force": true}'

Aplicar substituições de cota regional ou zonal

Alguns limites de cota são impostos por região ou zona. Isso é indicado pela presença de /{region} ou /{zone} na unidade de limite.

A aplicação de uma substituição a esse limite muda a cota base em todas as regiões ou zonas. Para mudar a cota de uma região ou zona específica, use o campo "local":

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/LIMIT_NAME/producerOverrides -d '{"override": {"override_value": "135", "dimensions": {"region": "asia-south1"} } }'