Esta página foi traduzida pela API Cloud Translation.

Configurar quotas

OpenAPI | gRPC

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

Adicione as informações sobre a quota ao seu ficheiro de configuração da OpenAPI.
Implemente o ficheiro de configuração da OpenAPI.
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:

Cloud Endpoints configurados
Implementou a configuração dos Endpoints.
Implementou o back-end da API.
Configurou a sua API para usar uma chave da API. Isto é necessário para que os pontos finais identifiquem o Google Cloud projeto ao qual a aplicação de chamada está associada. Consulte o artigo Partilhar APIs protegidas por chave da API para mais informações.

Adicionar uma quota ao seu documento OpenAPI

O procedimento seguinte descreve a adição das extensões necessárias ao seu documento OpenAPI para configurar quotas. Para simplificar, esta página refere-se ao documento OpenAPI como o ficheiro openapi.yaml e fornece as extensões OpenAPI apenas no formato YAML.

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

x-google-management.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
x-google-management.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.
x-google-quota.metricCosts: o metricCosts 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:

Abra o ficheiro openapi.yaml do projeto num editor de texto.
Se ainda não a tiver, adicione a extensão x-google-management na raiz do ficheiro (sem recuo nem aninhamento) antes da secção que define os caminhos.
Adicione a definição de metrics com recuo abaixo de 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 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 valueType tem de ser INT64.
- O campo metricKind tem de ser DELTA.
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
Opcionalmente, defina métricas e limites adicionais para cada métrica.
Na secção paths do ficheiro openapi.yaml, adicione a extensão x-google-quota com recuo abaixo de cada método ao qual quer aplicar uma quota.
```
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 pedido, o contador de pedidos da métrica é incrementado pelo número que especificar para o custo.
Guarde o ficheiro openapi.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:

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

O exemplo seguinte mostra como configurar os campos quota e limits na secçã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

O exemplo seguinte mostra como configurar a extensão x-google-quota na secçã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: []

Consulte as extensões OpenAPI para ver mais exemplos e descrições detalhadas das extensões x-google-management e x-google-quota.

Implementar o ficheiro `openapi.yaml` e o SEP

Para que a quota entre em vigor, tem de:

Implemente o ficheiro openapi.yaml na gestão de serviços, o que atualiza a configuração nos pontos finais.
Implemente o ESP. Os passos para implementar o ESP variam consoante o back-end no qual a sua API está implementada.

Para ver passos detalhados, consulte o artigo Implementar o back-end da API.