Usar chaves de API para se autenticar
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.
As chaves de API são um valor de chave associado a recursos específicos do Amazon Location Service em sua Conta da AWS 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 a um recurso e/ou à API GetPlace*, 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 do seu aplicativo.
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 Práticas recomendadas da chave de API 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:
Criar uma chave de API para o Amazon Location Service
Você pode criar uma chave de API usando o console do Amazon Location Service, a AWS CLI ou a API do Amazon Location. Continue com os procedimentos apropriados abaixo.
- Amazon Location console
-
Para criar uma chave de API usando o console Amazon Location Service
-
No console do Amazon Location, selecione chaves de API no menu à esquerda.
-
Na página Chaves de API, selecione Criar chave de API.
-
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 Práticas recomendadas da chave de API.
-
Restrições de cliente – Opcionalmente, adicione um ou mais domínios da web ou um ou mais aplicativos para Android ou Apple nos quais você pode usar a chave de API. Por exemplo, se a chave de API for para permitir que um aplicativo seja executado no site example.com, você poderá colocar *.example.com/ como referenciador permitido.
-
Tags: opcional, adicione tags à chave de API.
-
Selecione Criar chave de API para criar a chave de API.
-
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
-
-
Use o comando create-key. 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
-
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. 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"
}
-
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 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 para encontrar o valor da chave posteriormente.
Utilizar uma chave de API para chamar uma API do Amazon Location
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, 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@4.x/dist/maplibre-gl.css' />
<script src='https://unpkg.com/maplibre-gl@4.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()
}
}
Restringir o uso da chave de API por origem da solicitação
Você pode configurar chaves de API com restrições de cliente que limitam o acesso a domínios ou aplicativos móveis específicos. Quando se restringir por domínio, as solicitações serão autorizadas somente se o cabeçalho do indicador HTTP corresponder ao valor fornecido. Quando se restringir por aplicativo Android ou Apple, as solicitações serão autorizadas somente se os campos do cabeçalho do indicador HTTP do aplicativo corresponderem aos valores fornecidos por você.
Para obter mais informações, consulte ApiKeyRestrictions na Referência de API do Amazon Location Service.
Identificadores de aplicativos Android:
-
X-Android-Package:
Um identificador exclusivo para aplicativos Android, definido no arquivo build.gradle do aplicativo, geralmente seguindo um formato de domínio inverso.
Exemplo:
com.mydomain.appname
-
X-Android-Cert:
O hash SHA-1 do certificado de assinatura usado para assinar o APK do Android.
Exemplo:
BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
Identificadores de aplicativos da Apple:
-
X-Apple-Bundle-Id :
Um identificador exclusivo para aplicativos Apple (iOS, macOS, etc.), definido no arquivo Info.plist do aplicativo, geralmente seguindo um formato de domínio reverso.
Exemplo:
com.mydomain.appname
Práticas recomendadas da chave de API
As chaves de API incluem um valor de texto não criptografado que dá acesso a um ou mais recursos em seu Conta da AWS. Se alguém copiar sua chave de API, poderá acessar esses mesmos recursos e APIs. Para minimizar o impacto potencial, analise as seguintes práticas recomendadas:
-
Limitar a chave da API
Para evitar a situação acima, é melhor limitar sua chave de API. Quando criar a chave, você pode especificar o domínio, o aplicativo Android ou Apple em que a chave de API pode ser usada.
-
Gerenciar o tempo de vida útil das chaves de API
Você pode criar chaves de API que funcionem indefinidamente. No entanto, se você quiser criar uma chave de API temporária, fizer rodízio das chaves de API regularmente ou revogar uma chave de API existente, você pode usar a expiração da chave de API.
-
É possível configurar o prazo de validade de uma chave de API ao criá-la ou atualizá-la.
-
Ao atingir o tempo de expiração, a chave de API é desativada automaticamente. As chaves inativas não podem mais ser usadas para fazer solicitações.
-
Você pode alterar uma chave temporária para uma chave permanente removendo o prazo de expiração.
-
Você pode excluir uma chave de API 90 dias após desativá-la.
-
Se tentar desativar uma chave de API que tenha sido usada nos últimos 7 dias, você receberá uma solicitação para confirmar que deseja fazer a alteração.
Se estiver usando a API do Amazon Location Service, ou a AWS CLI, defina o parâmetro ForceUpdate como true; caso contrário, você receberá um erro.
