Como configurar cotas

Nesta página, descrevemos como configurar cotas para uma API. De modo geral, as etapas são:

  1. Adicionar as informações sobre a cota ao arquivo de configuração da API gRPC.
  2. Implantar o arquivo de configuração da API gRPC.
  3. Implantar o Extensible Service Proxy (ESP).

Para uma visão geral da funcionalidade oferecida pelas cotas, consulte Sobre cotas.

Pré-requisitos

Como ponto de partida nesta página, presume-se que você tenha:

Como adicionar uma cota ao seu arquivo de configuração da API gRPC

No procedimento a seguir, descrevemos como adicionar as configurações necessárias ao arquivo de configuração da API gRPC para estipular as cotas. Para simplificar, esta página se refere ao arquivo de configuração da API gRPC como o arquivo api_config.yaml.

Adicione as três seções a seguir ao arquivo api_config.yaml:

  • metrics: uma métrica com nome que conta as solicitações para sua API. Forneça um nome que descreve o contador. O nome pode ser uma categoria, como read-requests ou write-requests. Como alternativa, se você estiver definindo uma cota para um método específico, convém incluir o nome do método, por exemplo, echo-api/echo_requests.

  • quota.limits: representa um único limite aplicável em uma métrica nomeada. Aqui você configura o número permitido de solicitações para a métrica definida. Atualmente, são aceitos apenas limites por minuto e por projeto.

  • quota.metric_rules: um metric_rule mapeia métodos para métricas (de muitos para muitos). Uma solicitação para um método aloca um contador para cada uma das métricas relacionadas. Ao associar um método a uma métrica, você sempre especifica um custo para a solicitação. É possível configurar o custo de cada método de forma independente. Isso permite o consumo de métodos distintos em taxas diferentes da mesma métrica. Caso você não tenha um requisito de cota complexo, configure o custo de cada métrica como 1.

Para configurar cotas na API:

  1. Abra o arquivo api_config.yaml do projeto em um editor de texto.

  2. Adicione o campo metrics no nível superior do arquivo (não recuado ou aninhado), depois do campo apis.

    metrics:
  - name: "YOUR_METRIC_NAME"
    display_name: "YOUR_METRIC_DISPLAY_NAME"
        value_type: INT64
    metric_kind: DELTA`
    • Substitua YOUR_METRIC_NAME por um nome que descreve o contador de solicitações da API.
    • Substitua YOUR_METRIC_DISPLAY_NAME pelo texto exibido na página Endpoints > Serviços > Cotas para identificar a métrica.
    • O campo value_type precisa ser INT64.
    • O campo metric_kind precisa ser DELTA.

  3. Adicione um campo quota no mesmo nível que metrics e adicione um campo limits aninhado dentro da seção quota.

    quota:
  limits:
    - name: "YOUR_LIMIT_NAME"
      metric: "YOUR_METRIC_NAME"
      unit: "1/min/{project}"
      values:
        STANDARD: VALUE_FOR_THE_LIMIT
    • Substitua YOUR_LIMIT_NAME por um nome que descreve o limite.
    • Substitua YOUR_METRIC_NAME por um metric.name definido anteriormente.
    • O campo unit precisa ser "1/min/{project}". Esse é o identificador para o limite por minuto e por projeto.
    • O campo values precisa conter STANDARD.
    • Substitua VALUE_FOR_THE_LIMIT por um valor inteiro. Esse é o número de solicitações que um aplicativo associado ao projeto do Google Cloud de um cliente pode fazer em um minuto.

  4. Se quiser, defina métricas e limites adicionais para cada métrica.

  5. Adicione uma linha metric_rules recuada em quota, depois da seção limits. Na seção metric_rules, associe uma métrica definida anteriormente a um método, da seguinte maneira:

    metric_rules:
  - metric_costs:
      YOUR_METRIC_NAME: YOUR_METRIC_COST
    selector: [METHODS]
    • Substitua YOUR_METRIC_NAME por um metric.name definido anteriormente.
    • Substitua YOUR_METRIC_COST por um número inteiro. Para cada solicitação, o contador de solicitações da métrica é acrescido do número que você especificou para o custo.

    • Para o campo selector, especifique uma das seguintes opções:

      • Para associar todos os métodos em todas as APIs com o metric_cost, use selector: "*"
      • Para associar todos os métodos em uma API com o metric_cost, use selector: YOUR_API_NAME.*
      • Para associar um método específico em uma API com metric_cost, use selector: YOUR_API_NAME.YOUR_METHOD_NAME

  6. Salve o arquivo api_config.yaml.

Exemplos de configuração de cota

Os três exemplos a seguir mostram como configurar cotas na sua API.

O exemplo a seguir mostra como configurar o campo metric:

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA`

O exemplo a seguir mostra como configurar os campos quota e limits na seção quota:

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA
quota:
  limits:
    # Define the limit or the read-requests metric.
    - name: "read-limit"
      metric: "read-requests"
      unit: "1/min/{project}"
      values:
        STANDARD: 1000

O exemplo a seguir mostra como configurar a linha metrics após a seção limits:

  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      display_name: "Read requests"
      value_type: INT64
      metric_kind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
    metric_rules:
      - metric_costs:
          "read-requests": 1
        selector: *

Como implantar o arquivo api_config.yaml e o ESP

Para que a cota entre em vigor, você precisa:

  1. Implante o arquivo api_config.yaml no Service Management, que atualiza a configuração no Endpoints. Para ver as etapas detalhadas, consulte Como implantar a configuração do Endpoints.
  2. Implante o ESP. Para conferir as etapas detalhadas, consulte Como implantar o back-end da API.