Guia de desenvolvedores do SDK REST JavaScript/TypeScript (visualização)

Artigo
02/07/2024

O SDK REST do Azure Maps JavaScript/TypeScript (SDK JavaScript) dá suporte à pesquisa usando o serviço Pesquisa do Azure Maps, como procurar um endereço, procurar o limite de uma cidade ou país e pesquisar por coordenadas. Este artigo ajuda-o a começar a criar aplicações com reconhecimento de localização que incorporam o poder do Azure Maps.

Nota

O SDK JavaScript do Azure Maps dá suporte à versão LTS do Node.js. Para obter mais informações, consulte Node.js Release Working Group.

Pré-requisitos

Conta do Azure Maps.
Chave de subscrição ou outra forma de Autenticação com o Azure Maps.
Node.js.

Gorjeta

Você pode criar uma conta do Azure Maps programaticamente, Aqui está um exemplo usando a CLI do Azure:

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Criar um projeto de Node.js

O exemplo a seguir cria um novo diretório e, em seguida, um programa Node.js chamado mapsDemo usando npm:

mkdir mapsDemo
cd mapsDemo
npm init

Instalar o pacote de pesquisa

Para usar o SDK JavaScript do Azure Maps, você precisa instalar o pacote de pesquisa. Cada um dos serviços do Azure Maps, incluindo pesquisa, roteamento, renderização e geolocalização, está cada um em seu próprio pacote.

npm install @azure-rest/maps-search

Depois que o pacote estiver instalado, crie um search.js arquivo no mapsDemo diretório:

mapsDemo
+-- package.json
+-- package-lock.json
+-- node_modules/
+-- search.js

Serviços do Azure Maps

Nome do serviço	Pacotes npm	Amostras
Procurar	@azure-rest/maps-search	Exemplos de pesquisa
Percurso	@azure-rest/mapas-rota	Amostras de rotas
Composição	@azure-rest/maps-render	Exemplo de renderização
Geolocalização	@azure-rest/mapas-geolocalização	Exemplo de geolocalização

Criar e autenticar um MapsSearchClient

Você precisa de um credential objeto para autenticação ao criar o MapsSearchClient objeto usado para acessar as APIs de pesquisa do Azure Maps. Você pode usar uma credencial do Microsoft Entra ou uma chave de assinatura do Azure para autenticar. Para obter mais informações sobre autenticação, consulte Autenticação com mapas do Azure.

Gorjeta

AMapsSearchClient é a interface principal para desenvolvedores que usam a biblioteca de pesquisa do Azure Maps. Consulte Biblioteca de cliente da Pesquisa do Azure Maps para saber mais sobre os métodos de pesquisa disponíveis.

Usando uma credencial do Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando a biblioteca de Identidade do Azure. Para usar o provedor DefaultAzureCredential, você precisa instalar o @azure/identity pacote:

npm install @azure/identity

Você precisa registrar o novo aplicativo Microsoft Entra e conceder acesso ao Azure Maps atribuindo a função necessária à sua entidade de serviço. Para obter mais informações, consulte Hospedar um daemon em recursos que não sejam do Azure. A ID do aplicativo (cliente), uma ID de diretório (locatário) e um segredo do cliente são retornados. Copie esses valores e armazene-os em um local seguro. Você precisa deles nas etapas a seguir.

Defina os valores da ID do aplicativo (cliente), da ID do diretório (locatário) e do segredo do cliente do seu aplicativo Microsoft Entra e da ID do cliente do recurso de mapa como variáveis de ambiente:

Variável de Ambiente	Description
AZURE_CLIENT_ID	ID do pedido (cliente) na sua candidatura registada
AZURE_CLIENT_SECRET	O valor do segredo do cliente na sua aplicação registada
AZURE_TENANT_ID	ID do diretório (locatário) em seu aplicativo registrado
MAPS_CLIENT_ID	A ID do cliente na sua conta do Azure Map

Você pode usar um .env arquivo para essas variáveis. Você precisa instalar o pacote dotenv :

npm install dotenv

Em seguida, adicione um .env arquivo no diretório mapsDemo e especifique estas propriedades:

AZURE_CLIENT_ID="<client-id>"
AZURE_CLIENT_SECRET="<client-secret>"
AZURE_TENANT_ID="<tenant-id>"
MAPS_CLIENT_ID="<maps-client-id>"

Depois que as variáveis de ambiente forem criadas, você poderá acessá-las em seu código JavaScript:

const MapsSearch = require("@azure-rest/maps-search").default; 
const { DefaultAzureCredential } = require("@azure/identity"); 
require("dotenv").config(); 
 
const credential = new DefaultAzureCredential(); 
const client = MapsSearch(credential, process.env.MAPS_CLIENT_ID);

Usando uma credencial de chave de assinatura

Pode autenticar-se com a sua chave de subscrição do Azure Maps. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Maps, conforme mostrado na captura de tela a seguir:

Você precisa passar a chave de assinatura para a AzureKeyCredential classe fornecida pelo Pacote de Autenticação Principal do Azure. Por motivos de segurança, é melhor especificar a chave como uma variável de ambiente do que incluí-la no código-fonte.

Use um .env arquivo para armazenar a variável de chave de assinatura para fazer isso. Você precisa instalar o pacote dotenv para recuperar o valor:

npm install dotenv

Em seguida, adicione um .env arquivo no diretório mapsDemo e especifique a propriedade:

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

Depois que a variável de ambiente for criada, você poderá acessá-la em seu código JavaScript:

const MapsSearch = require("@azure-rest/maps-search").default;
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

const credential = new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY);
const client = MapsSearch(credential);

Usando uma credencial de token de assinatura de acesso compartilhado (SAS)

Os tokens de assinatura de acesso compartilhado (SAS) são tokens de autenticação criados usando o formato de token Web JSON (JWT) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Maps.

Você pode obter o token SAS usando AzureMapsManagementClient.accounts.listSas o pacote. Siga a seção Criar e autenticar um AzureMapsManagementClient para configurar primeiro.

Em segundo lugar, siga Identidades gerenciadas para o Azure Maps para criar uma identidade gerenciada para sua conta do Azure Maps . Copie o ID principal (ID do objeto) da identidade gerenciada.

Em seguida, instale o pacote do Pacote de Autenticação Principal do Azure para usar AzureSASCredential:

npm install @azure/core-auth

Finalmente, você pode usar o token SAS para autenticar o cliente:

  const MapsSearch = require("@azure-rest/maps-search").default;
  const { AzureSASCredential } = require("@azure/core-auth");
  const { DefaultAzureCredential } = require("@azure/identity");
  const { AzureMapsManagementClient } = require("@azure/arm-maps");

  const subscriptionId = "<subscription ID of the map account>"
  const resourceGroupName = "<resource group name of the map account>";
  const accountName = "<name of the map account>";
  const mapsAccountSasParameters = {
    start: "<start time in ISO format>", // e.g. "2023-11-24T03:51:53.161Z"
    expiry: "<expiry time in ISO format>", // maximum value to start + 1 day
    maxRatePerSecond: 500,
    principalId: "<principle ID (object ID) of the managed identity>",
    signingKey: "primaryKey",
  };
  const credential = new DefaultAzureCredential();
  const managementClient = new AzureMapsManagementClient(credential, subscriptionId);
  const {accountSasToken} = await managementClient.accounts.listSas(
    resourceGroupName,
    accountName,
    mapsAccountSasParameters
  );
  if (accountSasToken === undefined) {
    throw new Error("No accountSasToken was found for the Maps Account.");
  }
  const sasCredential = new AzureSASCredential(accountSasToken);
  const client = MapsSearch(sasCredential);

Geocodificação

O trecho de código a seguir demonstra como, em um aplicativo de console simples, importar o @azure-rest/maps-search pacote e obter as coordenadas de um endereço usando a consulta GetGeocodesing :

const MapsSearch = require("@azure-rest/maps-search").default;
const { isUnexpected } = require("@azure-rest/maps-search");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

async function main() {
  const credential = new AzureKeyCredential(
    process.env. MAPS_SUBSCRIPTION_KEY
  );
  const client = MapsSearch(credential);

  const response = await client.path("/geocode", "json").get({
    queryParameters: {
      query: "1301 Alaskan Way, Seattle, WA 98101, US",
    },
  });
  if (isUnexpected(response)) {
    throw response.body.error;
  }
  const [ lon, lat ] = response.body.features[0].geometry.coordinates;
  console.log(`The coordinate is: (${lat}, ${lon})`);
}

main().catch((err) => {
  console.error(err);
});

Este trecho de código mostra como usar o MapsSearch método da biblioteca de cliente do Azure Maps Search para criar um client objeto com suas credenciais do Azure. Você pode usar sua chave de assinatura do Azure Maps ou a credencial do Microsoft Entra. O path parâmetro especifica o ponto de extremidade da API, que neste caso é "/geocode". O get método envia uma solicitação HTTP GET com os parâmetros de consulta. A consulta procura a coordenada de "1301 Alaskan Way, Seattle, WA 98101, US". O SDK retorna os resultados como um objeto GeocodingResponseOutput e os grava no console. Os resultados são ordenados por pontuação de confiança neste exemplo e apenas o primeiro resultado é exibido na tela. Para obter mais informações, consulte GetGeocoding.

Executar search.js com Node.js:

node search.js

Geocodificação reversa em lote

A Pesquisa do Azure Maps também fornece alguns métodos de consulta em lote. O exemplo a seguir demonstra como chamar o método de pesquisa reversa em lote:

  const batchItems = [
    // This is an invalid query
    { coordinates: [2.294911, 148.858561] },
    {
      coordinates: [-122.34255, 47.6101],
    },
    { coordinates: [-122.33817, 47.6155] },
  ];
  const response = await client.path("/reverseGeocode:batch").post({
    body: { batchItems },
  });

Neste exemplo, três coordenadas são incluídas no batchItems corpo da solicitação. O primeiro item é inválido, consulte Manipulando solicitações com falha para obter um exemplo mostrando como lidar com o item inválido.

Depois de receber a resposta, você pode registrá-la:

 
function logResponseBody(resBody) {
  const { summary, batchItems } = resBody;

  const { totalRequests, successfulRequests } = summary;
  console.log(`${successfulRequests} out of ${totalRequests} requests are successful.`);

  batchItems.forEach(({ response }, idx) => {
    if (response.error) {
      console.log(`Error in ${idx + 1} request: ${response.error.message}`);
    } else {
      console.log(`Results in ${idx + 1} request:`);
      response.features.forEach((feature) => {
        console.log(`  ${feature.properties.address.freeformAddress}`);
      });
    }
  });
}

Tratamento de pedidos falhados

Manipule solicitações com falha verificando a error propriedade no item do lote de resposta. Veja a função na pesquisa reversa logResponseBody de lote concluída a seguir ao exemplo.

Exemplo de pesquisa reversa em lote concluída

O código completo para o exemplo de pesquisa em lote de endereço reverso:

const MapsSearch = require("@azure-rest/maps-search").default,
  { isUnexpected } = require("@azure-rest/maps-search");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

async function main() {
  const credential = new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY);
  const client = MapsSearch(credential);

  const batchItems = [
    // This is an invalid query
    { coordinates: [2.294911, 148.858561] },
    {
      coordinates: [-122.34255, 47.6101],
    },
    { coordinates: [-122.33817, 47.6155] },
  ];

  const response = await client.path("/reverseGeocode:batch").post({
    body: { batchItems },
  });

  if (isUnexpected(response)) {
    throw response.body.error;
  }

  logResponseBody(resumeResponse.body);
}

function logResponseBody(resBody) {
  const { summary, batchItems } = resBody;

  const { totalRequests, successfulRequests } = summary;
  console.log(`${successfulRequests} out of ${totalRequests} requests are successful.`);

  batchItems.forEach(({ response }, idx) => {
    if (response.error) {
      console.log(`Error in ${idx + 1} request: ${response.error.message}`);
    } else {
      console.log(`Results in ${idx + 1} request:`);
      response.features.forEach((feature) => {
        console.log(`  ${feature.properties.address.freeformAddress}`);
      });
    }
  });
} 

main().catch(console.error);

Usar o SDK V1

Estamos trabalhando para disponibilizar todos os recursos V1 na V2, até lá, instale os seguintes pacotes V1 SDK, se necessário:

npm install @azure-rest/map-search-v1@npm:@azure-rest/map-search@^1.0.0
npm install @azure-rest/map-search-v2@npm:@azure-rest/map-search@^2.0.0

Em seguida, você pode importar os dois pacotes:

const MapsSearchV1 = require("@azure-rest/map-search-v1").default;
const MapsSearchV2 = require("@azure-rest/map-search-v2").default;

O exemplo a seguir demonstra a criação de uma função que aceita um endereço e pesquisa POIs em torno dele. Use o SDK V2 para obter as coordenadas do endereço(/geocode) e o SDK V1 para pesquisar POIs em torno dele(/search/nearby).

const MapsSearchV1 = require("@azure-rest/map-search-v1").default;
const MapsSearchV2 = require("@azure-rest/map-search-v2").default;
const { AzureKeyCredential } = require("@azure/core-auth");
const { isUnexpected: isUnexpectedV1 } = require("@azure-rest/maps-search-v1");
const { isUnexpected: isUnexpectedV2 } = require("@azure-rest/maps-search-v2");
require("dotenv").config();

/** Initialize the MapsSearchClient */
const clientV1 = MapsSearchV1(new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY));
const clientV2 = MapsSearchV2(new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY));

async function searchNearby(address) {
  /** Make a request to the geocoding API */
  const geocodeResponse = await clientV2
    .path("/geocode")
    .get({ queryParameters: { query: address } });
  /** Handle error response */
  if (isUnexpectedV2(geocodeResponse)) {
    throw geocodeResponse.body.error;
  }

  const [lon, lat] = geocodeResponse.body.features[0].geometry.coordinates;
  
  /** Make a request to the search nearby API */
  const nearByResponse = await clientV1.path("/search/nearby/{format}", "json").get({
    queryParameters: { lat, lon },
  });
  /** Handle error response */
  if (isUnexpectedV1(nearByResponse)) {
    throw nearByResponse.body.error;
  }
  /** Log response body */
  for(const results of nearByResponse.body.results) {
    console.log(
      `${result.poi ? result.poi.name + ":" : ""} ${result.address.freeformAddress}. (${
        result.position.lat
      }, ${result.position.lon})\n`
    );
  }
}

async function main(){
  searchNearBy("15127 NE 24th Street, Redmond, WA 98052");
}

main().catch((err) => {
    console.log(err);
})

Informações adicionais

A biblioteca de cliente do Azure Maps Search para JavaScript/TypeScript.