Como configurar cotas

OpenAPI | gRPC

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

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

configurou os Cloud Endpoints
implantado a configuração do Endpoints
implantado o back-end da API;
Configurar a API para usar uma chave de API. Isso é necessário para que o Endpoints identifique o projeto do Google Cloud ao qual o aplicativo de chamada está associado. Para mais informações, veja Como compartilhar APIs protegidas por chaves.

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:

Abra o arquivo openapi.yaml do projeto em um editor de texto.
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.
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.
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 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.
Se quiser, defina métricas e limites adicionais para cada métrica.
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.
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 quota:

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:

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

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