As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Usar chaves de API para se autenticar
<a name="using-apikeys"></a>

**nota**  
As chaves de API estão disponíveis para uso somente com recursos de **mapa**, **lugar** e **rota** e você não pode modificar nem criar esses recursos. Se seu aplicativo precisar acessar outros recursos ou ações para usuários não autenticados, você poderá usar o Amazon Cognito para fornecer acesso junto com, ou em vez das, chaves de API. Para obter mais informações, consulte [Usar o Amazon Cognito para autenticação](authenticating-using-cognito.md).

As *chaves de API* são um valor-chave associado a recursos específicos do Amazon Location Service ou API em sua Conta da AWS API e a ações específicas que você pode realizar nesses recursos. Você pode usar uma chave de API em seu aplicativo para fazer chamadas não autenticadas para as APIs do Amazon Location para esses recursos. 

Por exemplo, se você associar uma chave de API and/or a um recurso, a `GetPlace*` API, um aplicativo que usa essa chave de API poderá chamar APIs específicas. Essa mesma chave de API não daria permissões para alterar ou atualizar nenhum recurso ou chamar APIs às quais não estivesse associada.

Quando você chama as APIs do Amazon Location Service em seus aplicativos, você normalmente faz essa chamada como um *usuário autenticado* que está autorizado a fazer as chamadas de API. Contudo, há alguns casos em que não é necessário autenticar todos os usuários da sua aplicação. 

Por exemplo, talvez você queira que um aplicativo da web que mostra a localização da sua empresa esteja disponível para qualquer pessoa que use o site, esteja ela conectada ou não. Nesse caso, uma alternativa é usar as chaves de API para fazer as chamadas de API.

Consulte [Melhores práticas para chaves de API](api-keys-best-practices.md) para obter informações adicionais sobre quando usar chaves de API.

Para obter mais informações sobre como trabalhar com chaves usando a API do Amazon Location Service, consulte os tópicos na *Referência da API do Amazon Location Service*:
+ [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_CreateKey.html)
+ [DeleteKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_DeleteKey.html)
+ [DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_DescribeKey.html)
+ [ListKeys](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_ListKeys.html)
+ [UpdateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_UpdateKey.html)

## Criar uma chave de API para o Amazon Location Service
<a name="create-api-key"></a>

Você pode criar uma chave de API por meio do console do Amazon Location Service ou da Amazon Location API. AWS CLI Continue com os procedimentos apropriados abaixo.

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

**Para criar uma chave de API usando o console Amazon Location Service**

1. No [https://console.aws.amazon.com/location](https://console.aws.amazon.com/location), selecione **chaves de API** no menu à esquerda.

1. Na página **Chaves de API**, selecione **Criar chave de API**.

1. Na página **Criar chave de API**, preencha as seguintes informações:
   + **Nome**: um nome para sua chave de API, do tipo `ExampleKey`.
   + **Descrição**: uma descrição opcional para a sua chave de API.
   + **Recursos**: no menu suspenso, escolha os recursos do Amazon Location aos quais conceder acesso com essa chave de API. Você pode adicionar mais de um recurso escolhendo **Adicionar recurso**.
   + **Ações**: especifique as ações que você deseja autorizar com essa chave de API. Você deve selecionar pelo menos uma ação para corresponder a cada tipo de recurso selecionado. Por exemplo, se você selecionou um recurso de local, deverá selecionar pelo menos uma das opções em **Ações de locais**.
   + **Prazo**: opcional, adicione uma data e um horário de expiração para sua chave de API. Para obter mais informações, consulte [Melhores práticas para chaves de API](api-keys-best-practices.md).
   + **Restrições de cliente**: opcionalmente, adicione um ou mais domínios da web ou um ou mais aplicações para Android ou Apple nos quais você pode usar a chave de API. Por exemplo, se a chave de API for para permitir que uma aplicação seja executada no site `example.com`, você poderá colocar `*.example.com/` como referenciador permitido.
   + **Tags**: opcional, adicione tags à chave de API.

1. Selecione **Criar chave de API** para criar a chave de API.

1. Na página de detalhes da chave de API, você pode ver informações sobre a chave de API que você criou. Selecione **Mostrar chave de API** para ver o valor da chave que você usa ao chamar as APIs do Amazon Location. O valor da chave terá o formato `v1.public.{{a1b2c3d4...}}`. 

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

1. Use o comando [create-key](https://docs.aws.amazon.com/cli/latest/reference/location/create-key.html). O exemplo a seguir cria uma chave de API chamada `ExampleKey` sem data de expiração e acesso a um único recurso de mapa.

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

1. A resposta inclui o valor da chave de API a ser usada ao acessar recursos em seus aplicativos. O valor da chave terá o formato `v1.public.a1b2c3d4...`. Para saber mais sobre como usar a chave de API para renderizar mapas, consulte [Utilizar uma chave de API para chamar uma API do Amazon Location](#using-apikeys-in-api). A resposta para create-key é semelhante à seguinte:

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

1. Você também pode usar a `describe-key` para encontrar o valor da chave posteriormente. O exemplo a seguir mostra como chamar `describe-key` em uma chave de API chamada `ExampleKey`.

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

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

Use a operação [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_CreateKey.html) das APIs do Amazon Location. O exemplo a seguir é uma solicitação de API para criar uma chave de API chamada `ExampleKey` sem data de expiração e acesso a um único recurso de mapa.

```
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"
    ]
  }
}
```

A resposta inclui o valor da chave de API a ser usada ao acessar recursos em seus aplicativos. O valor da chave terá o formato `v1.public.a1b2c3d4...`.

Você também pode usar a API [DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geoapikeys_DescribeKey.html) para encontrar o valor da chave posteriormente.

------

## Utilizar uma chave de API para chamar uma API do Amazon Location
<a name="using-apikeys-in-api"></a>

Depois de criar uma chave de API, você pode usar o valor da chave para fazer chamadas para as APIs do Amazon Location em seu aplicativo.

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

As APIs que oferecem suporte a chaves de API têm um parâmetro adicional que usa o valor da chave de API. Por exemplo, se você chamar a API `GetPlace`, você poderá preencher o parâmetro [chave](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html), da seguinte forma

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

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

Quando você usar o parâmetro `--key`, você também deve usar o parâmetro `--no-sign-request` para evitar assinar com o Sig v4.

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

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

Use o seguinte código:

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

Use o seguinte código:

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

Use o seguinte código:

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

------