Uso de claves de la API para autenticación
Las claves de la API solo están disponibles para su uso con los recursos de mapa, lugares y rutas, y no se pueden modificar ni crear esos recursos. Si su aplicación necesita acceso a otros recursos o acciones para los usuarios no autenticados, puede usar Amazon Cognito para proporcionar acceso junto con las claves de API o en lugar de ellas. Para obtener más información, consulte Uso de Amazon Cognito para la autenticación.
Las claves de la API son un valor de clave que se asocia a recursos específicos de Amazon Location Service o API en la Cuenta de AWS y las acciones específicas que puede realizar en esos recursos. Puede usar una clave de API en su aplicación para realizar llamadas no autenticadas a las API de Amazon Location para esos recursos.
Por ejemplo, si asocia una clave de API a un recurso o a la API de GetPlace*, la aplicación que utilice esa clave de API podrá llamar a API específicas. Esa misma clave de API no otorgaría permisos para cambiar o actualizar ningún recurso o llamar a las API a las que no esté asociada.
Cuando llama a las API de Amazon Location Service en sus aplicaciones, normalmente realiza esta llamada como un usuario autenticado que está autorizado a realizar las llamadas a las API. No obstante, hay algunos casos en los que no desea autenticar a todos los usuarios de la aplicación.
Por ejemplo, es posible que desee que cualquier persona que utilice el sitio web tenga acceso a una aplicación web que muestre la ubicación de su empresa, tanto si ha iniciado sesión como si no. En este caso, una alternativa es utilizar las claves de la API para realizar las llamadas a la API.
Consulte Prácticas recomendadas de clave de la API para obtener información adicional acerca de cuándo utilizar claves de la API.
Para obtener más información acerca de cómo trabajar con claves mediante la API de Amazon Location Service, consulte los siguientes temas en la Referencia de la API de Amazon Location Service:
Creación de una clave de API para Amazon Location Service
Puede crear una clave de API mediante la consola de Amazon Location Service, la AWS CLI o la API de Amazon Location. Continúe con los procedimientos correspondientes que se indican a continuación.
- Amazon Location console
-
Para crear una clave de API mediante la consola de Amazon Location Service
-
En la consola de Amazon Location, seleccione las claves de API en el menú de la izquierda.
-
En la página Claves de API, elija Crear clave de API.
-
En la página Crear clave de API, rellene la siguiente información:
-
Nombre: un nombre para su clave de API, por ejemplo ExampleKey.
-
Descripción: una descripción opcional para su clave de API.
-
Recursos: en el menú desplegable, elija los recursos de Amazon Location para conceder acceso con esta clave de API. Puede agregar más de un recurso seleccionando agregar recurso.
-
Acciones: especifique las acciones que desea autorizar con esta clave de API. Debe seleccionar al menos una acción para que coincida con cada tipo de recurso que haya seleccionado. Por ejemplo, si ha seleccionado un recurso de ubicación, debe seleccionar al menos una de las opciones de la sección Acciones de ubicación.
-
Hora de caducidad: si lo desea, añada una fecha y una hora de caducidad para su clave de API. Para obtener más información, consulte Prácticas recomendadas de clave de la API.
-
Restricciones de los clientes: si lo desea, agregue uno o más dominios web o una o más aplicaciones de Android o Apple en las que pueda usar la clave de la API. Por ejemplo, si la clave de la API es para permitir que una aplicación se ejecute en el sitio web example.com, puede poner *.example.com/ como referente permitido.
-
Etiquetas: si lo desea, añada etiquetas a la clave de API.
-
Seleccione Crear clave de API para crear la clave de API.
-
En la página de detalles de la clave de API, puede ver información sobre la clave de API que ha creado. Seleccione Mostrar clave de API para ver el valor de clave que utiliza al llamar a las API de Amazon Location. El valor de la clave tendrá el formato v1.public.a1b2c3d4....
- AWS CLI
-
-
Utilice el comando create-key. En el siguiente ejemplo, se crea una clave de API llamada ExampleKey sin fecha de caducidad y con acceso a un ú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
-
La respuesta incluye el valor de la clave de API que se debe utilizar al acceder a los recursos de las aplicaciones. El valor de la clave tendrá el formato v1.public.a1b2c3d4.... Para obtener más información acerca del uso de la clave de API de para renderizar mapas, consulte Uso de una clave de API para llamar a una API de Amazon Location. La respuesta a create-key tiene este aspecto:
{
"Key": "v1.public.a1b2c3d4...",
"KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
"KeyName": "ExampleKey",
"CreateTime": "2023-02-06T22:33:15.693Z"
}
-
También puede utilizar la describe-key para buscar el valor de la clave más tarde. En el ejemplo siguiente, se muestra cómo llamar a describe-key en una clave de API llamada ExampleKey.
aws location describe-key \
--key-name ExampleKey
- Amazon Location API
-
Use la operación CreateKey de las API de Amazon Location. El siguiente ejemplo es una solicitud de API para crear una clave de API llamada ExampleKey sin fecha de caducidad y con acceso a un ú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"
]
}
}
La respuesta incluye el valor de la clave de API que se debe utilizar al acceder a los recursos de las aplicaciones. El valor de la clave tendrá el formato v1.public.a1b2c3d4....
También puede usar la API de DescribeKey para buscar el valor de una clave más tarde.
Uso de una clave de API para llamar a una API de Amazon Location
Tras crear una clave de API, puede usar el valor de la clave para realizar llamadas a las API de Amazon Location de su aplicación.
- API
-
Las API que admiten las claves de API tienen un parámetro adicional que toma el valor de la clave de API. Por ejemplo, si llama a la API GetPlace, puede rellenar el parámetro clave de la siguiente manera
curl --request GET —url 'https://places.geo.eu-central-1.amazonaws.com/v2/place/{PLACEID}?key={APIKEY}&language=jp'
- AWS CLI
-
Cuando utilice el parámetro --key, también debería usar el parámetro --no-sign-request para evitar firmar con Sig v4.
aws geo-places get-place --place-id $PLACEID --language jp --key $APIKEY
- SDK (web)
-
Utilice el siguiente 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)
-
Utilice el siguiente 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)
-
Utilice el siguiente 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()
}
}
Restricción del uso de las claves de API por origen de la solicitud
Puede configurar las claves de API con restricciones de cliente que limiten el acceso a dominios o aplicaciones móviles específicos. Al restringir por dominio, las solicitudes solo se autorizarán si el encabezado de referencia HTTP coincide con el valor que proporcione. Cuando se restrinjan por aplicación de Android o Apple, las solicitudes solo se autorizarán si los campos del encabezado HTTP del identificador de la aplicación coinciden con los valores que proporcione.
Para obtener más información, consulte ApiKeyRestrictions en la Referencia de la API de Amazon Location Service.
Identificadores de aplicaciones de Android:
-
X-Android-Package:
Un identificador único para las aplicaciones de Android, definido en el archivo build.gradle de la aplicación, que suele seguir un formato de dominio inverso.
Ejemplo:
com.mydomain.appname
-
X-Android-Cert:
El hash SHA-1 del certificado de firma utilizado para firmar el APK de Android.
Ejemplo:
BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
Identificadores de aplicaciones de Apple:
-
X-Apple-Bundle-Id :
Un identificador único para las aplicaciones de Apple (iOS, macOS, etc.), definido en el Info.plist de la aplicación, que suele seguir un formato de dominio inverso.
Ejemplo:
com.mydomain.appname
Prácticas recomendadas de clave de la API
Las claves de la API incluyen un valor de texto sin formato que da acceso a uno o más recursos o API en la Cuenta de AWS. Si alguien copia su clave de la API, podrá acceder a esos mismos recursos y API. Para minimizar el impacto potencial, revise las siguientes prácticas recomendadas:
-
Limitación de la clave de la API
Para evitar la situación anterior, es mejor limitar la clave de la API. Cuando crea la clave, puede especificar el dominio, la aplicación de Android o Apple en la que se puede usar la clave.
-
Administración de la vida útil de claves de API
Puede crear claves de API que funcionen indefinidamente. Sin embargo, si quiere crear una clave de API temporal, rotar las claves de API de forma regular o revocar una clave de API existente, puede utilizar la caducidad de la clave de API.
-
Puede establecer el tiempo de caducidad de una clave de API cuando la crea o actualiza.
-
La clave de API se desactiva automáticamente cuando alcanza su hora de vencimiento. Las claves inactivas ya no se pueden usar para realizar solicitudes.
-
Puede cambiar una clave temporal por una clave permanente quitando el tiempo de caducidad.
-
Puede eliminar una clave de API 90 días después de desactivarla.
-
Si intenta desactivar una clave de API que se haya utilizado en los últimos siete días, se le pedirá que confirme que desea realizar el cambio.
Si utiliza la API de Amazon Location Service o la AWS CLI, establezca el parámetro ForceUpdate en true, de lo contrario recibirá un error.
