Azure Haritalar hizmetleri modülünü kullanma

  • Makale

Azure Haritalar Web SDK'sı bir hizmet modülü sağlar. Bu modül, JavaScript veya TypeScript kullanarak web veya Node.js uygulamalarında Azure Haritalar REST hizmetlerini kullanmayı kolaylaştıran bir yardımcı kitaplıktır.

Not

Azure Haritalar Web SDK Hizmeti Modülü kullanımdan kaldır

Azure Haritalar Web SDK Hizmeti Modülü artık kullanım dışıdır ve 30.09.26 tarihinde kullanımdan kaldırılacaktır. Hizmet kesintilerini önlemek için 30.09.26'ya kadar Azure Haritalar JavaScript REST SDK'sına geçiş yapmanızı öneririz. Daha fazla bilgi için bkz. JavaScript/TypeScript REST SDK Geliştirici Kılavuzu (önizleme).

Web sayfasında hizmetler modülünü kullanma

  1. Yeni bir HTML dosyası oluşturun.

  2. Azure Haritalar hizmetleri modülünü yükleyin. İki yoldan biriyle yükleyebilirsiniz:

    • Azure Haritalar hizmetleri modülünün genel olarak barındırılan Azure Content Delivery Network sürümünü kullanın. Dosyanın öğesine bir betik başvurusu <head> ekleyin:
    <script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>

    • Alternatif olarak, azure-maps-rest npm paketini kullanarak Azure Haritalar Web SDK'sı kaynak kodunun hizmet modülünü yerel olarak yükleyin ve ardından uygulamanızla barındırın. Bu paket, TypeScript tanımlarını da içerir. Şu komutu çalıştırın:

      npm install azure-maps-rest

      Ardından, modülü bir kaynak dosyaya eklemek için içeri aktarma bildirimini kullanın:

      import * as service from "azure-maps-rest";

  3. Kimlik doğrulama işlem hattı oluşturma. Hizmet URL'si istemci uç noktasını başlatabilmeniz için işlem hattı oluşturulmalıdır. bir Azure Haritalar Arama hizmeti istemcisinin kimliğini doğrulamak için kendi Azure Haritalar hesap anahtarınızı veya Microsoft Entra kimlik bilgilerinizi kullanın. Bu örnekte, Arama hizmeti URL istemcisi oluşturulur.

    Kimlik doğrulaması için abonelik anahtarı kullanıyorsanız:

    // Get an Azure Maps key at https://azure.com/maps.
var subscriptionKey = '<Your Azure Maps Key>';

// Use SubscriptionKeyCredential with a subscription key.
var subscriptionKeyCredential = new atlas.service.SubscriptionKeyCredential(subscriptionKey);

// Use subscriptionKeyCredential to create a pipeline.
var pipeline = atlas.service.MapsURL.newPipeline(subscriptionKeyCredential, {
  retryOptions: { maxTries: 4 } // Retry options
});

// Create an instance of the SearchURL client.
var searchURL = new atlas.service.SearchURL(pipeline);

    Kimlik doğrulaması için Microsoft Entra Id kullanıyorsanız:

    // Enter your Azure AD client ID.
var clientId = "<Your Azure Active Directory Client Id>";

// Use TokenCredential with OAuth token (Azure AD or Anonymous).
var aadToken = await getAadToken();
var tokenCredential = new atlas.service.TokenCredential(clientId, aadToken);

// Create a repeating time-out that will renew the Azure AD token.
// This time-out must be cleared when the TokenCredential object is no longer needed.
// If the time-out is not cleared, the memory used by the TokenCredential will never be reclaimed.
var renewToken = async () => {
  try {
    console.log("Renewing token");
    var token = await getAadToken();
    tokenCredential.token = token;
    tokenRenewalTimer = setTimeout(renewToken, getExpiration(token));
  } catch (error) {
    console.log("Caught error when renewing token");
    clearTimeout(tokenRenewalTimer);
    throw error;
  }
}
tokenRenewalTimer = setTimeout(renewToken, getExpiration(aadToken));

// Use tokenCredential to create a pipeline.
var pipeline = atlas.service.MapsURL.newPipeline(tokenCredential, {
  retryOptions: { maxTries: 4 } // Retry options
});

// Create an instance of the SearchURL client.
var searchURL = new atlas.service.SearchURL(pipeline);

function getAadToken() {
  // Use the signed-in auth context to get a token.
  return new Promise((resolve, reject) => {
    // The resource should always be https://atlas.microsoft.com/.
    const resource = "https://atlas.microsoft.com/";
    authContext.acquireToken(resource, (error, token) => {
      if (error) {
        reject(error);
      } else {
        resolve(token);
      }
    });
  })
}

function getExpiration(jwtToken) {
  // Decode the JSON Web Token (JWT) to get the expiration time stamp.
  const json = atob(jwtToken.split(".")[1]);
  const decode = JSON.parse(json);

  // Return the milliseconds remaining until the token must be renewed.
  // Reduce the time until renewal by 5 minutes to avoid using an expired token.
  // The exp property is the time stamp of the expiration, in seconds.
  const renewSkew = 300000;
  return (1000 * decode.exp) - Date.now() - renewSkew;
}

    Daha fazla bilgi için bkz. Azure Haritalar ile kimlik doğrulaması.

  4. Aşağıdaki kod, bir adresi coğrafi kodlamak için yeni oluşturulan Azure Haritalar Arama hizmeti URL istemcisini kullanır: "1 Microsoft Way, Redmond, WA". Kod işlevini kullanır searchAddress ve sonuçları sayfanın gövdesinde bir tablo olarak görüntüler.

    // Search for "1 microsoft way, redmond, wa".
searchURL.searchAddress(atlas.service.Aborter.timeout(10000), '1 microsoft way, redmond, wa')
  .then(response => {
    var html = [];

    // Display the total results.
    html.push('Total results: ', response.summary.numResults, '<br/><br/>');

    // Create a table of the results.
    html.push('<table><tr><td></td><td>Result</td><td>Latitude</td><td>Longitude</td></tr>');

    for(var i=0;i<response.results.length;i++){
      html.push('<tr><td>', (i+1), '.</td><td>', 
        response.results[i].address.freeformAddress, 
        '</td><td>', 
        response.results[i].position.lat,
        '</td><td>', 
        response.results[i].position.lon,
        '</td></tr>');
    }

    html.push('</table>');

    // Add the resulting HTML to the body of the page.
    document.body.innerHTML = html.join('');
});

İşte tam, çalışan kod örneği:

<html>
 <head>

  <script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>

  <script type="text/javascript">
    
    // Get an Azure Maps key at https://azure.com/maps.
    var subscriptionKey = '{Your-Azure-Maps-Subscription-key}';

    // Use SubscriptionKeyCredential with a subscription key.
    var subscriptionKeyCredential = new atlas.service.SubscriptionKeyCredential(subscriptionKey);

    // Use subscriptionKeyCredential to create a pipeline.
    var pipeline = atlas.service.MapsURL.newPipeline(subscriptionKeyCredential, {
      retryOptions: { maxTries: 4 } // Retry options
    });

    // Create an instance of the SearchURL client.
    var searchURL = new atlas.service.SearchURL(pipeline);

    // Search for "1 microsoft way, redmond, wa".
    searchURL.searchAddress(atlas.service.Aborter.timeout(10000), '1 microsoft way, redmond, wa')
      .then(response => {
      var html = [];

      // Display the total results.
      html.push('Total results: ', response.summary.numResults, '<br/><br/>');

      // Create a table of the results.
      html.push('<table><tr><td></td><td>Result</td><td>Latitude</td><td>Longitude</td></tr>');

      for(var i=0;i<response.results.length;i++){
        html.push('<tr><td>', (i+1), '.</td><td>', 
        response.results[i].address.freeformAddress, 
        '</td><td>', 
        response.results[i].position.lat,
        '</td><td>', 
        response.results[i].position.lon,
        '</td></tr>');
      }

      html.push('</table>');

      // Add the resulting HTML to the body of the page.
      document.body.innerHTML = html.join('');
    });

  </script>
</head>

<style>
  table {
    border: 1px solid black;
    border-collapse: collapse;
  }
  td, th {
    border: 1px solid black;
    padding: 5px;
  }
</style>

<body> </body>

</html>

Aşağıdaki görüntüde, bu örnek kodun sonuçlarını gösteren bir ekran görüntüsü, adresin aranmış olduğu bir tablo ve sonuçta elde edilen koordinatlar verilmiştir.

Aranan adresi ve sonuçta elde edilen koordinatları gösteren HTML tablosunun ekran görüntüsü.

Azure Kamu bulut desteği

Azure Haritalar Web SDK'sı Azure Kamu bulutunu destekler. Azure Haritalar Web SDK'sına erişmek için kullanılan tüm JavaScript ve CSS URL'leri aynı kalır, ancak Azure Haritalar platformunun Azure Kamu bulut sürümüne bağlanmak için aşağıdaki görevlerin yapılması gerekir.

Etkileşimli harita denetimini kullanırken, sınıfın bir örneğini Map oluşturmadan önce aşağıdaki kod satırını ekleyin.

atlas.setDomain('atlas.azure.us');

Haritanın ve hizmetlerin kimliğini doğrularken Azure Kamu bulut platformundan Azure Haritalar kimlik doğrulama ayrıntılarını kullandığınızdan emin olun.

BIR API URL uç noktasının örneği oluşturulurken hizmetlerin etki alanının ayarlanması gerekir. Örneğin, aşağıdaki kod sınıfının bir örneğini SearchURL oluşturur ve etki alanını Azure Kamu buluta gösterir.

var searchURL = new atlas.service.SearchURL(pipeline, 'atlas.azure.us');

Azure Haritalar REST hizmetlerine doğrudan erişiyorsa, URL etki alanını olarak atlas.azure.usdeğiştirin. Örneğin, arama API'si hizmetini kullanıyorsanız URL etki alanını olarak https://atlas.microsoft.com/search/ https://atlas.azure.us/search/değiştirin.

Sonraki adımlar

Bu makalede kullanılan sınıflar ve yöntemler hakkında daha fazla bilgi edinin:

Haritalar URL

SearchURL

Routeurl

SubscriptionKeyCredential

TokenCredential

Hizmetler modülünü kullanan diğer kod örnekleri için şu makalelere bakın:

Arama sonuçlarını haritada gösterme

Koordinattan bilgi alma

A'dan B'ye yol tariflerini gösterme