Configurazione delle quote

OpenAPI | gRPC

In questa pagina viene descritto come configurare le quote per l'API. A livello generale, i passaggi sono:

Aggiungere le informazioni sulla quota al file di configurazione OpenAPI.
Distribuire il file di configurazione OpenAPI.
Esegui il deployment di Extensible Service Proxy (ESP).

Per una panoramica della funzionalità fornita in base alle quote, consulta Informazioni sulle quote.

Prerequisiti

Per iniziare, questa pagina presuppone che tu abbia:

Cloud Endpoints configurato
Distribuito la configurazione di Endpoints.
Deployment del backend dell'API.
Configurato l'API in modo da utilizzare una chiave API. Questo è necessario affinché gli endpoint identifichino il progetto Google Cloud a cui è associata l'applicazione chiamante. Per ulteriori informazioni, consulta Condivisione delle API protette da una chiave API.

Aggiunta di una quota al documento OpenAPI

La procedura seguente descrive l'aggiunta delle estensioni necessarie al documento OpenAPI per configurare le quote. Per semplicità, questa pagina fa riferimento al documento OpenAPI come file openapi.yaml e fornisce le estensioni OpenAPI solo in formato YAML.

Aggiungi le seguenti tre sezioni al file openapi.yaml:

x-google-management.metrics: una metrica denominata che conteggia le richieste all'API. Devi fornire un nome che descriva il contatore. Il nome può essere una categoria, ad esempio read-requests o write-requests. In alternativa, se stai definendo una quota per un metodo specifico, potresti includere il nome del metodo, ad esempio echo-api/echo_requests
x-google-management.quota.limits: rappresenta un singolo limite applicabile per una metrica denominata. Qui puoi configurare il numero consentito di richieste per una metrica che hai definito. Attualmente sono supportati solo i limiti al minuto per progetto.
x-google-quota.metricCosts: il metricCosts consente di mappare i metodi alle metriche (many-to-many). Una richiesta a un metodo alloca un contatore per ciascuna delle metriche mappate. Quando associ un metodo a una metrica, devi sempre specificare un costo per la richiesta. Puoi configurare il costo di ogni metodo in modo indipendente. Ciò consente di utilizzare diversi metodi a velocità diverse dalla stessa metrica con nome. Se non hai un requisito di quota complesso, puoi configurare il costo di ogni metrica su 1.

Per configurare le quote nell'API:

Apri il file openapi.yaml del progetto in un editor di testo.
Se non l'hai già, aggiungi l'estensione x-google-management alla radice del file (non in posizione rientrata o nidificata) prima della sezione che definisce i percorsi.
Aggiungi la definizione di metrics rientrata sotto x-google-management.
```
x-google-management:
  metrics:
    - name: "YOUR_METRIC_NAME"
      displayName: "YOUR_METRIC-DISPLAY_NAME"
      valueType: INT64
      metricKind: DELTA
```
- Sostituisci YOUR_METRIC_NAME con un nome che descrive il contatore delle richieste dell'API.
- Sostituisci YOUR_METRIC_DISPLAY_NAME con il testo visualizzato nella pagina Endpoint > Servizi > Quote per identificare la metrica.
- Il campo valueType deve essere INT64.
- Il campo metricKind deve essere DELTA.
Aggiungi un campo quota allo stesso livello di metrics e aggiungi un campo limits nidificato all'interno della sezione quota.
```
quota:
  limits:
    - name: "YOUR_LIMIT_NAME"
      metric: "YOUR_METRIC_NAME"
      unit: "1/min/{project}"
      values:
        STANDARD: VALUE_FOR_THE_LIMIT
```
- Sostituisci YOUR_LIMIT_NAME con un nome che descriva il limite.
- Sostituisci YOUR_METRIC_NAME con un valore metric.name definito in precedenza.
- Il campo unit deve essere "1/min/{project}". Questo è l'identificatore del limite per minuto per progetto.
- Il campo values deve contenere STANDARD.
- Sostituisci VALUE_FOR_THE_LIMIT con un numero intero. Questo è il numero di richieste che un'applicazione associata al progetto Google Cloud di un consumatore può effettuare al minuto.
Facoltativamente, definisci metriche e limiti aggiuntivi per ogni metrica.
Nella sezione paths del file openapi.yaml, aggiungi l'estensione x-google-quota rientrata sotto ogni metodo a cui vuoi applicare una quota.
```
x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
```
- Sostituisci YOUR_METRIC_NAME con un valore metric.name definito in precedenza.
- Sostituisci YOUR_METRIC_COST con un numero intero. Per ogni richiesta, il contatore delle richieste della metrica viene incrementato del numero specificato per il costo.
Salva il file openapi.yaml.

Esempi di configurazione delle quote

I tre esempi seguenti mostrano come configurare le quote nell'API.

L'esempio seguente mostra come configurare il campo metric:

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

L'esempio seguente mostra come configurare i campi quota e limits nella sezione 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

L'esempio seguente mostra come configurare l'estensione x-google-quota nella sezione 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: []

Per ulteriori esempi e descrizioni dettagliate delle estensioni x-google-management e x-google-quota, consulta la pagina relativa alle estensioni OpenAPI.

Deployment del file `openapi.yaml` e dell'ESP

Affinché la quota abbia effetto, dovrai:

Esegui il deployment del file openapi.yaml in Service Management, che aggiorna la configurazione in Endpoints.
Esegui il deployment dell'ESP. I passaggi per il deployment dell'ESP variano a seconda del backend in cui viene eseguito il deployment dell'API.

Per la procedura dettagliata, vedi Deployment del backend dell'API.