Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Usa le chiavi API per l'autenticazione
<a name="using-apikeys"></a>

**Nota**  
Le chiavi API possono essere utilizzate solo con risorse di **mappe**, **luoghi** e **percorsi** e non è possibile modificare o creare tali risorse. Se la tua applicazione richiede l'accesso ad altre risorse o azioni per gli utenti non autenticati, puoi utilizzare Amazon Cognito per fornire l'accesso insieme o al posto delle chiavi API. Per ulteriori informazioni, consulta [Usa Amazon Cognito per l'autenticazione](authenticating-using-cognito.md).

Le *chiavi API* sono un valore chiave associato a risorse o API specifiche di Amazon Location Service presenti nella tua Account AWS azienda e ad azioni specifiche che puoi eseguire su tali risorse. Puoi utilizzare una chiave API nella tua applicazione per effettuare chiamate non autenticate all'Amazon Location APIs per tali risorse. 

Ad esempio, se associ una chiave API a una risorsa, and/or l'`GetPlace*`applicazione che utilizza quella chiave API sarà in grado di effettuare chiamate specifiche. APIs La stessa chiave API non fornirebbe le autorizzazioni per modificare o aggiornare alcuna risorsa o chiamata a APIs cui non è associata.

Quando chiami Amazon Location Service APIs nelle tue applicazioni, in genere effettui questa chiamata come *utente autenticato* autorizzato a effettuare le chiamate API. Tuttavia, ci sono alcuni casi in cui non desideri autenticare tutti gli utenti della tua applicazione. 

Ad esempio, potresti volere che un'applicazione web che mostri la sede della tua attività commerciale sia disponibile per tutti gli utenti del sito Web, indipendentemente dal fatto che abbiano effettuato l'accesso o meno. In questo caso, un'alternativa consiste nell'utilizzare le chiavi API per effettuare le chiamate API.

Vedi [Le migliori pratiche relative alle chiavi API](#api-keys-best-practices) per ulteriori informazioni su quando utilizzare le chiavi API.

Per ulteriori informazioni sull'utilizzo delle chiavi utilizzando l'API Amazon Location Service, consulta i seguenti argomenti nel *riferimento all'API di Amazon Location Service*:
+ [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)

## Crea una chiave API per Amazon Location Service
<a name="create-api-key"></a>

Puoi creare una chiave API tramite la console Amazon Location Service o AWS CLI l'API Amazon Location. Continua con le procedure appropriate riportate di seguito.

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

**Per creare una chiave API utilizzando la console Amazon Location Service**

1. Nella [https://console.aws.amazon.com/location](https://console.aws.amazon.com/location), scegli **le chiavi API** dal menu a sinistra.

1. Nella pagina delle **chiavi API**, scegli **Crea chiave API**.

1. Nella pagina **Crea chiave API**, inserisci le seguenti informazioni:
   + **Nome**: un nome per la tua chiave API, ad esempio`ExampleKey`.
   + **Descrizione**: una descrizione opzionale per la tua chiave API.
   + **Risorse**: nel menu a discesa, scegli le risorse di Amazon Location a cui consentire l'accesso con questa chiave API. Puoi aggiungere più di una risorsa selezionando **Aggiungi risorsa**.
   + **Azioni**: specifica le azioni che desideri autorizzare con questa chiave API. È necessario selezionare almeno un'azione che corrisponda a ciascun tipo di risorsa selezionato. Ad esempio, se hai selezionato una risorsa relativa ai luoghi, devi selezionare almeno una delle scelte in **Azioni relative ai luoghi**.
   + **Ora di scadenza**: facoltativamente, aggiungi una data e un'ora di scadenza per la tua chiave API. Per ulteriori informazioni, consulta [Le migliori pratiche relative alle chiavi API](#api-keys-best-practices).
   + **Restrizioni per i client**: facoltativamente, aggiungi uno o più domini Web o una o più app Android o Apple in cui puoi utilizzare la chiave API. Ad esempio, se la chiave API serve a consentire l'esecuzione di un'applicazione sul sito Web`example.com`, puoi inserirla `*.example.com/` come referente consentito.
   + **Tag**: facoltativamente, aggiungi tag alla chiave API.

1. Scegli **Crea chiave API** per creare la chiave API.

1. Nella pagina dei dettagli della chiave API, puoi visualizzare le informazioni sulla chiave API che hai creato. Scegli **Mostra chiave API** per vedere il valore della chiave che usi quando chiami Amazon Location APIs. Il valore della chiave avrà il formato`v1.public.a1b2c3d4...`. 

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

1. Usa il comando [create-key](https://docs.aws.amazon.com/cli/latest/reference/location/create-key.html). L'esempio seguente crea una chiave API chiamata senza data `ExampleKey` di scadenza e accesso a una singola risorsa della mappa.

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

1. La risposta include il valore della chiave API da utilizzare per accedere alle risorse nelle applicazioni. Il valore chiave avrà il formato`v1.public.a1b2c3d4...`. Per ulteriori informazioni sull'utilizzo della chiave API per il rendering delle mappe, consulta[Usa una chiave API per chiamare un'API Amazon Location](#using-apikeys-in-api). La risposta a create-key è simile alla seguente:

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

1. Puoi anche usarlo `describe-key` per trovare il valore della chiave in un secondo momento. L'esempio seguente mostra come `describe-key` richiamare una chiave API denominata`ExampleKey`.

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

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

Usa l'[CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)operazione dalla sede Amazon APIs. L'esempio seguente è una richiesta API per creare una chiave API chiamata senza data di scadenza e `ExampleKey` con accesso a una singola risorsa della mappa.

```
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 risposta include il valore della chiave API da utilizzare per accedere alle risorse delle applicazioni. Il valore chiave avrà il formato`v1.public.a1b2c3d4...`.

Puoi anche utilizzare l'[DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html)API per trovare il valore della chiave per una chiave in un secondo momento.

------

## Usa una chiave API per chiamare un'API Amazon Location
<a name="using-apikeys-in-api"></a>

Dopo aver creato una chiave API, puoi utilizzare il valore della chiave per effettuare chiamate ad Amazon Location APIs nella tua applicazione.

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

Le chiavi API APIs che supportano le chiavi API hanno un parametro aggiuntivo che assume il valore della chiave API. Ad esempio, se chiami l'`GetPlace`API, puoi inserire il parametro [chiave](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html) nel modo seguente

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

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

Quando si utilizza il `--key` parametro, è necessario utilizzare anche il `--no-sign-request` parametro, per evitare di firmare con Sig v4.

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

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

Eseguire il seguente codice:

```
<!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) ]

Eseguire il seguente codice:

```
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) ]

Eseguire il seguente codice:

```
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()
    }
}
```

------

## Limita l'utilizzo delle chiavi API in base all'origine della richiesta
<a name="restrict-usage-by-origin"></a>

Puoi configurare le chiavi API con restrizioni client che limitano l'accesso a domini o applicazioni mobili specifici. In caso di restrizioni per dominio, le richieste verranno autorizzate solo se l'intestazione HTTP Referer corrisponde al valore fornito. In caso di restrizioni per applicazione Android o Apple, le richieste saranno autorizzate solo se i campi di intestazione HTTP dell'identificatore dell'applicazione corrispondono ai valori forniti.

Per ulteriori informazioni, consulta il *riferimento [ApiKeyRestrictions](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ApiKeyRestrictions.html)all'API di Amazon Location Service*.

**Identificatori di applicazioni Android:**
+ `X-Android-Package`:

  Un identificatore univoco per le applicazioni Android, definito nel `build.gradle` file dell'app, in genere con un formato a dominio inverso.

  Esempio:

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

  L'hash SHA-1 del certificato di firma utilizzato per firmare l'APK Android.

  Esempio:

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

**Identificatori delle applicazioni Apple:**
+ `X-Apple-Bundle-Id `:

  Un identificatore univoco per le applicazioni Apple (iOS, macOS, ecc.), definito nelle app, in genere seguendo un `Info.plist` formato a dominio inverso.

  Esempio:

  `com.mydomain.appname`

## Le migliori pratiche relative alle chiavi API
<a name="api-keys-best-practices"></a>

Le chiavi API includono un *valore* di testo semplice che dà accesso a una o più risorse o APIs nel tuo Account AWS. Se qualcuno copia la tua chiave API, può accedere alle stesse risorse e APIs. Per ridurre al minimo il potenziale impatto, consulta le seguenti best practice:
+ **Limita la chiave API**

  Per evitare la situazione sopra descritta, è meglio limitare la chiave API. Quando crei la chiave, puoi specificare il dominio, l'app Android o l'app Apple in cui può essere utilizzata la chiave.
+ **Gestisci la durata delle chiavi API**

  Puoi creare chiavi API che funzionano a tempo indeterminato. *Tuttavia, se desideri creare una chiave API temporanea, ruotare le chiavi API regolarmente o revocare una chiave API esistente, puoi utilizzare la scadenza della chiave API.*
  + Puoi impostare l'ora di scadenza di una chiave API quando la crei o la aggiorni.
  + Quando una chiave API raggiunge la data di scadenza, la chiave viene disattivata automaticamente. Le chiavi inattive non possono più essere utilizzate per effettuare richieste.
  + È possibile modificare una chiave temporanea in una chiave permanente rimuovendo la data di scadenza.
  + Puoi eliminare una chiave API 90 giorni dopo averla disattivata.
  + Se tenti di disattivare una chiave API che è stata utilizzata negli ultimi sette giorni, ti verrà richiesto di confermare che desideri apportare la modifica. 

    Se utilizzi l'API Amazon Location Service o AWS CLI, imposta il `ForceUpdate` parametro su`true`, altrimenti riceverai un errore.