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.

# Utiliser des clés d'API pour s'authentifier
<a name="using-apikeys"></a>

**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 [Utiliser Amazon Cognito pour vous authentifier](authenticating-using-cognito.md).

Les *clés d'API* sont une valeur clé associée à des ressources ou à une API Amazon Location Service spécifiques dans vos ressources Compte AWS, ainsi qu'à 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 Amazon Location APIs pour ces ressources. 

Par exemple, si vous associez une clé d'API à une ressource, and/or l'`GetPlace*`API, une application qui utilise cette clé d'API pourra appeler des ressources spécifiques APIs. Cette même clé d'API n'autoriserait pas la modification ou la mise à jour d'une ressource ou d'un appel APIs auquel elle n'est pas associée.

Lorsque vous appelez Amazon Location Service APIs dans vos applications, vous effectuez généralement cet appel en tant qu'*utilisateur authentifié* autorisé à effectuer les appels d'API. Cependant, 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.

Consultez [Bonnes pratiques clés en matière d'API](#api-keys-best-practices) pour plus d'informations sur les circonstances dans lesquelles utiliser les clés d'API.

Pour plus d'informations sur l'utilisation des clés à l'aide de l'API Amazon Location Service, consultez les rubriques suivantes dans le manuel *Amazon Location Service API Reference* :
+ [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)
+ [DeleteKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DeleteKey.html)
+ [DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html)
+ [ListKeys](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ListKeys.html)

## Création d'une clé d'API pour Amazon Location Service
<a name="create-api-key"></a>

Vous pouvez créer une clé d'API via la console Amazon Location Service ou l'API Amazon Location. AWS CLI Continuez avec les procédures appropriées ci-dessous.

------
#### [ Amazon Location console ]

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

1. Dans la [https://console.aws.amazon.com/location](https://console.aws.amazon.com/location), choisissez **les clés d'API** dans le menu de gauche.

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

1. Sur la page **Créer une clé d'API**, renseignez les informations suivantes :
   + **Nom** : nom de votre clé d'API, tel que`ExampleKey`.
   + **Description — Description** facultative de votre clé d'API.
   + **Ressources** — Dans le menu déroulant, choisissez les ressources Amazon Location auxquelles vous souhaitez donner accès avec cette clé d'API. 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 [Bonnes pratiques clés en matière d'API](#api-keys-best-practices).
   + **Restrictions relatives aux clients** : ajoutez éventuellement un ou plusieurs domaines Web ou une ou plusieurs applications Android ou Apple 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 Web`example.com`, vous pouvez la `*.example.com/` définir comme référent autorisé.
   + **Balises** : ajoutez éventuellement des balises à la clé d'API.

1. Choisissez **Create API key** pour créer la clé API.

1. 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 Amazon Location APIs. La valeur clé aura le format`v1.public.a1b2c3d4...`. 

------
#### [ AWS CLI ]

1. Utilisez la commande [Create-Key](https://docs.aws.amazon.com/cli/latest/reference/location/create-key.html). L'exemple suivant crée une clé d'API appelée `ExampleKey` sans date d'expiration et sans accès à une seule ressource cartographique.

   ```
   aws location \
     create-key \
     --key-name ExampleKey \
     --restrictions '{"AllowActions":["geo-maps:*"],"AllowResources":["arn:aws:geo-maps:region::provider/default"]}' \
     --no-expiry
   ```

1. 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 format`v1.public.a1b2c3d4...`. Pour en savoir plus sur l'utilisation de la clé API pour le rendu de cartes, consultez[Utiliser une clé d'API pour appeler une API Amazon Location](#using-apikeys-in-api). La réponse à create-key se présente comme suit :

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

1. Vous pouvez également l'`describe-key`utiliser 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
   ```

------
#### [ Amazon Location API ]

Utilisez l'[CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)opération depuis l'emplacement Amazon APIs. L'exemple suivant est une demande d'API pour créer une clé d'API appelée `ExampleKey` sans date d'expiration et sans accès à une seule ressource cartographique.

```
POST /metadata/v0/keys HTTP/1.1
Content-type: application/json
{
  "KeyName": "ExampleKey",
  "NoExpiry": true,
  "Restrictions": {
    "AllowActions": [
      "geo-places:*",
      "geo-routes:*",
      "geo-maps:*"
    ],
    "AllowResources": [
      "arn:aws:geo-places:Region::provider/default",
      "arn:aws:geo-routes:Region::provider/default",
      "arn:aws:geo-maps:Region::provider/default"
    ]
  }
}
```

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 format. `v1.public.a1b2c3d4...`

Vous pouvez également utiliser l'[DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html)API pour trouver la valeur d'une clé ultérieurement.

------

## Utiliser une clé d'API pour appeler une API Amazon Location
<a name="using-apikeys-in-api"></a>

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

------
#### [ API ]

Les clés APIs d'API compatibles ont un paramètre supplémentaire qui prend la valeur de la clé d'API. Par exemple, si vous appelez l'`GetPlace`API, vous pouvez renseigner le paramètre [clé](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html) comme suit

```
curl --request GET —url 'https://places.geo.eu-central-1.amazonaws.com/v2/place/{PLACEID}?key={APIKEY}&language=jp'
```

------
#### [ AWS CLI ]

Lorsque vous utilisez le `--key` paramètre, vous devez également l'`--no-sign-request`utiliser pour éviter de signer avec Sig v4.

```
aws geo-places get-place --place-id $PLACEID --language jp --key $APIKEY
```

------
#### [ SDK (web) ]

Utilisez le code suivant :

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Display a map</title>
        <meta property="og:description" content="Initialize a map in an HTML element with MapLibre GL JS." />
        <meta charset='utf-8'>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.css' />
        <script src='https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.js'></script>
        <style>
            body { margin: 0; }
            #map { height: 100vh; }
        </style>
    </head>
    <body>
         
        <div id="map"></div>
        <script>
     
            const apiKey = "<api key>"; // check how to create api key for Amazon Location
            const mapStyle = "Standard";  // eg. Standard, Monochrome, Hybrid, Satellite  
            const awsRegion = "eu-central-1"; // eg. us-east-2, us-east-1, us-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ca-central-1, eu-central-1, eu-west-1, eu-west-2, eu-south-2, eu-north-1, sa-east-1
            const styleUrl = `https://maps.geo.${awsRegion}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`;


            const map = new maplibregl.Map({
                container: 'map', // container id
                style: styleUrl, // style URL
                center: [25.24,36.31], // starting position [lng, lat]
                zoom: 2, // starting zoom
            });
        </script>
    </body>
</html>
```

------
#### [ SDK (iOS, Swift) ]

Utilisez le code suivant :

```
import UIKit
import MapLibre

class ViewController: UIViewController {
    let apiKey = "Enter your API key" // The previously-created API Key to use
    let regionName = "Enter your region name" // The service region - us-east-1, ap-south-1, etc
    var mapView: MLNMapView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        loadMap()
    }
    
    func loadMap() {
        let styleName = "Standard" // The map style - Standard, Monochrome, Hybrid, Satellite
        let colorName = "Light" // The color scheme - Light, Dark
        
        // The Amazon Location Service map style URL that MapLibre will use to render the maps.
        let styleURL = URL(string: "https://maps.geo.\(regionName).amazonaws.com/v2/styles/\(styleName)/descriptor?key=\(apiKey)&color-scheme=\(colorName)")

        // Initialize MapLibre        
        mapView = MLNMapView(frame: view.bounds)
        mapView.styleURL = styleURL
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        // Set the starting camera position and zoom level for the map
        mapView.setCenter(CLLocationCoordinate2D(latitude: 49.246559, longitude: -123.063554), zoomLevel: 10, animated: false)
        view.addSubview(mapView!)
    }
}
```

------
#### [ SDK (Android, Kotlin) ]

Utilisez le code suivant :

```
class MapActivity : Activity(), OnMapReadyCallback {

    private lateinit var mBinding: ActivityMapBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initializeMap(savedInstanceState)
    }

    private fun initializeMap(savedInstanceState: Bundle?) {
        // Init MapLibre
        // See the MapLibre Getting Started Guide for more details
        // https://maplibre.org/maplibre-native/docs/book/android/getting-started-guide.html
        MapLibre.getInstance(this@MapActivity)
        mBinding = ActivityMapBinding.inflate(layoutInflater)
        setContentView(mBinding.root)
        mBinding.mapView.onCreate(savedInstanceState)
        mBinding.mapView.getMapAsync(this)
    }

    override fun onMapReady(mapLibreMap: MapLibreMap) {
        mapLibreMap.setStyle(Style.Builder().fromUri(getMapUrl())) {
            // Set the starting camera position
            mapLibreMap.cameraPosition = CameraPosition.Builder().target(LatLng(49.246559, -123.063554)).zoom(10.0).build()
            mapLibreMap.uiSettings.isLogoEnabled = false
            mapLibreMap.uiSettings.attributionGravity = Gravity.BOTTOM or Gravity.END
            mapLibreMap.uiSettings.setAttributionDialogManager(AttributionDialogManager(this, mapLibreMap))
        }
    }

    // Return the Amazon Location Service map style URL
    // MapLibre will use this to render the maps.
    // awsRegion: The service region - us-east-1, ap-south-1, etc
    // mapStyle: The map style - Standard, Monochrome, Hybrid, Satellite  
    // API_KEY: The previously-created API Key to use
    // colorName: The color scheme to use - Light, Dark
    private fun getMapUrl() =
           "https://maps.geo.${getString(R.string.awsRegion)}.amazonaws.com/v2/styles/${getString(R.string.mapStyle)}/descriptor?key=${BuildConfig.API_KEY}&color-scheme=${getString(R.string.colorName)}"

    override fun onStart() {
        super.onStart()
        mBinding.mapView.onStart()
    }

    override fun onResume() {
        super.onResume()
        mBinding.mapView.onResume()
    }

    override fun onPause() {
        super.onPause()
        mBinding.mapView.onPause()
    }

    override fun onStop() {
        super.onStop()
        mBinding.mapView.onStop()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mBinding.mapView.onSaveInstanceState(outState)
    }

    override fun onLowMemory() {
        super.onLowMemory()
        mBinding.mapView.onLowMemory()
    }

    override fun onDestroy() {
        super.onDestroy()
        mBinding.mapView.onDestroy()
    }
}
```

------

## Limiter l'utilisation des clés d'API par origine de demande
<a name="restrict-usage-by-origin"></a>

Vous pouvez configurer des clés d'API avec des restrictions client qui limitent l'accès à des domaines ou à des applications mobiles spécifiques. Lors de la restriction par domaine, les demandes ne seront autorisées que si l'en-tête HTTP Referer correspond à la valeur que vous avez fournie. En cas de restriction par une application Android ou Apple, les demandes ne seront autorisées que si les champs d'en-tête HTTP de l'identifiant de l'application correspondent aux valeurs que vous fournissez.

Pour plus d'informations, consultez [ApiKeyRestrictions](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ApiKeyRestrictions.html)le manuel *Amazon Location Service API Reference*.

**Identifiants des applications Android :**
+ `X-Android-Package`:

  Identifiant unique pour les applications Android, défini dans le `build.gradle` fichier de l'application, généralement selon un format de domaine inversé.

  Exemple :

  `com.mydomain.appname`
+ `X-Android-Cert`:

  Le hachage SHA-1 du certificat de signature utilisé pour signer l'APK Android.

  Exemple :

  `BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75`

**Identifiants des applications Apple :**
+ `X-Apple-Bundle-Id `:

  Identifiant unique pour les applications Apple (iOS, macOS, etc.), défini dans les applications`Info.plist`, généralement selon un format de domaine inversé.

  Exemple :

  `com.mydomain.appname`

## Bonnes pratiques clés en matière d'API
<a name="api-keys-best-practices"></a>

Les clés d'API incluent une *valeur* en texte brut qui donne accès à une ou plusieurs ressources ou APIs à votre Compte AWS. Si quelqu'un copie votre clé d'API, il peut accéder à ces mêmes ressources et APIs. Pour minimiser l'impact potentiel, passez en revue les meilleures pratiques suivantes :
+ **Limiter la clé d'API**

  Pour éviter la situation ci-dessus, il est préférable de limiter votre clé d'API. Lorsque vous créez la clé, vous pouvez spécifier le domaine, l'application Android ou l'application Apple où la clé peut être utilisée.
+ **Gérez 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*.
  + Vous pouvez définir le délai d'expiration d'une clé d'API lorsque vous la créez ou la mettez à jour.
  + 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.
  + Vous pouvez remplacer une clé temporaire par une clé permanente en supprimant le délai d'expiration.
  + Vous pouvez supprimer une clé d'API 90 jours après l'avoir désactivée.
  + Si vous tentez de désactiver une clé d'API qui a été utilisée au cours des sept 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, définissez le `ForceUpdate` paramètre sur`true`, sinon vous recevrez un message d'erreur.