Permitir o acesso de convidados não autenticados ao seu aplicativo usando chaves de API - Amazon Location Service
Chaves de API comparadas ao Amazon CognitoCria uma chave de API.Utilizar uma chave de API para chamar uma API do Amazon LocationUtilizar uma chave de API para renderizar um mapaGerenciar o tempo de vida útil das chaves de API

Permitir o acesso de convidados não autenticados ao seu aplicativo usando chaves de API

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.

As chaves de API são um valor de chave associado a recursos específicos do Amazon Location Service em seu 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 ao recurso de mapa MyMap e às ações GetMap*, um aplicativo que usa essa chave de API poderá visualizar mapas criados com esse recurso e sua conta será cobrada como qualquer outro uso da sua conta. Essa mesma chave de API não daria permissões para alterar ou atualizar o recurso de mapa: somente o uso do recurso é permitido.

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 ou 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 ter mais informações, consulte Permitir acesso de convidado não autenticado às aplicações usando o Amazon Cognito..

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. Para evitar isso, você pode especificar os domínios em que a chave de API pode ser usada ao criar a chave. Esses domínios são chamados referenciadores. Se necessário, você também pode criar chaves de API de curto prazo definindo prazos de expiração para suas chaves de API.

Chaves de API comparadas ao Amazon Cognito

As chaves de API e o Amazon Cognito são usados de forma semelhante em cenários semelhantes, então por que você usaria um em vez do outro? A tabela a seguir destaca algumas das principais diferenças entre os dois.

  • As chaves de API estão disponíveis somente para recursos de mapas, lugares e rotas, e somente para determinadas ações. O Amazon Cognito pode ser usado para autenticar o acesso à maioria das APIs do Amazon Location Service.

  • Geralmente, o desempenho das solicitações de mapas com chaves de API é mais rápido do que cenários semelhantes com o Amazon Cognito. Uma autenticação mais simples significa menos idas e vindas ao serviço e menos solicitações em cache para se obter o mesmo bloco de mapa novamente em um curto período de tempo.

  • Com o Amazon Cognito, você pode usar seu próprio processo de autenticação ou combinar vários métodos de autenticação usando as identidades federadas do Amazon Cognito. Para obter mais informações, consulte Conceitos básicos das identidades federadas no Guia do desenvolvedor do Amazon Cognito.

Cria uma chave de API.

Você pode criar uma chave de API e associá-la a um ou mais recursos em seu Conta da AWS.

Você pode criar uma chave de API usando o console do Amazon Location Service, o AWS CLI ou as APIs do Amazon Location.

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

  1. No console do Amazon Location, selecione chaves de API no menu à esquerda.

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

  3. Na página Criar chave de API, preencha as seguintes informações:

    • Nome: um nome para sua chave de API, do tipo MyWebAppKey.

    • Descrição: uma descrição opcional para a sua chave de API.

    • Recursos: escolha os recursos do Amazon Location aos quais conceder acesso com essa chave de API no menu suspenso. 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 ter mais informações, consulte Gerenciar o tempo de vida útil das chaves de API.

    • Referenciadores: opcional, adicione um ou mais domínios 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.

  4. Selecione Criar chave de API para criar a chave de API.

  5. 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.... Para obter mais informações sobre como usar a chave de API para renderizar mapas, consulte Utilizar uma chave de API para renderizar um mapa.

API

Para criar uma chave de API usando as APIs do Amazon Location

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"
   "Restrictions": { 
      "AllowActions": [
         "geo:GetMap*"
      ],
      "AllowResources": [
         "arn:aws:geo:region:map/mapname"
      ]
   },
   "NoExpiry": true
   }
}

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 renderizar um mapa.

Você também pode usar a API DescribeKey para encontrar o valor da chave posteriormente.

AWS CLI

Para criar uma chave de API usando comandos 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:GetMap*"],"AllowResources":["arn:aws:geo:region:map/mapname"]}' \
  --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 renderizar um mapa. 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

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.

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

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

Se você preencher esse valor, você não precisará autenticar a chamada da API com o AWS Sig v4, como faria normalmente.

Para desenvolvedores de JavaScript, você pode usar o Amazon Location Auxiliar de autenticação em JavaScript para ajudar na autenticação das operações de API com chaves de API.

Para desenvolvedores móveis, você pode usar os seguintes SDKs de autenticação móvel Amazon Location:

Para os usuários AWS CLI, ao usar o parâmetro --key, você também deve usar o parâmetro --no-sign-request, para evitar assinar com o Sig v4.

nota

Se você incluir uma assinatura key e uma assinatura Sig v4 da AWS em uma chamada para o Amazon Location Service, somente a chave de API será usada.

Utilizar uma chave de API para renderizar um mapa

Você pode usar o valor da chave de API para renderizar um mapa em seu aplicativo usando o MapLibre. Isso é um pouco diferente de usar as chaves de API em outras APIs do Amazon Location que você está chamando diretamente, porque o MapLibre faz essas chamadas para você.

O exemplo de código a seguir mostra o uso da chave de API para renderizar um mapa em uma página simples da Web usando o controle de mapas MapLibre GL JS. Para que esse código funcione corretamente, substitua as strings v1.public.your-api-key-value, us-east-1 e ExampleMap por valores que correspondam aos seus Conta da 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>

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.

Ao criar uma nova chave de API ou atualizar uma existente, você pode definir o tempo de expiração dessa chave de API.

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

  • Você pode excluir uma chave de API 90 dias após desativá-la.

  • Se você tiver uma chave inativa que ainda não tenha sido excluída, você poderá restaurá-la atualizando o prazo de expiração para um horário futuro.

  • Para criar uma chave permanente, você pode remover o tempo de expiração.

  • Se você tentar desativar uma chave de API que tenha sido usada nos últimos 7 dias, você será solicitado a confirmar que deseja fazer a alteração. Se você estiver usando a API do Amazon Location Service, ou a AWS CLI, você receberá uma mensagem de erro, a menos que defina o parâmetro ForceUpdate como verdadeiro.