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

Статья
02/03/2024

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

Примечание.

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

Необходимые компоненты

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

Совет

Вы можете создать учетную запись Azure Карты программным способом. Ниже приведен пример с помощью 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 Карты, необходимо установить пакет поиска. Каждая из служб Azure Карты, включая поиск, маршрутизацию, отрисовку и геолокацию, находятся в собственном пакете.

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	Пример географического расположения

Создание и проверка подлинности Карты SearchClient

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

Совет

ЭтоMapsSearchClient основной интерфейс для разработчиков, использующих библиотеку поиска Карты Azure. Дополнительные сведения о доступных методах поиска см. в клиентской библиотеке поиска Azure Карты.

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

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

npm install @azure/identity

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

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

Переменная среды	Description
AZURE_CLIENT_ID	Идентификатор приложения (клиента) в зарегистрированном приложении
AZURE_CLIENT_SECRET	Значение секрета клиента в зарегистрированном приложении
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 Карты. Ключ подписки можно найти в разделе "Проверка подлинности" в учетной записи azure Карты, как показано на следующем снимке экрана:

Необходимо передать ключ 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);

Использование учетных данных маркера подписанного URL-адреса (SAS)

Маркеры подписанного URL-адреса (SAS) — это маркеры проверки подлинности, созданные с помощью формата JSON Web token (JWT) и криптографически подписанные для подтверждения подлинности приложения для REST API Azure Maps.

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

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

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

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

node search.js

Геокодирование обратной службы пакетной службы

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

  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;

В следующем примере показано создание функции, которая принимает адрес и поиск ПО вокруг него. Используйте пакет SDK версии 2, чтобы получить координаты адреса (/геокода) и пакета SDK версии 1 для поиска ПО вокруг него (/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);
})

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

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

Поделиться через