Como configurar cotas

Esta página mostra como configurar cotas para sua API. Em um nível alto, as etapas são:

  1. Adicionar as informações sobre a cota ao arquivo de configuração OpenAPI.
  2. Implantar seu arquivo de configuração OpenAPI.
  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ê:

Como adicionar uma cota ao documento de uma OpenAPI

Neste procedimento, você aprende a adicionar as extensões necessárias para a configuração de cotas pelo documento da OpenAPI. Para simplificar, nesta página o documento da OpenAPI é referido como openapi.yaml e as extensões OpenAPI são fornecidas somente no formato YAML.

Você adiciona estas três seções ao arquivo openapi.yaml:

  • x-google-management.metrics: uma métrica nomeada que conta as solicitações para a API. Você dá o nome que descreve o contador. Esse nome pode ser uma categoria, como read-requests ou write-requests. Outra opção é incluir o nome do método (echo-api/echo_requests, por exemplo) se você estiver definindo uma cota para um método específico.

  • x-google-management.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.

  • x-google-quota.metricCosts: o metricCosts 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 mapeadas. Ao associar um método a uma métrica, você sempre especifica um custo para a solicitação. O custo de cada método pode ser configurado de maneira independente. Isso permite o consumo de métodos distintos em taxas diferentes da mesma métrica. Se você não tiver um requisito de cota complexo, poderá configurar o custo de cada métrica como 1.

Para configurar cotas na API:

  1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
  2. Se você ainda não tiver a extensão x-google-management, adicione uma na raiz do arquivo (sem recuo ou aninhamento) antes da seção que define os caminhos.
  3. Adicione a definição metrics recuada em x-google-management.

    x-google-management:
      metrics:
        - name: "YOUR_METRIC_NAME"
          displayName: "YOUR_METRIC-DISPLAY_NAME"
          valueType: INT64
          metricKind: DELTA
    
    • Substitua YOUR_METRIC_NAME por um nome que descreve o contador de solicitações da API.
    • Para identificar a métrica, substitua YOUR_METRIC_DISPLAY_NAME pelo texto exibido na página Endpoints > Serviços > Cotas.
    • O campo valueType precisa ser INT64.
    • O campo metricKind precisa ser DELTA.
  4. Adicione um campo quota no mesmo nível que metrics e adicione um campo limits aninhado dentro da seção .

    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 precisa ser "1/min/{project}". Esse é o identificador para o limite por minuto 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.
  5. Se quiser, defina métricas e limites adicionais para cada métrica.

  6. Na seção paths do arquivo openapi.yaml, adicione a extensão x-google-quota recuada em todos os métodos que você pretende aplicar uma cota.

    x-google-quota:
      metricCosts:
        YOUR_METRIC_NAME: YOUR_METRIC_COST
    
    • 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.
  7. Salve o arquivo openapi.yaml.

Exemplos de configuração de cota

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

Este exemplo mostra como configurar o campo metric:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA

Este exemplo mostra como configurar os campos quota e limits na seção :

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000

Este exemplo mostra como configurar a extensão x-google-quota na seção paths:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          "read-requests": 1
      security:
      - api_key: []

Para outros exemplos e descrições detalhadas das extensões x-google-management e x-google-quota, consulte Extensões OpenAPI.

Como implantar o arquivo openapi.yaml e o ESP

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

  1. Implante o arquivo openapi.yaml no Service Management, que atualiza a configuração no Endpoints.
  2. implantar o ESP. As etapas para implantar o ESP variam de acordo com o back-end em que sua API foi implantada.

Para ver as etapas detalhadas, consulte Como implantar o back-end da API.