Questa pagina è stata tradotta dall'API Cloud Translation.

Configurazione delle quote

OpenAPI | gRPC

In questa pagina viene descritto come configurare le quote per l'API. A un livello generale, i passaggi necessari 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 delle funzionalità fornite dalle quote, consulta Informazioni sulle quote.

Prerequisiti

Per iniziare, questa pagina presuppone che tu abbia:

Cloud Endpoints configurati
Esegui il deployment della configurazione di Endpoints.
È stato eseguito il deployment del backend dell'API.
Hai configurato l'API per utilizzare una chiave API. Questo è necessario per consentire a Endpoints di identificare il progetto Google Cloud a cui è associata l'applicazione chiamante. Per ulteriori informazioni, consulta la sezione Condividere API protette da chiave API.

Aggiunta di una quota al documento OpenAPI

La procedura riportata di seguito descrive l'aggiunta delle estensioni richieste al documento OpenAPI per configurare le quote. Per semplicità, in questa pagina il documento OpenAPI è indicato come file openapi.yaml e le estensioni OpenAPI sono fornite solo in formato YAML.

Aggiungi le tre sezioni seguenti al file openapi.yaml:

x-google-management.metrics: una metrica denominata che conteggia le richieste alla tua API. Fornisci un nome che descriva il contatore. Il nome può essere una categoria, ad esempio read-requests o write-requests. In alternativa, se definisci una quota per un metodo specifico, ti consigliamo di 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. Al momento sono supportati solo i limiti per minuto e per progetto.
x-google-quota.metricCosts: metricCosts mappa 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, specifica sempre un costo per la richiesta. Puoi configurare il costo di ciascun metodo indipendentemente. In questo modo, i diversi metodi possono consumare a tassi diversi dalla stessa metrica denominata. 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à fatto, aggiungi l'estensione x-google-management alla directory principale del file (non rientrata o nidificata) prima della sezione che definisce i percorsi.
Aggiungi la definizione di metrics rientrata in 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 descriva il contatore delle richieste 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 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 valore intero. Si tratta del numero di richieste che un'applicazione associata al progetto Google Cloud di un consumatore può effettuare in un 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 per la 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: []

Consulta le estensioni OpenAPI per altri esempi e descrizioni dettagliate delle estensioni x-google-management e x-google-quota.

Esegui il 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 varieranno in base al backend su cui è eseguita l'API.

Per la procedura dettagliata, vedi Eseguire il deployment del backend dell'API.