Příručka pro vývojáře v sadě JAVAScript/TypeScript REST SDK (Preview)
Sada Azure Maps JavaScript/TypeScript REST SDK (JavaScript SDK) podporuje vyhledávání pomocí služby Azure Maps 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 polohou, které zahrnují výkon Azure Maps.
Poznámka:
Sada Azure Maps JavaScript SDK podporuje verzi LTS Node.js. Další informace najdete v Node.js pracovní skupině vydaných verzí.
Požadavky
- Účet Azure Maps.
- Klíč předplatného nebo jiná forma ověřování pomocí Azure Maps.
- Node.js.
Tip
Účet Azure Maps 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žít sadu JavaScript SDK služby Azure Maps, musíte nainstalovat vyhledávací balíček. Každá ze služeb Azure Maps, 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
Vytvoření a ověření MapsSearchClient
Při vytváření objektu použitého MapsSearchClient pro přístup k rozhraním API služby Azure Maps 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 Maps.
Tip
Jedná seMapsSearchClient o primární rozhraní pro vývojáře, kteří používají knihovnu Azure Maps Search. Další informace o dostupných metodách hledání najdete v klientské knihovně Služby Azure Maps 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 ke službě Azure Maps 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
Můžete se ověřit pomocí klíče předplatného Azure Maps. Klíč předplatného najdete v části Ověřování v účtu Azure Maps, 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é ověřit ověřování pro aplikaci v rozhraní REST API služby Azure Maps.
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 Maps a vytvořte spravovanou identitu pro svůj účet Azure Maps. 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 Maps Search k vytvoření objektu client s vašimi přihlašovacími údaji Azure. Můžete použít klíč předplatného Azure Maps 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í
Služba Azure Maps 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);
})