Příručka pro vývojáře v sadě JAVAScript/TypeScript REST SDK (Preview)

Článek
02/03/2024

Sada Azure Mapy JavaScript/TypeScript REST SDK (JavaScript SDK) podporuje vyhledávání pomocí azure Mapy Search, jako je hledání adresy, hledání hranic města nebo země a vyhledávání pomocí souřadnic. Tento článek vám pomůže začít vytvářet aplikace pracující s umístěním, které zahrnují výkon azure Mapy.

Poznámka:

Sada Azure Mapy JavaScript SDK podporuje verzi LTS Node.js. Další informace najdete v Node.js pracovní skupině vydaných verzí.

Požadavky

Účet Azure Mapy.
Klíč předplatného nebo jiná forma ověřování pomocí Azure Mapy
Node.js.

Tip

Účet Azure Mapy můžete vytvořit programově. Tady je příklad s využitím Azure CLI:

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

Vytvoření projektu Node.js

Následující příklad vytvoří nový adresář a pak Node.js program s názvem mapsDemo pomocí npm:

mkdir mapsDemo
cd mapsDemo
npm init

Instalace vyhledávacího balíčku

Pokud chcete používat sadu Azure Mapy JavaScript SDK, musíte nainstalovat vyhledávací balíček. Každá ze služeb Azure Mapy, včetně vyhledávání, směrování, vykreslování a geografické polohy, jsou každá z nich ve vlastním balíčku.

npm install @azure-rest/maps-search

Po instalaci balíčku vytvořte search.js v mapsDemo adresáři soubor:

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

Služby Azure Maps

Název služby	Balíčky npm	Vzorky
Search	@azure-rest/maps-search	ukázky hledání
Trasa	@azure-rest/maps-route	vzorky tras
Vykreslení	@azure-rest/maps-render	render sample
Geografická poloha	@azure-rest/maps-geolocation	Ukázka geografické polohy

Vytvoření a ověření Mapy SearchClient

Při vytváření objektu použitého MapsSearchClient pro přístup k rozhraním API služby Azure Mapy search potřebujete credential objekt pro ověřování. K ověření můžete použít přihlašovací údaje Microsoft Entra nebo klíč předplatného Azure. Další informace o ověřování najdete v tématu Ověřování pomocí Azure Mapy.

Tip

Jedná seMapsSearchClient o primární rozhraní pro vývojáře, kteří používají knihovnu Azure Mapy Search. Další informace o dostupných metodách hledání najdete v klientské knihovně azure Mapy Search.

Použití přihlašovacích údajů Microsoft Entra

Ověřování pomocí Microsoft Entra ID můžete provést pomocí knihovny identit Azure. Pokud chcete použít zprostředkovatele DefaultAzureCredential , musíte balíček nainstalovat @azure/identity :

npm install @azure/identity

Musíte zaregistrovat novou aplikaci Microsoft Entra a udělit přístup k Azure Mapy přiřazením požadované role k instančnímu objektu. Další informace najdete v tématu Hostování démona u prostředků mimo Azure. Vrátí se ID aplikace (klienta), ID adresáře (tenanta) a tajný klíč klienta. Zkopírujte tyto hodnoty a uložte je na bezpečném místě. Budete je potřebovat v následujících krocích.

Nastavte hodnoty ID aplikace (klienta), ID adresáře (tenanta) a tajného klíče klienta vaší aplikace Microsoft Entra a ID klienta prostředku mapy jako proměnné prostředí:

Proměnná prostředí	Popis
AZURE_CLIENT_ID	ID aplikace (klienta) ve vaší registrované aplikaci
AZURE_CLIENT_SECRET	Hodnota tajného klíče klienta v registrované aplikaci
AZURE_TENANT_ID	ID adresáře (tenanta) ve vaší registrované aplikaci
MAPS_CLIENT_ID	ID klienta ve vašem účtu Azure Map

Pro tyto proměnné můžete použít .env soubor. Musíte nainstalovat balíček dotenv :

npm install dotenv

Dále přidejte .env soubor do adresáře mapsDemo a zadejte tyto vlastnosti:

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

Po vytvoření proměnných prostředí k nim budete mít přístup v kódu JavaScriptu:

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);

Použití přihlašovacích údajů klíče předplatného

Pomocí klíče předplatného Azure Mapy můžete provést ověření. Klíč předplatného najdete v části Ověřování v účtu Azure Mapy, jak je znázorněno na následujícím snímku obrazovky:

Klíč předplatného AzureKeyCredential musíte předat třídě, kterou poskytuje balíček ověřování Azure Core. Z bezpečnostních důvodů je lepší zadat klíč jako proměnnou prostředí, než ho zahrnout do zdrojového kódu.

.env K tomu použijte soubor k uložení proměnné klíče předplatného. Abyste mohli načíst hodnotu, musíte nainstalovat balíček dotenv :

npm install dotenv

Dále přidejte .env soubor do adresáře mapsDemo a zadejte vlastnost:

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

Jakmile je proměnná prostředí vytvořená, můžete k ní přistupovat v kódu JavaScriptu:

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);

Použití přihlašovacích údajů tokenu sdíleného přístupového podpisu (SAS)

Tokeny sdíleného přístupového podpisu (SAS) jsou ověřovací tokeny vytvořené ve formátu JSON Web Token (JWT) a jsou kryptograficky podepsané, aby bylo možné prokázat ověřování pro aplikaci do rozhraní Azure Mapy REST API.

Token SAS můžete získat pomocí AzureMapsManagementClient.accounts.listSas balíčku. Nejprve postupujte podle části Vytvoření a ověření AzureMapsManagementClient nastavení.

Za druhé postupujte podle spravovaných identit pro Azure Mapy a vytvořte spravovanou identitu pro svůj účet Azure Mapy. Zkopírujte ID objektu zabezpečení spravované identity.

Dále nainstalujte balíček balíčku Azure Core Authentication Package , který se má použít AzureSASCredential:

npm install @azure/core-auth

Nakonec můžete k ověření klienta použít token SAS:

  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);

Geokódování

Následující fragment kódu ukazuje, jak v jednoduché konzolové aplikaci importovat @azure-rest/maps-search balíček a získat souřadnice adresy pomocí dotazu GetGeocoding :

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);
});

Tento fragment kódu ukazuje, jak použít metodu MapsSearch z klientské knihovny Azure Mapy Search k vytvoření objektu client s přihlašovacími údaji Azure. Můžete použít klíč předplatného Azure Mapy nebo přihlašovací údaje Microsoft Entra. Parametr path určuje koncový bod rozhraní API, který je v tomto případě "/geocode". Metoda get odešle požadavek HTTP GET s parametry dotazu. Dotaz vyhledá souřadnici "1301 Aljaškan Way, Seattle, WA 98101, US". Sada SDK vrátí výsledky jako objekt GeocodingResponseOutput a zapíše je do konzoly. Výsledky jsou seřazené podle skóre spolehlivosti v tomto příkladu a na obrazovce se zobrazí pouze první výsledek. Další informace naleznete v tématu GetGeocoding.

Spusťte search.js s Node.js:

node search.js

Dávkové zpětné geokódování

Azure Mapy Search také poskytuje některé metody dávkového dotazu. Následující příklad ukazuje, jak volat metodu dávkového zpětného vyhledávání:

  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 },
  });

V tomto příkladu jsou do batchItems textu požadavku zahrnuty tři souřadnice. První položka je neplatná. Příklad zpracování neplatných požadavků ukazuje, jak zpracovat neplatnou položku.

Jakmile dostanete odpověď, můžete ji protokolovat:

 
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}`);
      });
    }
  });
}

Zpracování neúspěšných požadavků

Zpracování neúspěšných požadavků kontrolou error vlastnosti v dávkové položce odpovědi Podívejte se na logResponseBody funkci v dokončeném dávkovém zpětném vyhledávání v následujícím příkladu.

Příklad dokončeného dávkového zpětného vyhledávání

Kompletní kód pro příklad dávkového vyhledávání reverzních adres:

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);

Použití sady SDK V1

Pracujeme na zpřístupnění všech funkcí V1 ve verzi 2, až do té doby nainstalujeme v případě potřeby následující balíčky sady SDK V1:

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

Potom můžete importovat dva balíčky:

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

Následující příklad ukazuje vytvoření funkce, která přijímá adresu a hledá poI kolem ní. Pomocí sady SDK V2 získáte souřadnice adresy (/geokódu) a sady SDK V1, abyste mohli prohledávat identifikátory POI(/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);
})

Další informace

Klientská knihovna Azure Mapy Search pro JavaScript/TypeScript.

Sdílet prostřednictvím