Configurar quotas

Esta página descreve como configurar quotas para a sua API. A um nível elevado, os passos são os seguintes:

  1. Adicione as informações sobre a quota ao ficheiro de configuração da API gRPC.
  2. Implemente o ficheiro de configuração da API gRPC.
  3. Implemente o proxy de serviço extensível (ESP).

Para uma vista geral da funcionalidade fornecida pelas quotas, consulte o artigo Acerca das quotas.

Pré-requisitos

Como ponto de partida, esta página pressupõe que:

Adicionar uma quota ao ficheiro de configuração da API gRPC

O procedimento seguinte descreve como adicionar as definições necessárias ao ficheiro de configuração da API gRPC para configurar quotas. Para simplificar, esta página refere-se ao ficheiro de configuração da API gRPC como o ficheiro api_config.yaml.

Adicione as três secções seguintes ao ficheiro api_config.yaml:

  • metrics: uma métrica com nome que contabiliza os pedidos à sua API. Indica um nome que descreve o contador. O nome pode ser uma categoria, como read-requests ou write-requests. Em alternativa, se estiver a definir uma quota para um método específico, é recomendável incluir o nome do método, por exemplo,echo-api/echo_requests.

  • quota.limits: representa um único limite aplicável numa métrica com nome. É aqui que configura o número permitido de pedidos para uma métrica que definiu. Atualmente, apenas são suportados limites por minuto e por projeto.

  • quota.metric_rules: um metric_rule mapeia métodos para métricas (muitos para muitos). Um pedido a um método atribui um contador a cada uma das métricas mapeadas. Quando associa um método a uma métrica, especifica sempre um custo para o pedido. Pode configurar o custo de cada método de forma independente. Isto permite que diferentes métodos consumam a métrica com o mesmo nome a taxas diferentes. Se não tiver um requisito de quota complexo, pode configurar o custo de cada métrica para 1.

Para configurar quotas na sua API:

  1. Abra o ficheiro api_config.yaml do projeto num editor de texto.

  2. Adicione o campo metrics ao nível superior do ficheiro (sem recuo nem aninhamento), após o 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 descreva o contador de pedidos de API.
    • Substitua YOUR_METRIC_DISPLAY_NAME pelo texto apresentado na página Endpoints > Serviços > Quotas para identificar a métrica.
    • O campo value_type tem de ser INT64.
    • O campo metric_kind tem de ser DELTA.

  3. Adicione um campo quota ao mesmo nível que metrics e adicione um campo limits aninhado na secçã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 descreva o limite.
    • Substitua YOUR_METRIC_NAME por um metric.name definido anteriormente.
    • O campo unit tem de ser "1/min/{project}". Este é o identificador do limite por minuto por projeto.
    • O campo values tem de conter STANDARD.
    • Substitua VALUE_FOR_THE_LIMIT por um valor inteiro. Este é o número de pedidos que uma aplicação associada ao projeto de um consumidor pode fazer num minuto. Google Cloud

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

  5. Adicione uma linha com recuo de metric_rules abaixo de quota, após a secção limits. Na secção metric_rules, associe uma métrica definida anteriormente a um método, da seguinte forma:

    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 pedido, o contador de pedidos da métrica é incrementado pelo número que especificar para o custo.

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

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

  6. Guarde o ficheiro api_config.yaml.

Exemplos de configuração de quotas

Os três exemplos seguintes mostram como configurar quotas na sua API.

O exemplo seguinte 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 seguinte mostra como configurar os campos quota e limits na secçã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 seguinte mostra como configurar a linha metrics após a secçã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: *

Implementar o ficheiro api_config.yaml e o SEP

Para que a quota entre em vigor, tem de:

  1. Implemente o ficheiro api_config.yaml na gestão de serviços, o que atualiza a configuração nos pontos finais. Para ver os passos detalhados, consulte o artigo Implementar a configuração do Endpoints.
  2. Implemente o ESP. Para ver passos detalhados, consulte o artigo Implementar o back-end da API.