Руководство разработчиков ПАКЕТА REST SDK для JavaScript и TypeScript (предварительная версия)
Пакет REST SDK для Azure Maps и TypeScript (пакет 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
Создание и проверка подлинности MapsSearchClient
При создании объекта, используемого MapsSearchClient для доступа к API поиска Azure Maps, требуется credential объект для проверки подлинности. Для проверки подлинности можно использовать учетные данные Microsoft Entra или ключ подписки Azure. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Maps".
Совет
ЭтоMapsSearchClient основной интерфейс для разработчиков с помощью библиотеки поиска Azure Maps. Дополнительные сведения о доступных методах поиска см . в клиентской библиотеке поиска Azure Maps.
Использование учетных данных Microsoft Entra
Вы можете пройти проверку подлинности с помощью идентификатора Microsoft Entra с помощью библиотеки удостоверений Azure. Чтобы использовать поставщик DefaultAzureCredential , необходимо установить @azure/identity пакет:
npm install @azure/identity
Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Maps, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от 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 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);
Использование учетных данных маркера подписанного URL-адреса (SAS)
Маркеры подписанного URL-адреса (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;
В следующем примере показано создание функции, которая принимает адрес и поиск ПО вокруг него. Используйте пакет 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);
})