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 esempioread-requests
owrite-requests
. In alternativa, se stai definendo una quota per un metodo specifico, potresti includere il nome del metodo, ad esempioecho-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
: ilmetricCosts
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 sottox-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 essereINT64
. - Il campo
metricKind
deve essereDELTA
.
- Sostituisci
Aggiungi un campo
quota
allo stesso livello dimetrics
e aggiungi un campolimits
nidificato all'interno della sezionequota
.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 valoremetric.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 contenereSTANDARD
. - 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.
- Sostituisci
Facoltativamente, definisci metriche e limiti aggiuntivi per ogni metrica.
Nella sezione
paths
del fileopenapi.yaml
, aggiungi l'estensionex-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 valoremetric.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.
- Sostituisci
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.