Permita o acesso de convidados não autenticados ao seu aplicativo usando chaves API - Amazon Location Service
APIchaves comparadas ao Amazon CognitoCrie API chavesUse uma API chave para ligar para um local da Amazon APIUse uma API chave para renderizar um mapaGerencie a vida útil das API principais

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

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

Quando você liga para o Amazon Location Service APIs em seus aplicativos, você normalmente faz essa chamada como um usuário autenticado que está autorizado a fazer as API chamadas. 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 API as teclas para fazer as API chamadas.

APIchaves são um valor-chave associado a recursos específicos do Amazon Location Service em você Conta da AWS e a ações específicas que você pode realizar nesses recursos. Você pode usar uma API chave em seu aplicativo para fazer chamadas não autenticadas para o local da Amazon APIs para esses recursos. Por exemplo, se você associar uma API chave ao recurso myMapde mapa e GetMap* às ações, um aplicativo que usa essa API chave poderá visualizar mapas criados com esse recurso, e sua conta será cobrada como qualquer outro uso da sua conta. Essa mesma API chave não daria permissões para alterar ou atualizar o recurso do mapa—somente o uso do recurso é permitido.

nota

APIas chaves estão disponíveis para uso somente com recursos de mapa, local 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 de, chaves. API Para obter mais informações, consulte Permita que convidados não autenticados acessem seu aplicativo usando o Amazon Cognito.

APIas chaves incluem um valor de texto simples que dá acesso a um ou mais recursos em seu Conta da AWS. Se alguém copiar sua API chave, poderá acessar esses mesmos recursos. Para evitar isso, você pode especificar os domínios em que a API chave pode ser usada ao criar a chave. Esses domínios são chamados referenciadores. Se necessário, você também pode criar API chaves de curto prazo definindo prazos de expiração para suas API chaves.

APIchaves comparadas ao Amazon Cognito

APIas chaves 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.

  • APIas chaves estão disponíveis somente para recursos de mapa, local e rota, e somente para determinadas ações. O Amazon Cognito pode ser usado para autenticar o acesso à maioria dos Amazon Location Service. APIs

  • O desempenho das solicitações de mapas com API chaves geralmente é 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.

Crie API chaves

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

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

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

  1. No console de localização da Amazon, escolha APIas chaves no menu à esquerda.

  2. Na página de APIchaves, escolha Criar API chave.

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

    • Nome — Um nome para sua API chave, comoMyWebAppKey.

    • Descrição — Uma descrição opcional para sua API chave.

    • Recursos — Escolha os recursos de localização da Amazon aos quais conceder acesso com essa API chave 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 API chave. 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.

    • Tempo de expiração — opcionalmente, adicione uma data e hora de expiração para sua API chave. Para obter mais informações, consulte Gerencie a vida útil das API principais.

    • Referenciadores — opcionalmente, adicione um ou mais domínios nos quais você possa usar a chave. API Por exemplo, se a API chave for permitir que um aplicativo seja executado no siteexample.com, você poderá colocá-lo *.example.com/ como referenciador permitido.

    • Tags — Opcionalmente, adicione tags à API chave.

  4. Escolha Criar API chave para criar a API chave.

  5. Na página de detalhes da API chave, você pode ver informações sobre a API chave que você criou. Escolha Mostrar API chave para ver o valor da chave que você usa ao ligar para a Amazon LocationAPIs. O valor da chave terá o formato v1.public.a1b2c3d4.... Para obter mais informações sobre como usar a API chave para renderizar mapas, consulteUse uma API chave para renderizar um mapa.

API

Para criar uma API chave usando a localização da Amazon APIs

Use a CreateKey operação da Amazon LocationAPIs.

O exemplo a seguir é uma API solicitação para criar uma API chave chamada ExampleKey sem data de validade 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 API valor-chave a ser usado ao acessar recursos em seus aplicativos. O valor da chave terá o formato v1.public.a1b2c3d4.... Para saber mais sobre como usar a API chave para renderizar mapas, consulteUse uma API chave para renderizar um mapa.

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

AWS CLI

Para criar uma API chave usando AWS CLI comandos

Use o comando create-key.

O exemplo a seguir cria uma API chave chamada ExampleKey sem data de validade 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 API valor-chave a ser usado ao acessar recursos em seus aplicativos. O valor da chave terá o formato v1.public.a1b2c3d4.... Para saber mais sobre como usar a API chave para renderizar mapas, consulteUse uma API chave 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 uma API chave chamada ExampleKey.

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

Use uma API chave para ligar para um local da Amazon API

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

As API chaves APIs que suportam têm um parâmetro adicional que assume o valor da API chave. Por exemplo, se você chamar o GetPlaceAPI, poderá preencher o parâmetro chave, da seguinte forma

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

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

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

Para desenvolvedores móveis, você pode usar a seguinte autenticação móvel de localização da AmazonSDKs:

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

nota

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

Use uma API chave para renderizar um mapa

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

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

Gerencie a vida útil das API principais

Você pode criar API chaves que funcionem indefinidamente. No entanto, se você quiser criar uma API chave temporária, alternar API as chaves regularmente ou revogar uma API chave existente, você pode usar a expiração da APIchave.

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

  • Quando uma API chave atinge seu prazo de validade, ela é automaticamente desativada. As chaves inativas não podem mais ser usadas para fazer solicitações de mapas.

  • Você pode excluir uma API chave 90 dias depois de 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 API chave que foi usada nos últimos 7 dias, você será solicitado a confirmar que deseja fazer a alteração. Se você estiver usando o Amazon Location ServiceAPI, ou o AWS CLI, você receberá um erro, a menos que defina o ForceUpdate parâmetro como verdadeiro.