Permitir el acceso de invitados no autenticados a su aplicación mediante claves de API - Amazon Location Service
Claves de API comparadas con Amazon CognitoCrear claves de APIUsar una clave de API para llamar a una API de Amazon LocationUsar una clave de API para renderizar un mapaGestionar la vida útil de claves de API

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Permitir el acceso de invitados no autenticados a su aplicación mediante claves de API

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 su 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.

Las claves de API son un valor clave que se asocia a recursos específicos de Amazon Location Service y a acciones específicas que puedes realizar en esos recursos. Cuenta de AWSPuede 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 al recurso de mapa Mi mapa y a las acciones GetMap*, la aplicación que utilice esa clave de API podrá ver los mapas creados con ese recurso y se cobrará a su cuenta como cualquier otro uso de su cuenta. Esa misma clave de API no otorgaría permisos para cambiar o actualizar el recurso del mapa, solo se permite usar el recurso.

nota

Las claves de 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 Cómo permitir el acceso a sus aplicaciones como invitado no autenticado con Amazon Cognito.

Las claves de API incluyen un valor de texto simple que da acceso a uno o más recursos de su cuenta Cuenta de AWS. Si alguien copia su clave de API, podrá acceder a esos mismos recursos. Para evitarlo, puede especificar los dominios en los que se puede usar la clave de API al crear la clave. Estos dominios se denominan referentes. Si es necesario, también puede crear claves de API a corto plazo estableciendo los tiempos de caducidad de sus claves de API.

Claves de API comparadas con Amazon Cognito

Las claves de API y Amazon Cognito se utilizan de forma similar en situaciones similares, así que ¿por qué utilizaría una en lugar de la otra? En la siguiente lista, se enumeran algunas de las diferencias entre ambas.

  • Las claves de API solo están disponibles para los recursos de mapas, lugares y rutas, y solo para determinadas acciones. Amazon Cognito se puede utilizar para autenticar el acceso a la mayoría de las API de Amazon Location Service.

  • El rendimiento de las solicitudes de mapas con claves de API suele ser más rápido que en escenarios similares con Amazon Cognito. Una autenticación más sencilla significa menos viajes de ida y vuelta al servicio y solicitudes almacenadas en caché cuando se vuelve a obtener el mismo mosaico de mapa en un período de tiempo corto.

  • Con Amazon Cognito, puede utilizar su propio proceso de autenticación o combinar varios métodos de autenticación mediante Amazon Cognito Federated Identities. Para obtener más información, consulte Introducción a las identidades federadas en la Guía para desarrolladores de Amazon Cognito.

Crear claves de API

Puede crear una clave de API y asociarla a uno o más recursos de su Cuenta de AWS.

Puedes crear una clave de API mediante la consola de Amazon Location Service AWS CLI, las o las API de ubicación de Amazon.

Console
Para crear una clave de API mediante la consola de Amazon Location Service

  1. En la consola de Amazon Location, seleccione las claves de API en el menú de la izquierda.

  2. En la página Claves de API, elija Crear clave de API.

  3. En la página Crear clave de API, rellene la siguiente información:

    • Nombre: un nombre para su clave de API, por ejemplo MyWebAppKey.

    • Descripción: una descripción opcional para su clave de API.

    • Recursos: elija los recursos de Amazon Location a los que desea acceder con esta clave de API en el menú desplegable. 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 Gestionar la vida útil de claves de API.

    • Referentes: si lo desea, añada uno o más dominios en los que pueda usar la clave de API. Por ejemplo, si la clave de la API es para permitir que una aplicación se ejecute en el sitio webexample.com, puede poner *.example.com/ como referente permitido.

    • Etiquetas: si lo desea, añada etiquetas a la clave de API.

  4. Seleccione Crear clave de API para crear la clave de API.

  5. 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.... Para obtener más información sobre el uso de la clave de API para la representación de mapas, consulte Usar una clave de API para renderizar un mapa.

API

Para crear una clave de API mediante las API de Amazon Location

Use la operación de CreateKey de las API de Amazon Location.

El siguiente ejemplo es una solicitud de API para crear una clave de API llamada sin fecha de caducidad y ExampleKeycon acceso a un único recurso de mapa. 

POST /metadata/v0/keys HTTP/1.1
Content-type: application/json

{
   "KeyName": "ExampleKey"
   "Restrictions": { 
      "AllowActions": [
         "geo:GetMap*"
      ],
      "AllowResources": [
         "arn:aws:geo:region:map/mapname"
      ]
   },
   "NoExpiry": true
   }
}

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 Usar una clave de API para renderizar un mapa.

También puede usar la DescribeKey API para buscar el valor de una clave más tarde.

AWS CLI

Para crear una clave de API con los comandos de la AWS CLI

Utilice el comando create-key.

En el siguiente ejemplo, se crea una clave de API llamada sin fecha de caducidad y ExampleKeycon acceso a un único recurso de mapa. 

aws location \
  create-key \
  --key-name ExampleKey \
  --restrictions '{"AllowActions":["geo:GetMap*"],"AllowResources":["arn:aws:geo:region:map/mapname"]}' \
  --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 Usar una clave de API para renderizar un mapa. 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 siguiente ejemplo, se muestra cómo describe-key invocar una clave de API denominada ExampleKey.

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

Usar 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.

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 GetPlace API, puede rellenar el parámetro clave de la siguiente manera

GET /places/v0/indexes/IndexName/places/PlaceId?key=KeyValue

Si rellenas este valor, no necesitas autenticar la llamada a la API con AWS Sig v4 como lo harías normalmente.

Para JavaScript los desarrolladores, puedes usar Amazon Location como ayuda JavaScript Ayudante de autenticación para autenticar las operaciones de la API con las claves de la API.

Para los desarrolladores de dispositivos móviles, puedes usar los siguientes SDK de autenticación móvil de Amazon Location:

Para AWS CLI los usuarios, al usar el --key parámetro, también deben usarlo para evitar firmar con Sig v4. --no-sign-request

nota

Si incluyes una firma Sig v4 key y una firma AWS Sig v4 en una llamada a Amazon Location Service, solo se utilizará la clave de API.

Usar una clave de API para renderizar un mapa

Puedes usar el valor de la clave de la API para representar un mapa en tu aplicación utilizando MapLibre. Esto es un poco diferente al uso de las claves de API en otras API de Amazon Location a las que llamas directamente, ya MapLibre que hace esas llamadas por ti.

En el siguiente código de ejemplo, se muestra el uso de la clave de API para representar un mapa en una página web sencilla mediante el control de mapas MapLibre GL JS. Para que este código funcione correctamente, sustituya la v1.public. your-api-key-value, us-east-1 y ExampleMapcadenas con valores que coincidan con su. Cuenta de AWS

<!-- index.html -->
<html>
  <head>
    <link href="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body { margin: 0; }
      #map { height: 100vh; }
    </style>
  </head>
  <body>
    <!-- Map container -->
    <div id="map" />
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.js"></script>
    <script>
      const apiKey = "v1.public.your-api-key-value"; // API key
      const region = "us-east-1"; // Region
      const mapName = "ExampleMap"; // Map name
      // URL for style descriptor
      const styleUrl = `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=${apiKey}`;
      // Initialize the map
      const map = new maplibregl.Map({
        container: "map",
        style: styleUrl,
        center: [-123.1187, 49.2819],
        zoom: 11,
      });
      map.addControl(new maplibregl.NavigationControl(), "top-left");
    </script>
  </body>
</html>

Gestionar 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.

Al crear una nueva clave de API o actualizar una existente, puede establecer el tiempo de caducidad de esa clave de API.

  • 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 de mapas.

  • Puede eliminar una clave de API 90 días después de desactivarla.

  • Si tiene una clave inactiva que aún no ha eliminado, puede restaurarla actualizando la fecha de caducidad a una fecha futura.

  • Para crear una clave permanente, puede eliminar la fecha de caducidad.

  • Si intenta desactivar una clave de API que se haya utilizado en los últimos 7 días, se le pedirá que confirme que desea realizar el cambio. Si utilizas la API de Amazon Location Service, o la AWS CLI, recibirás un error, a menos que establezcas el ForceUpdate parámetro en true.