JavaScript/TypeScript REST SDK Developers Guide (wersja zapoznawcza)

Artykuł
02/02/2024

Zestaw AZURE Mapy JavaScript/TypeScript REST SDK (JavaScript SDK) obsługuje wyszukiwanie przy użyciu usługa wyszukiwania azure Mapy, takich jak wyszukiwanie adresu, wyszukiwanie granicy miasta lub kraju i wyszukiwanie według współrzędnych. Ten artykuł ułatwia rozpoczęcie tworzenia aplikacji obsługujących lokalizację, które obejmują możliwości usługi Azure Mapy.

Uwaga

Zestaw SDK języka JavaScript platformy Azure Mapy obsługuje wersję Node.js LTS. Aby uzyskać więcej informacji, zobacz Node.js Release Working Group(Grupa robocza wydania).

Wymagania wstępne

Konto usługi Azure Mapy.
Klucz subskrypcji lub inna forma uwierzytelniania za pomocą usługi Azure Mapy.
Node.js.

Napiwek

Możesz programowo utworzyć konto usługi Azure Mapy. Oto przykład przy użyciu interfejsu wiersza polecenia platformy Azure:

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

Tworzenie projektu z użyciem narzędzia Node.js

Poniższy przykład tworzy nowy katalog, a następnie program Node.js o nazwie mapsDemo przy użyciu narzędzia npm:

mkdir mapsDemo
cd mapsDemo
npm init

Instalowanie pakietu wyszukiwania

Aby użyć zestawu SDK języka JavaScript platformy Azure Mapy, należy zainstalować pakiet wyszukiwania. Każda z usług Azure Mapy, w tym wyszukiwanie, routing, renderowanie i geolokalizacja, znajdują się we własnym pakiecie.

npm install @azure-rest/maps-search

Po zainstalowaniu pakietu utwórz search.js plik w mapsDemo katalogu:

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

Usługi Azure Maps

Nazwa usługi	Pakiety npm	Próbki
Wyszukaj	@azure-rest/maps-search	wyszukiwanie przykładów
Trasa	@azure rest/maps-route	przykłady tras
Renderowanie	@azure rest/maps-render	renderuj przykład
Geolokalizacja	@azure-rest/maps-geolokalizacja	przykład geolokalizacji

Tworzenie i uwierzytelnianie Mapy SearchClient

Wymagany credential jest obiekt uwierzytelniania podczas tworzenia obiektu używanego MapsSearchClient do uzyskiwania dostępu do interfejsów API wyszukiwania usługi Azure Mapy. Do uwierzytelniania można użyć poświadczeń usługi Microsoft Entra lub klucza subskrypcji platformy Azure. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Mapy (Uwierzytelnianie przy użyciu usługi Azure Mapy).

Napiwek

JestMapsSearchClient to podstawowy interfejs dla deweloperów korzystających z biblioteki wyszukiwania usługi Azure Mapy. Zobacz Bibliotekę klienta usługi Azure Mapy Search, aby dowiedzieć się więcej o dostępnych metodach wyszukiwania.

Używanie poświadczeń entra firmy Microsoft

Możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft przy użyciu biblioteki tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential , należy zainstalować @azure/identity pakiet:

npm install @azure/identity

Musisz zarejestrować nową aplikację Firmy Microsoft Entra i udzielić dostępu do usługi Azure Mapy, przypisując wymaganą rolę do jednostki usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracany jest identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz tajny klienta. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.

Ustaw wartości identyfikatora aplikacji (klienta), identyfikatora katalogu (dzierżawy) i wpisu tajnego klienta aplikacji Microsoft Entra oraz identyfikator klienta zasobu mapy jako zmienne środowiskowe:

Zmienna środowiskowa	opis
AZURE_CLIENT_ID	Identyfikator aplikacji (klienta) w zarejestrowanej aplikacji
AZURE_CLIENT_SECRET	Wartość wpisu tajnego klienta w zarejestrowanej aplikacji
AZURE_TENANT_ID	Identyfikator katalogu (dzierżawy) w zarejestrowanej aplikacji
MAPS_CLIENT_ID	Identyfikator klienta na koncie usługi Azure Map

Możesz użyć .env pliku dla tych zmiennych. Należy zainstalować pakiet dotenv :

npm install dotenv

Następnie dodaj .env plik w katalogu mapsDemo i określ następujące właściwości:

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

Po utworzeniu zmiennych środowiskowych możesz uzyskać do nich dostęp w kodzie 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);

Używanie poświadczeń klucza subskrypcji

Możesz uwierzytelnić się przy użyciu klucza subskrypcji usługi Azure Mapy. Klucz subskrypcji można znaleźć w sekcji Uwierzytelnianie na koncie usługi Azure Mapy, jak pokazano na poniższym zrzucie ekranu:

Musisz przekazać klucz subskrypcji do klasy dostarczonej AzureKeyCredential przez pakiet uwierzytelniania podstawowego platformy Azure. Ze względów bezpieczeństwa lepiej określić klucz jako zmienną środowiskową niż uwzględnić go w kodzie źródłowym.

.env Aby to osiągnąć, użyj pliku do przechowywania zmiennej klucza subskrypcji. Aby pobrać wartość, musisz zainstalować pakiet dotenv :

npm install dotenv

Następnie dodaj .env plik w katalogu mapsDemo i określ właściwość :

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

Po utworzeniu zmiennej środowiskowej możesz uzyskać do niej dostęp w kodzie 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);

Używanie poświadczeń tokenu sygnatury dostępu współdzielonego (SAS)

Tokeny sygnatury dostępu współdzielonego (SAS) to tokeny uwierzytelniania utworzone przy użyciu formatu tokenu internetowego JSON (JWT) i są podpisywane kryptograficznie w celu potwierdzenia uwierzytelniania aplikacji w interfejsie API REST usługi Azure Mapy.

Token SAS można uzyskać przy użyciu AzureMapsManagementClient.accounts.listSas pakietu. Postępuj zgodnie z sekcją Tworzenie i uwierzytelnianie elementu AzureMapsManagementClient , aby najpierw skonfigurować.

Następnie postępuj zgodnie z instrukcjami Tożsamości zarządzane dla usługi Azure Mapy, aby utworzyć tożsamość zarządzaną dla konta usługi Azure Mapy. Skopiuj identyfikator podmiotu zabezpieczeń (identyfikator obiektu) tożsamości zarządzanej.

Następnie zainstaluj pakiet pakietu Azure Core Authentication , aby użyć polecenia AzureSASCredential:

npm install @azure/core-auth

Na koniec możesz użyć tokenu SAS do uwierzytelniania klienta:

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

Geokodowanie

Poniższy fragment kodu pokazuje, jak w prostej aplikacji konsolowej zaimportować @azure-rest/maps-search pakiet i uzyskać współrzędne adresu przy użyciu zapytania 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);
});

Ten fragment kodu przedstawia sposób użycia metody z biblioteki klienta usługi Azure Mapy Search w celu utworzenia client obiektu przy użyciu MapsSearch poświadczeń platformy Azure. Możesz użyć klucza subskrypcji usługi Azure Mapy lub poświadczeń usługi Microsoft Entra. Parametr path określa punkt końcowy interfejsu API, który w tym przypadku to "/geocode". Metoda get wysyła żądanie HTTP GET z parametrami zapytania. Zapytanie wyszukuje współrzędną "1301 Alaskan Way, Seattle, WA 98101, US". Zestaw SDK zwraca wyniki jako obiekt GeocodingResponseOutput i zapisuje je w konsoli. Wyniki są uporządkowane według wskaźnika ufności w tym przykładzie i wyświetlany jest tylko pierwszy wynik na ekranie. Aby uzyskać więcej informacji, zobacz GetGeocoding.

Uruchom polecenie search.js przy użyciu Node.js:

node search.js

Odwrotne geokodowanie wsadowe

Usługa Azure Mapy Search udostępnia również niektóre metody zapytań wsadowych. W poniższym przykładzie pokazano, jak wywołać metodę wyszukiwania odwrotnego wsadowego:

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

W tym przykładzie trzy współrzędne są uwzględniane w batchItems treści żądania. Pierwszy element jest nieprawidłowy, zobacz Obsługa nieudanych żądań , aby zapoznać się z przykładem pokazującym sposób obsługi nieprawidłowego elementu.

Po otrzymaniu odpowiedzi możesz ją zarejestrować:

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

Obsługa żądań, które zakończyły się niepowodzeniem

Obsługa żądań, które zakończyły się niepowodzeniem, sprawdzając error właściwość w elemencie wsadowym odpowiedzi. logResponseBody Zobacz funkcję w ukończonym wyszukiwaniu odwrotnym wsadowym w poniższym przykładzie.

Przykład ukończonego wyszukiwania odwrotnego wsadowego

Kompletny kod dla przykładu wyszukiwania wsadowego odwrotnego adresu:

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

Korzystanie z zestawu SDK w wersji 1

Pracujemy nad udostępnieniem wszystkich funkcji v1 w wersji 2, aż do tego czasu zainstaluj następujące pakiety zestawu SDK w wersji 1 w razie potrzeby:

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

Następnie możesz zaimportować dwa pakiety:

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

W poniższym przykładzie pokazano tworzenie funkcji, która akceptuje adres i wyszukuje wokół niej interfejsy POI. Użyj zestawu SDK w wersji 2, aby uzyskać współrzędne adresu (/kodu geograficznego) i zestawu SDK w wersji 1 w celu wyszukiwania wokół niego punktów weryfikacji (/wyszukiwania/pobliskiego).

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

Dodatkowe informacje

Biblioteka klienta usługi Azure Mapy Search dla języka JavaScript/TypeScript.