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ê tenha:

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 são fornecidas extensões dessa OpenAPI apenas em formato YAML.

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

  • x-google-management.metrics: uma métrica nomeada que conta as solicitações para a API. Você fornece um nome que descreve o contador. Por exemplo, uma categoria, como read-requests ou write-requests. Para definir uma cota para um método específico, uma alternativa é incluir o nome do método, por exemplo, echo-api/echo_requests.

  • x-google-management.quota.limits: representa um único limite aplicável a 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 (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. É possível configurar o custo de cada método 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 seu projeto em um editor de texto.
  2. Caso ainda não tenha um, adicione a extensão x-google-management à raiz do arquivo (não recuada ou aninhada) antes da seção que define os caminhos.
  3. Adicione a definição de metrics pretendida 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 descreva 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 valueType precisa ser INT64.
    • O campo metricKind precisa ser DELTA.
  4. Adicione um campo quota no mesmo nível de 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 previamente definido.
    • 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. Este é o número de solicitações que um aplicativo associado ao projeto do GCP de um consumidor pode fazer em um minuto.
  5. Opcionalmente, defina métricas e limites complementares para cada métrica.

  6. Na seção paths do arquivo openapi.yaml, adicione a extensão x-google-quota recuada em cada método ao qual você quer aplicar uma cota.

    x-google-quota:
      metricCosts:
        YOUR_METRIC_NAME: YOUR_METRIC_COST
    
    • Substitua YOUR_METRIC_NAME por um metric.name previamente definido.
    • Substitua YOUR_METRIC_COST por um número inteiro. Para cada solicitação, o contador de solicitações da métrica é incrementado pelo 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.

O exemplo a seguir 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 a seguir mostra como configurar os campos de quota e limits na seção de 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 a seguir 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: []

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

Como implantar o arquivo openapi.yaml e ESP

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

  1. implantar o arquivo openapi.yaml no Service Management, que atualiza a configuração no Cloud 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.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com OpenAPI
Precisa de ajuda? Acesse nossa página de suporte.