JavaScript/TypeScript REST SDK Geliştirici Kılavuzu (önizleme)

Makale
02/03/2024

Azure Haritalar JavaScript/TypeScript REST SDK 'sı (JavaScript SDK), adres arama, şehir veya ülke sınırı arama ve koordinatlara göre arama gibi Azure Haritalar Arama hizmeti kullanarak aramayı destekler. Bu makale, Azure Haritalar gücünü içeren konum algılamalı uygulamalar oluşturmaya başlamanıza yardımcı olur.

Not

Azure Haritalar JavaScript SDK'sı Node.js LTS sürümünü destekler. Daha fazla bilgi için bkz . Node.js Yayın Çalışma Grubu.

Önkoşullar

Azure Haritalar hesabı.
Abonelik anahtarı veya Azure Haritalar ile başka bir Kimlik Doğrulaması biçimi.
Node.js.

İpucu

Program aracılığıyla bir Azure Haritalar hesabı oluşturabilirsiniz. Azure CLI'yı kullanan bir örnek aşağıda verilmiştir:

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

Node.js projesi oluşturma

Aşağıdaki örnek, npm kullanarak mapsDemo adlı bir Node.js programı oluşturarak yeni bir dizin oluşturur:

mkdir mapsDemo
cd mapsDemo
npm init

Arama paketini yükleme

Azure Haritalar JavaScript SDK'sını kullanmak için arama paketini yüklemeniz gerekir. Arama, yönlendirme, işleme ve coğrafi konum gibi Azure Haritalar hizmetlerinin her biri kendi paketlerindedir.

npm install @azure-rest/maps-search

Paket yüklendikten sonra dizininde mapsDemo bir search.js dosya oluşturun:

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

Azure Haritalar hizmetleri

Hizmet adı	npm paketleri	Örnekleri
Arama	@azure-rest/maps-search	arama örnekleri
Rota	@azure-rest/maps-route	yol örnekleri
İşleme	@azure-rest/maps-render	işleme örneği
Coğrafi Konum	@azure-rest/maps-geolocation	coğrafi konum örneği

Haritalar SearchClient oluşturma ve kimlik doğrulaması

Azure Haritalar arama API'lerine erişmek için kullanılan nesneyi oluştururken MapsSearchClient kimlik doğrulaması için bir credential nesneye ihtiyacınız vardır. Kimlik doğrulaması için Microsoft Entra kimlik bilgilerini veya Azure abonelik anahtarını kullanabilirsiniz. Kimlik doğrulaması hakkında daha fazla bilgi için bkz. Azure Haritalar ile kimlik doğrulaması.

İpucu

MapsSearchClient, Azure Haritalar arama kitaplığını kullanan geliştiriciler için birincil arabirimdir. Kullanılabilir arama yöntemleri hakkında daha fazla bilgi edinmek için bkz. Azure Haritalar Arama istemci kitaplığı.

Microsoft Entra kimlik bilgilerini kullanma

Azure Kimlik kitaplığını kullanarak Microsoft Entra Id ile kimlik doğrulaması yapabilirsiniz. DefaultAzureCredential sağlayıcısını kullanmak için paketini yüklemeniz @azure/identity gerekir:

npm install @azure/identity

Yeni Microsoft Entra uygulamasını kaydetmeniz ve hizmet sorumlunuza gerekli rolü atayarak Azure Haritalar erişimi vermeniz gerekir. Daha fazla bilgi için bkz . Azure dışı kaynaklarda daemon barındırma. Uygulama (istemci) kimliği, Dizin (kiracı) kimliği ve istemci gizli dizisi döndürülür. Bu değerleri kopyalayın ve güvenli bir yerde depolayın. Aşağıdaki adımlarda bunlara ihtiyacınız vardır.

Microsoft Entra uygulamanızın Uygulama (istemci) kimliği, Dizin (kiracı) kimliği ve istemci gizli dizisi değerlerini ve eşleme kaynağının istemci kimliğini ortam değişkenleri olarak ayarlayın:

Ortam değişkeni	Açıklama
AZURE_CLIENT_ID	Kayıtlı uygulamanızdaki uygulama (istemci) kimliği
AZURE_CLIENT_SECRET	Kayıtlı uygulamanızdaki istemci gizli dizisinin değeri
AZURE_TENANT_ID	Kayıtlı uygulamanızdaki dizin (kiracı) kimliği
MAPS_CLIENT_ID	Azure Map hesabınızdaki istemci kimliği

Bu değişkenler için bir .env dosya kullanabilirsiniz. Dotenv paketini yüklemeniz gerekir:

npm install dotenv

Ardından mapsDemo dizinine bir .env dosya ekleyin ve şu özellikleri belirtin:

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

Ortam değişkenleriniz oluşturulduktan sonra bunlara JavaScript kodunuzdan erişebilirsiniz:

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

Abonelik anahtarı kimlik bilgilerini kullanma

Azure Haritalar abonelik anahtarınızla kimlik doğrulaması yapabilirsiniz. Abonelik anahtarınız, aşağıdaki ekran görüntüsünde gösterildiği gibi Azure Haritalar hesabının Kimlik Doğrulaması bölümünde bulunabilir:

Abonelik anahtarını Azure Core Kimlik Doğrulama Paketi tarafından sağlanan sınıfa AzureKeyCredentialgeçirmeniz gerekir. Güvenlik nedenleriyle, anahtarı kaynak kodunuza eklemektense ortam değişkeni olarak belirtmek daha iyidir.

Bunu gerçekleştirmek için abonelik anahtarı değişkenini depolamak için bir .env dosya kullanın. Değeri almak için dotenv paketini yüklemeniz gerekir:

npm install dotenv

Ardından mapsDemo dizinine bir .env dosya ekleyin ve özelliğini belirtin:

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

Ortam değişkeniniz oluşturulduktan sonra JavaScript kodunuzdan bu değişkene erişebilirsiniz:

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

Paylaşılan Erişim İmzası (SAS) Belirteci Kimlik Bilgilerini Kullanma

Paylaşılan erişim imzası (SAS) belirteçleri, JSON Web belirteci (JWT) biçimi kullanılarak oluşturulan kimlik doğrulama belirteçleridir ve Azure Haritalar REST API'sinde bir uygulama için kimlik doğrulamasını kanıtlamak için şifresel olarak imzalanır.

SAS belirtecini paketi kullanarak AzureMapsManagementClient.accounts.listSas alabilirsiniz. Önce kurulum için oluşturma AzureMapsManagementClient ve kimlik doğrulaması oluşturma bölümünü izleyin.

İkinci olarak, Azure Haritalar hesabınız için yönetilen kimlik oluşturmak üzere Azure Haritalar için Yönetilen kimlikler'i izleyin. Yönetilen kimliğin asıl kimliğini (nesne kimliği) kopyalayın.

Ardından, kullanmak AzureSASCredentialiçin Azure Core Kimlik Doğrulama Paketi paketini yükleyin:

npm install @azure/core-auth

Son olarak, istemcinin kimliğini doğrulamak için SAS belirtecini kullanabilirsiniz:

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

Coğrafi kodlama

Aşağıdaki kod parçacığı, basit bir konsol uygulamasında paketi içeri aktarmayı @azure-rest/maps-search ve GetGeocoding sorgusunu kullanarak bir adresin koordinatlarını almayı gösterir:

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

Bu kod parçacığı, Azure kimlik bilgilerinizle bir client nesne oluşturmak için Azure Haritalar Search istemci kitaplığındaki yönteminin nasıl kullanılacağını MapsSearch gösterir. Azure Haritalar abonelik anahtarınızı veya Microsoft Entra kimlik bilgilerinizi kullanabilirsiniz. path parametresi, bu örnekte "/geocode" olan API uç noktasını belirtir. yöntemi sorgu get parametreleriyle bir HTTP GET isteği gönderir. Sorgu "1301 Alaskan Way, Seattle, WA 98101, ABD" koordinatını arar. SDK sonuçları GeocodingResponseOutput nesnesi olarak döndürür ve konsola yazar. Sonuçlar bu örnekte güvenilirlik puanına göre sıralanır ve ekranda yalnızca ilk sonuç görüntülenir. Daha fazla bilgi için bkz . GetGeocoding.

Node.js ile çalıştırın search.js :

node search.js

Toplu ters coğrafi kodlama

Azure Haritalar Arama bazı toplu sorgu yöntemleri de sağlar. Aşağıdaki örnek toplu ters arama yönteminin nasıl çağrılduğunu gösterir:

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

Bu örnekte, istek gövdesine batchItems üç koordinat eklenir. İlk öğe geçersiz, geçersiz öğenin nasıl işleneceğini gösteren bir örnek için bkz . Başarısız istekleri işleme.

Yanıtı aldıktan sonra günlüğe kaydedebilirsiniz:

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

Başarısız istekleri işleme

Yanıt toplu iş öğesinde error özelliği denetleyerek başarısız istekleri işleyebilir. logResponseBody Aşağıdaki örnekte tamamlanan toplu ters arama işlevine bakın.

Tamamlandı toplu ters arama örneği

Ters adres toplu arama örneği için tam kod:

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

V1 SDK'sı kullanma

O zamana kadar tüm V1 özelliklerini V2'de kullanılabilir hale getirmek için çalışıyoruz, gerekirse aşağıdaki V1 SDK paketlerini yükleyin:

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

Ardından iki paketi içeri aktarabilirsiniz:

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

Aşağıdaki örnekte, bir adresi kabul eden bir işlev oluşturma ve bu adresin etrafındaki İÇ'leri arama gösterilmektedir. V2 SDK'sını kullanarak adresin (/coğrafi kodun) ve V1 SDK'nın etrafındaki POI'leri aramak için (/arama/yakındaki) koordinatlarını alın.

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

Ek bilgi

JavaScript/TypeScript için Azure Haritalar Search istemci kitaplığı.

Aracılığıyla paylaş