Configurer les quotas

OpenAPI | gRPC

Cette page explique comment configurer des quotas pour votre API. De manière générale, les étapes sont les suivantes:

Ajoutez les informations sur le quota à votre fichier de configuration d'API gRPC.
Déployez votre fichier de configuration d'API gRPC.
Déployez l'Extensible Service Proxy (ESP).

Pour connaître les fonctionnalités fournies par les quotas, consultez la page À propos des quotas.

Prérequis

Pour commencer, cette page suppose que vous avez :

configuré Cloud Endpoints ;
déployé la configuration Endpoints.
déployé le backend de l'API ;
configuré l'utilisation d'une clé API dans votre API. Cela est nécessaire pour que Endpoints puisse identifier le projet Google Cloud auquel l'application appelante est associée. Consultez la section Partager des API protégées par une clé API pour en savoir plus.

Ajouter un quota à votre fichier de configuration d'API gRPC

La procédure suivante décrit l'ajout des paramètres obligatoires à votre fichier de configuration d'API gRPC pour définir des quotas. Par souci de simplicité, cette page fait référence au fichier de configuration d'API gRPC sous le nom api_config.yaml.

Ajoutez les trois sections suivantes au fichier api_config.yaml :

metrics : métrique nommée qui compte les requêtes adressées à votre API. Vous devez spécifier un nom décrivant le compteur. Le nom peut être une catégorie, telle que read-requests ou write-requests. Si vous définissez un quota pour une méthode spécifique, vous pouvez également inclure le nom de la méthode, par exemple echo-api/echo_requests.
quota.limits : représente une limite unique applicable à une métrique nommée. Cette section vous permet de configurer le nombre autorisé de requêtes pour une métrique que vous avez définie. Actuellement, seules les limites par minute et par projet sont acceptées.
quota.metric_rules : metric_rule mappe les méthodes sur des métriques (plusieurs à plusieurs). L'envoi d'une requête à une méthode alloue un compteur pour chacune des métriques mappées. Lorsque vous associez une méthode à une métrique, vous spécifiez toujours un coût par requête. Vous pouvez configurer le coût de chaque méthode indépendamment. Cela permet à différentes méthodes de consommer à des rythmes différents à partir de la même métrique nommée. Si vous n'avez pas d'exigences complexes en matière de quota, vous pouvez configurer le coût de chaque métrique sur 1.

Pour configurer des quotas sur votre API :

Ouvrez le fichier api_config.yaml de votre projet dans un éditeur de texte.
Ajoutez le champ metrics en haut du fichier (il ne doit pas être en retrait ni imbriqué), en dessous du champ apis.
```
metrics:
  - name: "YOUR_METRIC_NAME"
    display_name: "YOUR_METRIC_DISPLAY_NAME"
        value_type: INT64
    metric_kind: DELTA`
```
- Remplacez YOUR_METRIC_NAME par un nom qui décrit le compteur de requêtes API.
- Remplacez YOUR_METRIC_DISPLAY_NAME par le texte qui est affiché sous Endpoints > Services > Quotas afin d'identifier la métrique.
- Le champ value_type doit être INT64.
- Le champ metric_kind doit être DELTA.
Ajoutez un champ quota au même niveau que metrics, puis insérez un champ imbriqué limits dans la section quota.
```
quota:
  limits:
    - name: "YOUR_LIMIT_NAME"
      metric: "YOUR_METRIC_NAME"
      unit: "1/min/{project}"
      values:
        STANDARD: VALUE_FOR_THE_LIMIT
```
- Remplacez YOUR_LIMIT_NAME par un nom qui décrit la limite.
- Remplacez YOUR_METRIC_NAME par un nom metric.name déjà défini.
- Le champ unit doit être "1/min/{project}". Il s'agit de l'identifiant de la limite par projet et par minute.
- Le champ values doit contenir l'information STANDARD.
- Remplacez VALUE_FOR_THE_LIMIT par une valeur entière. Il s'agit du nombre de requêtes qu'une application associée au projet Google Cloud d'un utilisateur est autorisée à effectuer par minute.
(Facultatif) Définissez d'autres métriques et limites pour chaque métrique.
Ajoutez une ligne metric_rules en retrait sous quota, après la section limits. Dans la section metric_rules, associez une métrique déjà définie à une méthode, comme suit :
```
metric_rules:
  - metric_costs:
      YOUR_METRIC_NAME: YOUR_METRIC_COST
    selector: [METHODS]
```
- Remplacez YOUR_METRIC_NAME par un nom metric.name déjà défini.
- Remplacez YOUR_METRIC_COST par une valeur entière. Le nombre que vous indiquez pour le coût est ajouté au compteur de requêtes de la métrique pour chaque requête.
- Pour le champ selector, vous pouvez spécifier l'un des éléments suivants :
  - Pour associer toutes les méthodes de toutes les API à metric_cost, utilisez selector: "*".
  - Pour associer une méthode spécifique d'une API à metric_cost, utilisezselector: YOUR_API_NAME.*.
  - Pour associer une méthode spécifique d'une API à metric_cost, utilisezselector: YOUR_API_NAME.YOUR_METHOD_NAME.
Enregistrez le fichier api_config.yaml.

Exemples de configuration de quota

Les trois exemples suivants montrent comment configurer des quotas sur votre API.

L'exemple suivant montre comment configurer le champ metric :

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA`

L'exemple suivant montre comment configurer les champs quota et limits dans la section quota :

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: 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'exemple suivant montre comment configurer la ligne metrics après la section limits :

  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      display_name: "Read requests"
      value_type: INT64
      metric_kind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
    metric_rules:
      - metric_costs:
          "read-requests": 1
        selector: *

Déployer le fichier `api_config.yaml` et Extensible Service Proxy

Pour que le quota soit appliqué, vous devez procéder comme suit :

Déployez le fichier api_config.yaml dans Service Management, qui met à jour la configuration dans Endpoints. Pour connaître la procédure détaillée, consultez la page Déployer la configuration Endpoints.
Déployez l'ESP. Pour connaître la procédure détaillée, consultez la page Déployer le backend de l'API.