Autoriser l'accès invité non authentifié à votre application à l'aide de clés d'API - Amazon Location Service
Comparaison des clés d'API avec Amazon CognitoCréation de clés d'APIUtilisation d'une clé d'API pour appeler une API Amazon LocationUtiliser une clé d'API pour afficher une carteGestion de la durée de vie des clés d'API

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.

Autoriser l'accès invité non authentifié à votre application à l'aide de clés d'API

Lorsque vous appelez les API Amazon Location Service dans vos applications, vous effectuez généralement cet appel en tant qu'utilisateur authentifié autorisé à effectuer les appels d'API. Toutefois, dans certains cas, vous ne souhaitez pas authentifier tous les utilisateurs de votre application. Par exemple, vous souhaiterez peut-être qu'une application Web indiquant l'emplacement de votre entreprise soit accessible à tous ceux qui utilisent le site Web, qu'ils soient connectés ou non. Dans ce cas, une alternative consiste à utiliser des clés d'API pour effectuer les appels d'API.

Les clés d'API sont une valeur clé associée à des ressources Amazon Location Service spécifiques dans vos Compte AWSressources et à des actions spécifiques que vous pouvez effectuer sur ces ressources. Vous pouvez utiliser une clé d'API dans votre application pour effectuer des appels non authentifiés vers les API Amazon Location pour ces ressources. Par exemple, si vous associez une clé d'API à la ressource cartographique MyMap et aux GetMap* actions, une application utilisant cette clé d'API pourra visualiser les cartes créées avec cette ressource, et votre compte sera débité comme toute autre utilisation de votre compte. Cette même clé d'API ne permet pas de modifier ou de mettre à jour la ressource cartographique. Seule l'utilisation de cette ressource est autorisée.

Note

Les clés d'API ne peuvent être utilisées qu'avec les ressources cartographiques, géographiques et routières, et vous ne pouvez ni modifier ni créer ces ressources. Si votre application a besoin d'accéder à d'autres ressources ou actions pour les utilisateurs non authentifiés, vous pouvez utiliser Amazon Cognito pour fournir un accès avec ou à la place des clés d'API. Pour de plus amples informations, veuillez consulter Autoriser l'accès invité non authentifié à votre application à l'aide d'Amazon Cognito.

Les clés d'API incluent une valeur en texte brut qui donne accès à une ou plusieurs ressources de votre Compte AWS. Si quelqu'un copie votre clé d'API, il peut accéder à ces mêmes ressources. Pour éviter cela, vous pouvez spécifier les domaines dans lesquels la clé d'API peut être utilisée lorsque vous créez la clé. Ces domaines sont appelés référents. Si nécessaire, vous pouvez également créer des clés d'API à court terme en définissant des délais d'expiration pour vos clés d'API.

Comparaison des clés d'API avec Amazon Cognito

Les clés d'API et Amazon Cognito sont utilisés de la même manière pour des scénarios similaires, alors pourquoi utiliser l'un plutôt que l'autre ? La liste suivante met en évidence certaines des différences entre les deux.

  • Les clés d'API ne sont disponibles que pour les ressources cartographiques, géographiques et routières, et uniquement pour certaines actions. Amazon Cognito peut être utilisé pour authentifier l'accès à la plupart des API Amazon Location Service.

  • Les performances des requêtes cartographiques avec des clés d'API sont généralement plus rapides que dans des scénarios similaires avec Amazon Cognito. Une authentification simplifiée permet de réduire le nombre d'allers-retours vers le service et de demandes mises en cache lorsque vous obtenez à nouveau la même vignette cartographique en peu de temps.

  • Avec Amazon Cognito, vous pouvez utiliser votre propre processus d'authentification ou combiner plusieurs méthodes d'authentification à l'aide des identités fédérées Amazon Cognito. Pour plus d'informations, consultez Getting Started with Federated Identities dans le manuel Amazon Cognito Developer Guide.

Création de clés d'API

Vous pouvez créer une clé d'API et l'associer à une ou plusieurs ressources de votre Compte AWS.

Vous pouvez créer une clé d'API à l'aide de la console Amazon Location Service AWS CLI, ou des API Amazon Location.

Console
Pour créer une clé d'API à l'aide de la console Amazon Location Service

  1. Dans la console Amazon Location, choisissez les clés d'API dans le menu de gauche.

  2. Sur la page des clés d'API, choisissez Créer une clé d'API.

  3. Sur la page Créer une clé d'API, renseignez les informations suivantes :

    • Nom : nom de votre clé d'API, tel queMyWebAppKey.

    • Description — Description facultative de votre clé d'API.

    • Ressources — Choisissez les ressources Amazon Location auxquelles vous souhaitez donner accès avec cette clé d'API dans la liste déroulante. Vous pouvez ajouter plusieurs ressources en choisissant Ajouter une ressource.

    • Actions — Spécifiez les actions que vous souhaitez autoriser avec cette clé d'API. Vous devez sélectionner au moins une action correspondant à chaque type de ressource sélectionné. Par exemple, si vous avez sélectionné une ressource géographique, vous devez sélectionner au moins l'un des choix sous Actions de localisation.

    • Heure d'expiration : ajoutez éventuellement une date et une heure d'expiration pour votre clé d'API. Pour de plus amples informations, veuillez consulter Gestion de la durée de vie des clés d'API.

    • Référents : ajoutez éventuellement un ou plusieurs domaines dans lesquels vous pouvez utiliser la clé API. Par exemple, si la clé d'API doit autoriser l'exécution d'une application sur le site Webexample.com, vous pouvez la *.example.com/ définir comme référent autorisé.

    • Balises : ajoutez éventuellement des balises à la clé d'API.

  4. Choisissez Create API key pour créer la clé API.

  5. Sur la page détaillée de la clé d'API, vous pouvez consulter les informations relatives à la clé d'API que vous avez créée. Choisissez Afficher la clé d'API pour voir la valeur de clé que vous utilisez lorsque vous appelez les API Amazon Location. La valeur clé aura le formatv1.public.a1b2c3d4.... Pour plus d'informations sur l'utilisation de la clé API pour le rendu de cartes, consultezUtiliser une clé d'API pour afficher une carte.

API

Pour créer une clé d'API à l'aide des API Amazon Location

Utilisez l'CreateKeyopération depuis les API Amazon Location.

L'exemple suivant est une demande d'API visant à créer une clé ExampleKeyd'API appelée sans date d'expiration et à accéder à une seule ressource cartographique. 

POST /metadata/v0/keys HTTP/1.1
Content-type: application/json

{
   "KeyName": "ExampleKey"
   "Restrictions": { 
      "AllowActions": [
         "geo:GetMap*"
      ],
      "AllowResources": [
         "arn:aws:geo:region:map/mapname"
      ]
   },
   "NoExpiry": true
   }
}

La réponse inclut la valeur de la clé d'API à utiliser lors de l'accès aux ressources de vos applications. La valeur clé aura le formatv1.public.a1b2c3d4.... Pour en savoir plus sur l'utilisation de la clé API pour le rendu de cartes, consultezUtiliser une clé d'API pour afficher une carte.

Vous pouvez également utiliser l'DescribeKeyAPI pour trouver la valeur d'une clé ultérieurement.

AWS CLI

Pour créer une clé d'API à l'aide de AWS CLI commandes

Utilisez la commande create-key.

L'exemple suivant crée une clé d'API appelée ExampleKeysans date d'expiration et donnant accès à une seule ressource cartographique. 

aws location \
  create-key \
  --key-name ExampleKey \
  --restrictions '{"AllowActions":["geo:GetMap*"],"AllowResources":["arn:aws:geo:region:map/mapname"]}' \
  --no-expiry

La réponse inclut la valeur de la clé d'API à utiliser lors de l'accès aux ressources de vos applications. La valeur clé aura le formatv1.public.a1b2c3d4.... Pour en savoir plus sur l'utilisation de la clé API pour le rendu de cartes, consultezUtiliser une clé d'API pour afficher une carte. La réponse à create-key ressemble à ce qui suit.

{
    "Key": "v1.public.a1b2c3d4...",
    "KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
    "KeyName": "ExampleKey",
    "CreateTime": "2023-02-06T22:33:15.693Z"
}

Vous pouvez également l'describe-keyutiliser pour rechercher la valeur clé ultérieurement. L'exemple suivant montre comment appeler describe-key une clé d'API nommée ExampleKey.

aws location describe-key \
    --key-name ExampleKey

Utilisation d'une clé d'API pour appeler une API Amazon Location

Après avoir créé une clé d'API, vous pouvez utiliser la valeur de la clé pour appeler les API Amazon Location dans votre application.

Les API qui prennent en charge les clés d'API possèdent un paramètre supplémentaire qui prend la valeur de la clé d'API. Par exemple, si vous appelez l'GetPlaceAPI, vous pouvez renseigner le paramètre clé comme suit

GET /places/v0/indexes/IndexName/places/PlaceId?key=KeyValue

Si vous renseignez cette valeur, vous n'avez pas besoin d'authentifier l'appel d'API avec AWS Sig v4 comme vous le feriez normalement.

Pour JavaScript les développeurs, vous pouvez utiliser Amazon Location JavaScript Aide à l'authentification pour authentifier les opérations d'API à l'aide de clés d'API.

Pour les développeurs mobiles, vous pouvez utiliser les kits SDK d'authentification mobile Amazon Location suivants :

Pour AWS CLI les utilisateurs, lorsque vous utilisez le --key paramètre, vous devez également l'--no-sign-requestutiliser, afin d'éviter de signer avec Sig v4.

Note

Si vous incluez à la fois une signature key et une signature AWS Sig v4 dans un appel à Amazon Location Service, seule la clé d'API est utilisée.

Utiliser une clé d'API pour afficher une carte

Vous pouvez utiliser la valeur de la clé d'API pour afficher une carte dans votre application à l'aide de MapLibre. Cela est un peu différent de l'utilisation des clés d'API dans d'autres API Amazon Location que vous appelez directement, car il MapLibre effectue ces appels pour vous.

L'exemple de code suivant montre comment utiliser la clé API pour afficher une carte sur une simple page Web à l'aide du contrôle cartographique MapLibre GL JS. Pour que ce code fonctionne correctement, remplacez le v1.public. your-api-key-value, us-east-1, et des ExampleMapchaînes dont les valeurs correspondent à votre. Compte AWS

<!-- index.html -->
<html>
  <head>
    <link href="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body { margin: 0; }
      #map { height: 100vh; }
    </style>
  </head>
  <body>
    <!-- Map container -->
    <div id="map" />
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.js"></script>
    <script>
      const apiKey = "v1.public.your-api-key-value"; // API key
      const region = "us-east-1"; // Region
      const mapName = "ExampleMap"; // Map name
      // URL for style descriptor
      const styleUrl = `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=${apiKey}`;
      // Initialize the map
      const map = new maplibregl.Map({
        container: "map",
        style: styleUrl,
        center: [-123.1187, 49.2819],
        zoom: 11,
      });
      map.addControl(new maplibregl.NavigationControl(), "top-left");
    </script>
  </body>
</html>

Gestion de la durée de vie des clés d'API

Vous pouvez créer des clés d'API qui fonctionnent indéfiniment. Toutefois, si vous souhaitez créer une clé d'API temporaire, faire régulièrement pivoter les clés d'API ou révoquer une clé d'API existante, vous pouvez utiliser l'expiration de la clé d'API.

Lorsque vous créez une nouvelle clé d'API ou que vous mettez à jour une clé d'API existante, vous pouvez définir le délai d'expiration de cette clé d'API.

  • Lorsqu'une clé d'API atteint son délai d'expiration, elle est automatiquement désactivée. Les clés inactives ne peuvent plus être utilisées pour effectuer des demandes de cartes.

  • Vous pouvez supprimer une clé d'API 90 jours après l'avoir désactivée.

  • Si vous avez une clé inactive que vous n'avez pas encore supprimée, vous pouvez la restaurer en reportant la date d'expiration à une date future.

  • Pour créer une clé permanente, vous pouvez supprimer le délai d'expiration.

  • Si vous tentez de désactiver une clé d'API qui a été utilisée au cours des 7 derniers jours, il vous sera demandé de confirmer que vous souhaitez apporter la modification. Si vous utilisez l'API Amazon Location Service, ou le AWS CLI, vous recevrez un message d'erreur, sauf si vous définissez le ForceUpdate paramètre sur true.