Configuration de plans d’utilisation pour les API REST dans API Gateway

Avant de créer un plan d’utilisation, assurez-vous d’avoir configuré vos clés API. Pour plus d’informations, consultez Configuration de clés API pour les API REST dans API Gateway.

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. Cependant, vous devez utiliser la propriété UsagePlan apiStages pour associer les valeurs d’étape d’API spécifiées (apiId et stage) aux clés d’API incluses (via UsagePlanKey) au lieu d’utiliser la propriété ApiKey stageKeys.

Pour vérifier si vous avez déjà migré vers les plans d’utilisation par défaut, utilisez la commande CLI get-account. 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 API vers les plans d’utilisation par défaut à l’aide de l’AWS CLI comme suit :

Pour migrer vers les plans d’utilisation par défaut à l’aide de l’AWS CLI

1. Appelez cette commande CLI : update-account.

2. 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.

2. Dans le panneau de navigation principal d’Amazon API Gateway, choisissez Plans d’utilisation, puis Créer un plan d’utilisation.

   

3. Pour Nom, entrez un nom.

4. (Facultatif) Sous Description, entrez une description.

5. 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.

6. 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.

7. Choisissez Créer un plan d’utilisation.

AWS CLI

La commande create-usage-plan suivante crée un plan d’utilisation qui se réinitialise 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 usageplan:create 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.

2. Sous l’onglet Étapes associées, choisissez Ajouter une étape.

   

3. Pour API, sélectionnez une API.

4. Pour Étape, sélectionnez une étape.

5. (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.

   2. Pour Ressource, sélectionnez une ressource dans votre API.

   3. Pour Méthode, sélectionnez une méthode dans votre API.

   4. Entrez un Taux et un Débit pour votre plan d'utilisation.

6. Choisissez Ajouter au plan d’utilisation.

AWS CLI

La commande update-usage-plan suivante ajoute l’étape Prod 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 usageplan:update 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.

   

2. 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.

   2. 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.

3. Choisissez Ajouter une clé d’API.

AWS CLI

La commande create-usage-plan-key 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 usageplankey:create pour associer une clé d’API existante à un plan d’utilisation.

Vous pouvez également associer directement vos clés API à un plan d’utilisation au moment de leur importation. Appelez apikey:import 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.