Cette page a été traduite par l'API Cloud Translation.

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 OpenAPI.
Déployez votre fichier de configuration OpenAPI.
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 document OpenAPI

La procédure suivante décrit l'ajout à votre document OpenAPI des extensions nécessaires pour configurer des quotas. Par souci de simplicité, cette page fait référence au fichier de configuration OpenAPI sous le nom openapi.yaml et fournit les extensions OpenAPI uniquement au format YAML.

Ajoutez les trois sections suivantes au fichier openapi.yaml :

x-google-management.metrics : métrique nommée qui compte les requêtes adressées à votre API. Vous devez spécifier un nom décrivant le compteur. Il peut s'agir d'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
x-google-management.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.
x-google-quota.metricCosts : metricCosts 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 taux différents depuis 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 openapi.yaml de votre projet dans un éditeur de texte.
Si vous ne possédez pas déjà l'extension x-google-management, ajoutez-la à la racine du fichier ci-dessus là où les chemins sont définis (elle ne doit pas être en retrait ni imbriquée).
Ajoutez la définition metrics en retrait sous x-google-management.
```
x-google-management:
  metrics:
    - name: "YOUR_METRIC_NAME"
      displayName: "YOUR_METRIC-DISPLAY_NAME"
      valueType: INT64
      metricKind: 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 valueType doit être INT64.
- Le champ metricKind 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 peut exécuter en une minute.
(Facultatif) Définissez d'autres métriques et limites pour chaque métrique.
Dans la section paths du fichier openapi.yaml, ajoutez l'extension x-google-quota en retrait sous chaque méthode à laquelle vous souhaitez appliquer un quota.
```
x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
```
- 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.
Enregistrez le fichier openapi.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 :

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

L'exemple suivant montre comment configurer les champs quota et limits dans la section 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'exemple suivant montre comment configurer l'extension x-google-quota dans la section 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: []

Consultez la page sur les extensions OpenAPI pour obtenir d'autres exemples et des descriptions détaillées concernant les extensions x-google-management et x-google-quota.

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

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

Déployez le fichier openapi.yaml dans Service Management, qui met à jour la configuration dans Endpoints.
Déployez l'ESP. Les étapes de déploiement d'ESP varient en fonction du backend sur lequel votre API est déployée.

Pour connaître la procédure détaillée, consultez la page sur le déploiement du backend de l'API.