Руководство разработчиков ПАКЕТА REST SDK для JavaScript и TypeScript (предварительная версия)

2025-04-11

Пакет REST SDK для JavaScript/TypeScript Azure Maps (пакет SDK JavaScript) поддерживает поиск с использованием службы Azure Maps, например, поиск адреса, поиск границ города или страны, а также поиск по координатам. Эта статья поможет вам приступить к созданию приложений, поддерживающих расположение, которые включают возможности Azure Maps.

Примечание.

Пакет SDK JavaScript для Azure Maps поддерживает версию LTS Node.js. Дополнительные сведения см. в Рабочей группе по выпуску Node.js.

Требования

Azure Maps учетная запись.
Ключ подписки или другая форма проверки подлинности с помощью Azure Maps.
Node.js.

Совет

Вы можете создать учетную запись Azure Maps программным способом. Ниже приведен пример с помощью Azure CLI:

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

Создание проекта Node.js

В следующем примере создается новый каталог, а затем программа Node.js с именем mapsDemo с помощью npm:

mkdir mapsDemo
cd mapsDemo
npm init

Установка пакета поиска

Чтобы использовать пакет SDK JavaScript для Azure Maps, необходимо установить пакет поиска. Каждая из служб Azure Maps, включая поиск, маршрутизацию, отрисовку и географическое расположение, находятся в собственном пакете.

npm install @azure-rest/maps-search

После установки пакета создайте search.js файл в каталоге mapsDemo :

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

Службы Azure Maps

Имя службы	Пакеты npm	Образцы
Найти	@azure-rest/maps-search	Примеры поиска
Маршрут	@azure-rest/maps-route	Примеры маршрутов
Render	@azure-rest/maps-render	Пример отрисовки
Геопозиционирование	@azure-rest/maps-geolocation	Пример географического расположения

Создание и проверка подлинности MapsSearchClient

Вам нужен объект credential для аутентификации при создании объекта MapsSearchClient, используемого для доступа к API поиска Azure Maps. Для проверки подлинности можно использовать учетные данные Microsoft Entra или ключ подписки Azure. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Maps".

Совет

ЭтоMapsSearchClient основной интерфейс для разработчиков при использовании библиотеки поиска Azure Maps. Смотрите библиотеку клиента Azure Maps Search, чтобы узнать больше о доступных методах поиска.

Использование учетных данных Microsoft Entra

Вы можете пройти проверку подлинности с помощью Microsoft Entra ID, используя библиотеку Azure Identity. Чтобы использовать поставщик DefaultAzureCredential , необходимо установить @azure/identity пакет:

npm install @azure/identity

Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Maps, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от Azure. Возвращаются идентификатор приложения (клиента), идентификатор каталога (клиента) и секрет клиента. Скопируйте эти значения и сохраните их в безопасном месте. Вам они понадобятся на следующих этапах.

Задайте значения идентификатора приложения (клиента), идентификатора каталога (арендатора), секрет клиента для вашего приложения Microsoft Entra, а также идентификатора клиента ресурса карты в качестве переменных среды:

Переменная среды	Описание
AZURE_CLIENT_ID	Идентификатор приложения (клиента) в зарегистрированном приложении
AZURE_CLIENT_SECRET (секретный ключ клиента Azure)	Значение секрета клиента в зарегистрированном приложении
AZURE_TENANT_ID	Идентификатор каталога (арендатора) в зарегистрированном приложении
MAPS_CLIENT_ID	Идентификатор клиента в учетной записи Azure Map

Для этих переменных можно использовать .env файл. Необходимо установить пакет dotenv :

npm install dotenv

Затем добавьте .env файл в каталог mapsDemo и укажите следующие свойства:

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

После создания переменных среды вы можете получить к ним доступ в коде 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);

Использование подписочного ключа

Вы можете пройти проверку подлинности с помощью ключа подписки Azure Maps. Ключ подписки можно найти в разделе "Проверка подлинности" в учетной записи Azure Maps, как показано на следующем снимке экрана:

Необходимо передать ключ подписки AzureKeyCredential в класс, предоставленный пакетом проверки подлинности Azure Core . По соображениям безопасности лучше указать ключ в качестве переменной среды, чем включить ее в исходный код.

Используйте файл .env для хранения переменной ключа подписки. Чтобы получить значение, необходимо установить пакет dotenv :

npm install dotenv

Затем добавьте .env файл в каталог mapsDemo и укажите свойство:

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

После создания переменной среды вы можете получить доступ к ней в коде 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);

Использование учетного токена доступа (SAS)

Подписанный маркер доступа (SAS) — это токены аутентификации, созданные в формате JSON Web token (JWT) и криптографически подписанные для подтверждения подлинности приложения для REST API Azure Maps.

Маркер SAS можно получить с помощью AzureMapsManagementClient.accounts.listSas пакета. Сначала следуйте разделу "Создание и проверка подлинности AzureMapsManagementClient " для установки.

Во-вторых, следуйте процедуре создания управляемых идентичностей для Azure Maps, чтобы создать управляемую идентичность для вашей учетной записи Azure Maps. Скопируйте основной идентификатор (идентификатор объекта) управляемого удостоверения.

Затем установите пакет аутентификации Azure Core для использования AzureSASCredential:

npm install @azure/core-auth

Наконец, можно использовать маркер 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);

геокодирование

В следующем фрагменте кода показано, как в простом консольном приложении импортировать @azure-rest/maps-search пакет и получить координаты адреса с помощью запроса 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);
});

В этом фрагменте кода показано, как использовать MapsSearch метод из клиентской библиотеки поиска Azure Maps для создания client объекта с учетными данными Azure. Вы можете использовать ключ подписки Azure Maps или учетные данные Microsoft Entra. Параметр path указывает конечную точку API, которая в данном случае — "/geocode". Метод get отправляет HTTP-запрос GET с параметрами запроса. Запрос определяет координаты "1301 Аласкан Вей, Сиэтл, WA 98101, США". Пакет SDK возвращает результаты в виде объекта GeocodingResponseOutput и записывает их в консоль. Результаты упорядочены по оценке достоверности в этом примере, и на экране отображается только первый результат. Дополнительные сведения см. в разделе GetGeocoding.

Запустите search.js с помощью Node.js:

node search.js

Пакетное обратное геокодирование

Поиск Azure Maps также предоставляет некоторые методы пакетного запроса. В следующем примере показано, как вызвать метод пакетного обратного поиска:

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

В этом примере три координаты включаются в batchItems текст запроса. Первый элемент недопустим, см. в разделе "Обработка неудачных запросов ", в котором показано, как обрабатывать недопустимый элемент.

Получив ответ, вы можете его записать:

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

Обработка неудачных запросов

Обрабатывайте неудачные запросы путем проверки свойства error в пакетном элементе ответа. См. функцию logResponseBody в следующем примере завершенного пакетного обратного поиска.

Пример завершенного пакетного обратного поиска

Полный код для примера пакетного поиска реверсного адреса:

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

Использование пакета SDK версии 1

При необходимости мы работаем над тем, чтобы сделать все функции версии 1 доступными в версии 2. При необходимости установите следующие пакеты SDK версии 1:

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

Затем можно импортировать два пакета:

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

В следующем примере показано, как создать функцию, которая принимает адрес и выполняет поиск точек интереса (POI) вокруг него. Используйте набор SDK версии 2, чтобы получить координаты адреса через геокодирование, и набор SDK версии 1 для поиска точек интереса рядом с ним через поиск.

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

Дополнительная информация:

Клиентская библиотека поиска Azure Maps для JavaScript или TypeScript.