Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Plans d'utilisation et clés d'API pour REST APIs dans API Gateway
Après avoir créé, testé et déployé votre APIs, vous pouvez utiliser les plans d'utilisation d'API Gateway pour les rendre disponibles sous forme d'offres de produits pour vos clients. Vous pouvez configurer des plans d'utilisation et des clés d'API pour permettre aux clients d'accéder à certains APIs d'entre eux et commencer à limiter les demandes sur la APIs base de limites et de quotas définis. Ils peuvent être définis au niveau de l’API ou de la méthode API.
## Que sont les plans d’utilisation et les clés d’API ?
Un *plan d’utilisation* spécifie qui peut accéder à une ou plusieurs méthodes et étapes d’API déployées et définit le taux de requête cible pour commencer à limiter les requêtes. Le plan utilise des clés d’API afin d’identifier les clients et mesure les accès aux étapes d’API associées pour chaque clé.
Les *clés d’API* sont des valeurs de chaînes alphanumériques que vous distribuez aux clients des développeurs d’applications pour leur accorder l’accès à l’API. Vous pouvez utiliser des clés d'API conjointement avec des [autorisateurs Lambda, des](apigateway-use-lambda-authorizer.md) [rôles IAM](permissions.md) ou Amazon Cognito pour contrôler l'[accès](apigateway-integrate-with-cognito.md) à votre. APIs API Gateway peut générer des clés d’API pour vous ou vous pouvez les importer à partir d’un [fichier CSV](api-key-file-format.md). Vous pouvez générer une clé d’API dans API Gateway ou l’importer dans API Gateway à partir d’une source externe. Pour de plus amples informations, veuillez consulter [Configuration des clés d'API pour REST APIs dans API Gateway](api-gateway-setup-api-keys.md).
Chaque clé d’API a un nom et une valeur. (Les termes « clé d’API » et « valeur de clé d’API » sont souvent utilisés de manière interchangeable.) Le nom ne peut pas dépasser 1 024 caractères. La valeur est une chaîne alphanumérique comportant entre 20 et 128 caractères, par exemple, `apikey1234abcdefghij0123456789`.
**Important**
Les valeurs de clés d’API doivent être uniques. Si vous tentez de créer deux clés d’API nommées différemment mais avec la même valeur, API Gateway les considère comme une seule et même clé d’API.
Une clé d'API peut être associée à plusieurs plans d'utilisation. Un plan d'utilisation peut être associé à plusieurs étapes. Toutefois, une clé d'API donnée ne peut être associée qu'à un seul plan d'utilisation pour chaque étape de votre API.
Une *limitation* définit le point cible auquel la limitation des requêtes doit commencer. Ils peuvent être définis au niveau de l’API ou de la méthode d’API.
Une *limite de quota* détermine le nombre maximal de requêtes autorisées pour une clé d’API donnée sur un intervalle de temps spécifié. Vous pouvez configurer les méthodes d’API pour exiger une autorisation de clé d’API selon la configuration du plan d’utilisation.
Les limites de quota et de restriction s’appliquent aux diverses demandes de clés d’API qui sont regroupées pour toutes les étapes d’API au sein d’un plan d’utilisation.
**Note**
La limitation des plans d’utilisation et les quotas ne sont pas des limites strictes et sont appliquées au mieux. Dans certains cas, les clients peuvent dépasser les quotas que vous avez définis. Ne comptez pas sur les quotas de plan d’utilisation ni sur la limitation pour contrôler les coûts ou bloquer l’accès à une API. Pensez à utiliser [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) pour contrôler les coûts et [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) pour gérer les demandes d'API.
## Bonnes pratiques concernant les clés d’API et les plans d’utilisation
Voici quelques suggestions de bonnes pratiques à suivre lors de l’utilisation de clés d’API et de plans d’utilisation.
**Important**
N'utilisez pas de clés d'API pour l'authentification ou l'autorisation afin de contrôler l'accès à votre APIs. Si vous en avez plusieurs APIs dans un plan d'utilisation, un utilisateur possédant une clé d'API valide pour une API de ce plan d'utilisation peut accéder APIs à *toutes les* API de ce plan d'utilisation. Pour contrôler l’accès à votre API, utilisez plutôt un rôle IAM, un [Mécanisme d’autorisation Lambda](apigateway-use-lambda-authorizer.md) ou un [Groupe d’utilisateurs Amazon Cognito](apigateway-integrate-with-cognito.md).
Utilisez les clés d’API générées par API Gateway. Les clés d’API ne doivent pas inclure d’informations confidentielles ; les clients les transmettent généralement dans des en-têtes qui peuvent être enregistrés.
+ Si vous utilisez un portail pour développeurs pour publier votre APIs, notez que les clients peuvent souscrire à tous les abonnements d'un plan d'utilisation donné, même si vous ne les avez pas rendus visibles à vos clients. APIs
+ Dans certains cas, les clients peuvent dépasser les quotas que vous avez définis. Ne vous fiez pas aux plans d’utilisation pour contrôler les coûts. Pensez à utiliser [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) pour contrôler les coûts et [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) pour gérer les demandes d'API.
+ Une fois que vous avez ajouté une clé d’API à un plan d’utilisation, l’opération de mise à jour peut prendre quelques minutes.
# Choix d’une source de clé d’API dans API Gateway
Lorsque vous associez un plan d’utilisation à une API et activez des clés d’API sur les méthodes d’API, chaque demande entrante vers l’API doit inclure une [clé d’API](api-gateway-basic-concept.md#apigateway-definition-api-key). API Gateway lit la clé et la compare à celles du plan d’utilisation. S’il y a correspondance, API Gateway restreint les demandes en fonction des limitations et quotas définis dans le plan. Sinon, il renvoie une exception `InvalidKeyParameter`. En conséquence, l’appelant reçoit une réponse `403 Forbidden`.
Votre API API Gateway peut recevoir des clés d’API à partir de l’une de ces deux sources :
**`HEADER`**
Vous distribuez les clés d’API à vos clients et leur demandez de les transmettre comme en-tête `X-API-Key` de chaque demande entrante.
**`AUTHORIZER`**
Un mécanisme d’autorisation Lambda renvoie la clé d’API dans le cadre de la réponse d’autorisation. Pour plus d’informations sur la réponse d’autorisation, consultez [Sortie d’un mécanisme d’autorisation Lambda API Gateway](api-gateway-lambda-authorizer-output.md).
**Note**
Pour connaître les bonnes pratiques à prendre en compte, consultez [Bonnes pratiques concernant les clés d’API et les plans d’utilisation](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
La procédure ci-dessous montre comment choisir une source de clé d’API pour une API.
------
#### [ AWS Management Console ]
**Pour choisir une source de clé d’API pour une API**
1. Connectez-vous à la console API Gateway.
1. Choisissez une API existante ou créez-en une.
1. Dans le panneau de navigation principal, choisissez **Paramètres de l’API**.
1. Dans la section **Détails de l'API**, choisissez **Modifier**.
1. Sous **Source de clé d’API**, sélectionnez `Header` ou `Authorizer` dans la liste déroulante.
1. Sélectionnez **Enregistrer les modifications**.
------
#### [ AWS CLI ]
La [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante met à jour une API afin de définir la source de la clé d'API sur `AUTHORIZER` :
```
aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER
```
Pour que le client soumette une clé d’API, définissez `value` sur `HEADER` dans la commande précédente.
------
#### [ REST API ]
Pour choisir une source de clé d’API pour une API à l’aide de l’API REST API Gateway, appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) comme suit :
```
PATCH /restapis/fugvjdxtri/ HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160603T205348Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/apiKeySource",
"value" : "HEADER"
}
]
}
```
Pour avoir qu’un mécanisme d’autorisation renvoie une clé d’API, définissez la `value` sur `AUTHORIZER` dans l’entrée `patchOperations` précédente.
------
# Format de fichier de clé d’API API Gateway
API Gateway peut importer les clés d’API à partir de fichiers externes au format CSV (valeurs séparées par des virgules), puis associer les clés importées à un ou plusieurs plans d’utilisation. Le fichier importé doit comporter les colonnes `Name` et `Key`. Les noms d’en-tête de colonne ne sont pas sensibles à la casse et les colonnes peuvent être dans n’importe quel ordre, comme illustré dans l’exemple suivant :
```
Key,name
apikey1234abcdefghij0123456789,MyFirstApiKey
```
Une valeur `Key` doit comprendre entre 20 et 128 caractères. Une valeur `Name` ne peut pas dépasser 1 024 caractères.
Un fichier de clé d’API peut également contenir la colonne `Description`, `Enabled` ou `UsagePlanIds`, comme illustré dans l’exemple suivant :
```
Name,key,description,Enabled,usageplanIds
MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b
```
Lorsqu'une clé est associée à plusieurs plans d'utilisation, la `UsagePlanIds` valeur est une chaîne du plan d'utilisation séparée par des virgules IDs, entre guillemets doubles ou simples, comme indiqué dans l'exemple suivant :
```
Enabled,Name,key,UsageplanIds
true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr"
```
Les colonnes non reconnues sont autorisées, mais sont ignorées. La valeur par défaut est une chaîne vide ou une valeur booléenne `true`.
Il est possible d’importer la même clé d’API plusieurs fois, auquel cas la version la plus récente remplace la précédente. Deux clés d’API sont identiques si elles ont la même valeur `key`.
**Note**
Pour connaître les bonnes pratiques à prendre en compte, consultez [Bonnes pratiques concernant les clés d’API et les plans d’utilisation](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
# Configuration des clés d'API pour REST APIs dans API Gateway
Pour configurer les clés d’API, procédez comme suit :
+ Configurez des méthodes API pour exiger une clé d’API.
+ Créez ou importez une clé d’API pour l’API dans une région.
Avant de configurer des clés d’API, vous devez avoir créé une API et l'avoir déployée jusqu'à une étape. Une fois que vous avez créé une valeur de clé d'API, elle ne peut pas être modifiée.
Pour obtenir les instructions de création et de déploiement d’une API à l’aide de la console API Gateway, consultez [Développez REST APIs dans API Gateway](rest-api-develop.md) et [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md), respectivement.
Une fois votre clé d’API créée, vous devez l’associer à un plan d’utilisation. Pour de plus amples informations, veuillez consulter [Configurer des plans d'utilisation pour REST APIs dans API Gateway](api-gateway-create-usage-plans.md).
**Note**
Pour connaître les meilleures pratiques à prendre en compte, voir[Bonnes pratiques concernant les clés d’API et les plans d’utilisation](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
**Topics**
+ [Exigence d'une clé d’API sur une méthode](#api-gateway-usage-plan-configure-apikey-on-method)
+ [Création d’une clé d’API](#api-gateway-usage-plan-create-apikey)
+ [Importation de clés d’API](#api-gateway-usage-pan-import-apikey)
## Exigence d'une clé d’API sur une méthode
La procédure suivante explique comment configurer une méthode d’API pour exiger une clé d’API.
------
#### [ AWS Management Console ]
**Pour configurer une méthode d’API pour exiger une clé d’API**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Dans le panneau de navigation principal d’API Gateway, choisissez **Resources (Ressources)**.
1. Sous **Resources**, créez une méthode ou choisissez une méthode existante.
1. Dans l'onglet **Demande de méthode**, sous **Paramètres de demande de méthode**, choisissez **Modifier**.
![\[Ajout d’une clé d’API à une méthode\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png)
1. Sélectionnez **Clé d’API obligatoire**.
1. Choisissez **Enregistrer**.
1. Déployez ou redéployez l’API pour que l’exigence prenne effet.
Si l’option **Clé d’API obligatoire** est définie sur `false` et que vous n’exécutez pas les étapes précédentes, aucune clé d’API associée à une étape d’API n’est utilisée pour la méthode.
------
#### [ AWS CLI ]
La commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante crée une méthode `PUT` qui nécessite une clé d’API :
```
aws apigateway put-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type "NONE" \
--api-key-required
```
La commande [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) suivante met à jour une méthode existante pour qu’elle exige une clé d’API :
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/apiKeyRequired",value="true"
```
------
#### [ REST API ]
Pour exiger une clé d’API sur une méthode, exécutez l’une des actions suivantes :
+ Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) pour créer une méthode. Définissez `apiKeyRequired` sur `true` dans la charge utile de la demande.
+ Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) pour définir `apiKeyRequired` sur `true`.
------
## Création d’une clé d’API
La procédure suivante montre comment créer une clé d’API. Si vous désirez importer votre clé d’API, ignorez cette étape.
------
#### [ AWS Management Console ]
**Pour créer une clé d’API**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Dans le panneau de navigation principal d’API Gateway, choisissez **Clés d’API**.
1. Choisissez **Créer une clé d’API**.
![\[Création de clés d’API pour les plans d’utilisation\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png)
1. Pour **Nom**, entrez un nom.
1. (Facultatif) Sous **Description**, entrez une description.
1. Pour **Clé d’API**, choisissez **Autogénérer** pour qu’API Gateway génère la valeur de la clé, ou choisissez **Personnalisé** pour créer votre propre valeur de clé.
1. Choisissez **Enregistrer**.
------
#### [ AWS CLI ]
La [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html)commande suivante crée une clé d'API :
```
aws apigateway create-api-key \
--name 'Dev API key' \
--description 'API key for Devs' \
--enabled
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) pour créer une clé d’API.
------
## Importation de clés d’API
La procédure suivante explique comment importer des clés d’API. Si vous avez déjà créé une clé d’API, ignorez cette étape.
------
#### [ AWS Management Console ]
**Pour importer des clés d’API**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Dans le panneau de navigation principal, choisissez **Clés d’API**.
1. Choisissez le menu déroulant **Actions**, puis choisissez **Importer des clés d’API**.
1. Pour charger un fichier de clés séparées par des virgules, sélectionnez **Choisissez un fichier**. Vous pouvez également entrer les clés dans l’éditeur de texte. Pour plus d’informations sur le format de fichier, consultez [Format de fichier de clé d’API API Gateway](api-key-file-format.md).
1. Choisissez **Échouer avec les avertissements** pour arrêter l’importation en cas d’erreur, ou **Ignorer les avertissements** pour continuer à importer les entrées de clé valides en cas d’avertissement.
1. Choisissez **Importer** pour importer vos clés d’API.
------
#### [ AWS CLI ]
La [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html)commande suivante importe une clé d'API :
```
aws apigateway import-api-key \
a--body fileb://keys.csv \
--format csv
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) pour importer une clé d’API à partir d’un fichier. Pour le format de fichier, consultez [Format de fichier de clé d’API API Gateway](api-key-file-format.md).
------
Vous ne pouvez pas modifier la valeur de la nouvelle clé d’API. Une fois votre API créée, vous allez configurer un plan d’utilisation. Pour de plus amples informations, veuillez consulter [Configurer des plans d'utilisation pour REST APIs dans API Gateway](api-gateway-create-usage-plans.md).
# Configurer des plans d'utilisation pour REST APIs dans API Gateway
Avant de créer un plan d’utilisation, assurez-vous d’avoir configuré vos clés d’API. Pour de plus amples informations, veuillez consulter [Configuration des clés d'API pour REST APIs dans API Gateway](api-gateway-setup-api-keys.md).
**Topics**
+ [Migration de votre API vers les plans d’utilisation par défaut (si nécessaire)](#api-gateway-usage-plan-migrate-to-default)
+ [Création d'un plan d'utilisation](#api-gateway-usage-plan-create)
+ [Ajout d’une étape d’API à un plan d’utilisation.](#api-gateway-usage-plan-add-stage)
+ [Ajout d’une clé d’API à un plan d’utilisation](#api-gateway-usage-plan-add-key)
## Migration de votre API vers les plans d’utilisation par défaut (si nécessaire)
Si vous avez commencé à utiliser API Gateway *après* le déploiement de la fonction des plans d’utilisation le 11 août 2016, les plans d’utilisation seront automatiquement activés dans toutes les régions prises en charge.
Si vous avez commencé à utiliser API Gateway avant cette date, vous devrez peut-être migrer vers les plans d’utilisation par défaut. Vous serez invité à définir l’option **Enable Usage Plans** (Activer les plans d’utilisation) avant d’utiliser des plans d’utilisation pour la première fois dans la région sélectionnée. Lorsque vous activez cette option, des plans d’utilisation par défaut sont créés pour chaque étape d’API unique associée aux clés d’API existantes. Dans le plan d’utilisation par défaut, aucune limitation ou limite de quota n’est définie initialement, et les associations entre les clés d’API et les étapes d’API sont copiées dans les plans d’utilisation. L’API se comporte de la même manière qu’auparavant. Toutefois, vous devez utiliser la [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html)`apiStages`propriété pour associer les valeurs d'étape d'API spécifiées (`apiId`et`stage`) aux clés d'API incluses (via [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)), au lieu d'utiliser la [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html)`stageKeys`propriété.
Pour vérifier si vous avez déjà migré vers les plans d’utilisation par défaut, utilisez la commande CLI [https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html). Dans la sortie de la commande, la liste `features` inclut une entrée de `"UsagePlans"` lorsque les plans d’utilisation sont activés.
Vous pouvez également migrer vos plans d'utilisation APIs vers les plans d'utilisation par défaut en utilisant AWS CLI ce qui suit :
**Pour passer aux plans d'utilisation par défaut à l'aide du AWS CLI**
1. Appelez cette commande CLI : [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html).
1. Pour le paramètre `cli-input-json`, utilisez le code JSON suivant :
```
[
{
"op": "add",
"path": "/features",
"value": "UsagePlans"
}
]
```
## Création d'un plan d'utilisation
La procédure suivante explique comment créer un plan d'utilisation.
------
#### [ AWS Management Console ]
**Pour créer un plan d’utilisation**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Dans le panneau de navigation principal d’Amazon API Gateway, choisissez **Plans d’utilisation**, puis **Créer un plan d’utilisation**.
![\[Entités de plan d'utilisation d'API\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png)
1. Pour **Nom**, entrez un nom.
1. (Facultatif) Sous **Description**, entrez une description.
1. Par défaut, les plans d’utilisation permettent une limitation. Entrez un **Taux** et un **Débit** pour votre plan d'utilisation. Choisissez **Limitation** pour désactiver la limitation.
1. Par défaut, les plans d’utilisation activent un quota pour une période donnée. Pour **Demandes**, entrez le nombre total de demandes qu’un utilisateur peut effectuer au cours de la période de votre plan d’utilisation. Choisissez **Quota** pour désactiver le quota.
1. Choisissez **Créer un plan d’utilisation**.
------
#### [ AWS CLI ]
La [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html)commande suivante crée un plan d'utilisation qui est réinitialisé au début du mois :
```
aws apigateway create-usage-plan \
--name "New Usage Plan" \
--description "A new usage plan" \
--throttle burstLimit=10,rateLimit=5 \
--quota limit=500,offset=0,period=MONTH
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) pour créer un plan d’utilisation.
------
## Ajout d’une étape d’API à un plan d’utilisation.
La procédure suivante explique comment ajouter une étape à un plan d’utilisation.
------
#### [ AWS Management Console ]
**Pour ajouter une étape à un plan d’utilisation**
1. Sélectionnez votre plan d’utilisation.
1. Sous l’onglet **Étapes associées**, choisissez **Ajouter une étape**.
![\[Ajout d’une étape d’API à un plan d’utilisation.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png)
1. Pour **API**, sélectionnez une API.
1. Pour **Étape**, sélectionnez une étape.
1. (Facultatif) Pour activer la limitation au niveau de la méthode, procédez comme suit :
1. Choisissez **Limitation au niveau de la méthode**, puis choisissez **Ajouter une méthode**.
1. Pour **Ressource**, sélectionnez une ressource dans votre API.
1. Pour **Méthode**, sélectionnez une méthode dans votre API.
1. Entrez un **Taux** et un **Débit** pour votre plan d'utilisation.
1. Choisissez **Ajouter au plan d’utilisation**.
------
#### [ AWS CLI ]
La [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)commande suivante ajoute l'`Prod`étape d'une API à un plan d'utilisation :
```
aws apigateway update-usage-plan \
--usage-plan-id abc123 \
--patch-operations op="add",path="/apiStages",value="a1b1c2:Prod"
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) pour mettre à jour un plan d’utilisation.
------
## Ajout d’une clé d’API à un plan d’utilisation
La procédure suivante montre comment ajouter une clé d’API à un plan d’utilisation.
------
#### [ AWS Management Console ]
**Pour ajouter une clé à un plan d’utilisation**
1. Sous l’onglet **Clés d’API associées**, choisissez **Ajouter une clé d’API**.
![\[Entités de plan d'utilisation d'API\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png)
1.
1. Pour associer une clé existante à votre plan d’utilisation, sélectionnez **Ajouter une clé existante**, puis sélectionnez votre clé existante dans le menu déroulant.
1. Pour créer une nouvelle clé d’API, sélectionnez **Créer et ajouter une clé**, puis créez une nouvelle clé. Pour plus d’informations sur la création d’une nouvelle clé, consultez [Création d’une clé d’API](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey).
1. Choisissez **Ajouter une clé d’API**.
------
#### [ AWS CLI ]
La [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html)commande suivante associe une clé d'API existante à un plan d'utilisation :
```
aws apigateway create-usage-plan-key \
--usage-plan-id a1b2c3 \
--key-type "API_KEY" \
--key-id aaa111bbb
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html) pour associer une clé d’API existante à un plan d’utilisation.
Vous pouvez également associer directement vos APIs clés à un plan d'utilisation lorsque vous les importez. Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) pour ajouter directement une ou plusieurs clés d’API au plan d’utilisation spécifié. La charge utile de la requête doit contenir les valeurs de clé d’API, l’identifiant du plan d’utilisation associé, les indicateurs booléens permettant d’indiquer que les clés sont activées pour le plan d’utilisation et, éventuellement, les noms et descriptions des clés d’API.
L’exemple suivant de requête `apikey:import` ajoute trois clés d’API (identifiées par `key`, `name` et `description`) à un plan d’utilisation (identifié par `usageplanIds`) :
```
POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1
Host: apigateway.us-east-1.amazonaws.com
Content-Type: text/csv
Authorization: ...
key,name, description, enabled, usageplanIds
abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt
abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt
abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt
```
En conséquence, trois ressources `UsagePlanKey` sont créées et ajoutées au plan d’utilisation `UsagePlan`.
Vous pouvez également ajouter des clés d’API à plusieurs plans d’utilisation de cette façon. Pour ce faire, remplacez la valeur de chaque colonne `usageplanIds` par une chaîne indiquée entre guillemets contenant les identifiants des plans d’utilisation sélectionnés, séparés par des virgules (`"n371pt,m282qs"` ou `'n371pt,m282qs'`).
------
**Note**
Une clé d'API peut être associée à plusieurs plans d'utilisation. Un plan d'utilisation peut être associé à plusieurs étapes. Toutefois, une clé d'API donnée ne peut être associée qu'à un seul plan d'utilisation pour chaque étape de votre API.
# Maintenir un plan d'utilisation pour REST APIs dans API Gateway
La gestion d’un plan d’utilisation implique la surveillance des quotas utilisés et restants sur une période donnée et, si besoin, l’extension des quotas restants selon une valeur spécifiée. Les procédures suivantes expliquent comment surveiller les quotas.
------
#### [ AWS Management Console ]
**Pour surveiller les quotas utilisés et restants**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Dans le panneau de navigation principal d'API Gateway, choisissez **Plans d'utilisation**.
1. Sélectionnez un plan d'utilisation.
1. Choisissez l'onglet **Clés d'API associées** pour voir le nombre de demandes restantes pendant la période de temps pour chaque clé.
1. (Facultatif) Choisissez **Exporter les données d’utilisation**, puis choisissez une date de début **De** et une date de fin **À**. Choisissez ensuite **JSON** ou **CSV** pour le format des données exportées, puis choisissez **Exporter**.
L’exemple suivant montre un fichier exporté.
```
{
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
}
```
Les données d’utilisation de cet exemple présentent les données d’utilisation quotidiennes d’un client d’API, identifié par la clé d’API (`px1KW6...qBazOJH`), entre le 1er août 2016 et le 3 août 2016. Les données d’utilisation de chaque jour montrent les quotas utilisés et restants. Dans cet exemple, l’abonné n’a pas encore commencé à utiliser ses quotas alloués et le propriétaire ou l’administrateur de l’API a réduit le quota restant de 5 000 à 10 le troisième jour.
Les procédures suivantes expliquent comment modifier les quotas.
**Pour étendre les quotas restants**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Dans le panneau de navigation principal d'API Gateway, choisissez **Plans d'utilisation**.
1. Sélectionnez un plan d'utilisation.
1. Choisissez l'onglet **Clés d'API associées** pour voir le nombre de demandes restantes pendant la période de temps pour chaque clé.
1. Sélectionnez une clé d’API, puis choisissez **Accorder une extension d’utilisation**.
1. Entrez un nombre pour définir le quota **Demandes restantes**. Vous pouvez augmenter ou réduire le nombre de demandes restantes pendant la durée de votre plan d’utilisation.
1. Choisissez **Mettre à jour le quota**.
------
#### [ AWS CLI ]
Les [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)exemples suivants ajoutent, suppriment ou modifient les paramètres de régulation au niveau de la méthode dans un plan d'utilisation.
**Note**
Assurez-vous de remplacer `us-east-1` par la région appropriée pour votre API.
Pour ajouter ou remplacer une limitation de taux afin de restreindre une ressource et une méthode en particulier :
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/rateLimit",value="0.1"
```
Pour ajouter ou remplacer une limitation du mode rafale afin de restreindre une ressource et une méthode en particulier :
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/burstLimit",value="1"
```
Pour supprimer les paramètres de limitation au niveau méthode pour une ressource et une méthode en particulier :
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod",value=""
```
Pour supprimer tous les paramètres de limitation au niveau de la méthode pour une API :
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle ",value=""
```
Voici un extrait utilisant l’exemple d’API Pet Store :
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'
```
------
#### [ REST API ]
Appelez [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) pour gérer un plan d’utilisation.
------
# Créez et configurez des clés d'API et des plans d'utilisation avec CloudFormation
Vous pouvez l'utiliser CloudFormation pour exiger des clés d'API sur les méthodes d'API et créer un plan d'utilisation pour une API. L'exemple de CloudFormation modèle effectue les opérations suivantes :
+ Il crée une API dans l’API Gateway avec les méthodes `GET` et `POST`.
+ Il nécessite une clé d’API pour les méthodes `GET` et `POST`. Cette API reçoit des clés à partir de l’en-tête `X-API-KEY` de chaque demande entrante.
+ Il crée une clé d’API.
+ Il crée un plan d’utilisation pour spécifier un quota mensuel de 1 000 demandes par mois, une limite de taux de limitation de 100 demandes par seconde et une limitation de débit en rafale de 200 demandes par seconde.
+ Il spécifie une limite de fréquence de limitation au niveau de la méthode de 50 demandes par seconde et une limite de fréquence de limitation au niveau de la méthode de 100 demandes par seconde pour la méthode `GET`.
+ Il associe l’étape d’API et la clé d’API au plan d’utilisation.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
KeyName:
Type: String
Default: MyKeyName
Description: Name of an API key
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: keys-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
UsagePlan:
Type: AWS::ApiGateway::UsagePlan
DependsOn:
- ApiDeployment
Properties:
Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET
ApiStages:
- ApiId: !Ref Api
Stage: !Sub '${StageName}'
Throttle:
"/pets/GET":
RateLimit: 50.0
BurstLimit: 100
Quota:
Limit: 1000
Period: MONTH
Throttle:
RateLimit: 100.0
BurstLimit: 200
UsagePlanName: "My Usage Plan"
ApiKey:
Type: AWS::ApiGateway::ApiKey
Properties:
Description: API Key
Name: !Sub '${KeyName}'
Enabled: True
UsagePlanKey:
Type: AWS::ApiGateway::UsagePlanKey
Properties:
KeyId: !Ref ApiKey
KeyType: API_KEY
UsagePlanId: !Ref UsagePlan
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# Configuration d’une méthode pour utiliser des clés d’API avec une définition OpenAPI
Vous pouvez utiliser une définition OpenAPI pour exiger des clés d’API sur une méthode.
Pour chaque méthode, créez un objet d’exigence de sécurité afin d’exiger une clé d’API pour invoquer la méthode. Définissez ensuite `api_key` dans la définition de la sécurité. Après avoir créé votre API, ajoutez la nouvelle étape d’API à votre plan d’utilisation.
L’exemple suivant crée une API et exige une clé d’API pour les méthodes `POST` et `GET` :
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "2024-03-14T20:20:12Z",
"title" : "keys-api"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/pets" : {
"get" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
},
"post" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
}
}
},
"securityDefinitions" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "keys-api",
"version" : "2024-03-14T20:20:12Z"
},
"servers" : [ {
"url" : "{basePath}",
"variables" : {
"basePath" : {
"default" : "v1"
}
}
} ],
"paths" : {
"/pets" : {
"get" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
},
"post" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
}
}
},
"components" : {
"securitySchemes" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
}
```
------
# Tester les plans d'utilisation de REST APIs dans API Gateway
À titre d'exemple, utilisons l' PetStore API, qui a été créée dans[Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md). Supposons que l’API est configurée pour utiliser la clé d’API `Hiorr45VR...c4GJc`. Les étapes suivantes expliquent comment tester un plan d’utilisation.
**Pour tester votre plan d’utilisation**
+ Envoyez une demande `GET` sur la ressource Pets (`/pets`), avec les paramètres de requête `?type=...&page=...` de l’API (par exemple, `xbvxlpijch`) dans un plan d’utilisation :
```
GET /testStage/pets?type=dog&page=1 HTTP/1.1
x-api-key: Hiorr45VR...c4GJc
Content-Type: application/x-www-form-urlencoded
Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com
X-Amz-Date: 20160803T001845Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}
```
**Note**
Vous devez envoyer cette demande au composant `execute-api` d’API Gateway et fournir la clé d’API requise (par exemple, `Hiorr45VR...c4GJc`) dans l’en-tête `x-api-key` requis.
La réponse positive renvoie un code de statut `200 OK` et une charge utile qui contient les résultats demandés obtenus du backend. Si vous oubliez de définir l’en-tête `x-api-key` ou si vous le définissez avec une clé incorrecte, vous obtenez une réponse `403 Forbidden`. Toutefois, si vous n’avez pas configuré la méthode pour exiger une clé d’API, vous obtiendrez probablement une réponse `200 OK` que vous définissiez l’en-tête `x-api-key` correctement ou non, et les limites de quota et de restriction du plan d’utilisation seront ignorées.
Parfois, lorsqu’une erreur interne se produit qui empêche API Gateway d’appliquer les limitations de plan d’utilisation ou les quotas pour la demande, API Gateway traite la demande sans appliquer les limitations ou les quotas comme indiqué dans le plan d’utilisation. En revanche, il consigne un message d'erreur `Usage Plan check failed due to an internal error` dans CloudWatch. Vous pouvez ignorer ces erreurs occasionnelles.
# Appel d’une méthode à l’aide d’une clé d’API
En fonction du type de source de la clé d’API que vous choisissez, appliquez l’une des procédures suivantes pour utiliser une clé d’API issue de l’en-tête ou une clé d’API renvoyée par un mécanisme d’autorisation dans l’appel de méthode :
**Pour utiliser une clé d’API issue d’un en-tête :**
1. Créez une API avec les méthodes d'API souhaitées, puis déployez l'API dans une étape.
1. Créez un nouveau plan d'utilisation ou choisissez un plan d'utilisation existant. Ajoutez l'étape d'API déployée au plan d'utilisation. Attachez une clé API au plan d'utilisation ou choisissez une clé API existante dans le plan. Notez la valeur de clé API choisie.
1. Configurez des méthodes d’API pour exiger une clé API.
1. Redéployez l'API à la même étape. Si vous déployez l'API pour une nouvelle étape, assurez-vous de mettre à jour le plan d'utilisation pour attacher la nouvelle étape d'API.
1. Appelez l’API à l’aide de la clé d’API. L’exemple de commande curl suivant invoque la méthode `GET` sur la ressource `getUsers` de l’étape `prod` d’une API à l’aide d’une clé d’API.
```
curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
Le client peut désormais appeler les méthodes d’API tout en fournissant l’en-tête `x-api-key` avec la clé API choisie comme valeur d’en-tête. Un appel peut se présenter comme suit :
**Pour utiliser une clé d’API issue d’un mécanisme d’autorisation :**
1. Créez une API avec les méthodes d'API souhaitées, puis déployez l'API dans une étape.
1. Créez un nouveau plan d'utilisation ou choisissez un plan d'utilisation existant. Ajoutez l'étape d'API déployée au plan d'utilisation. Attachez une clé API au plan d'utilisation ou choisissez une clé API existante dans le plan. Notez la valeur de clé API choisie.
1. Créez un mécanisme d’autorisation Lambda par jeton. Incluez, `usageIdentifierKey:{api-key}` en tant que propriété de niveau racine de la réponse d’autorisation. Pour apprendre à créer un mécanisme d’autorisation par jeton, consultez [Exemple de fonction de mécanisme d’autorisation Lambda `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create).
1. Configurez des méthodes d’API pour exiger une clé d’API et activer le mécanisme d’autorisation Lambda sur les méthodes.
1. Redéployez l'API à la même étape. Si vous déployez l'API pour une nouvelle étape, assurez-vous de mettre à jour le plan d'utilisation pour attacher la nouvelle étape d'API.
Le client peut désormais appeler les méthodes API key-required sans fournir explicitement une clé API. La clé API retournant le mécanisme d’autorisation est utilisée automatiquement.