Použití modulu služeb Azure Mapy

Článek
04/07/2024

Sada Azure Mapy Web SDK poskytuje modul služeb. Tento modul je pomocná knihovna, která usnadňuje používání služeb Azure Mapy REST ve webových nebo Node.js aplikacích pomocí JavaScriptu nebo TypeScriptu.

Poznámka:

Vyřazení modulu služby Azure Mapy Web SDK

Modul služby Azure Mapy Web SDK je teď zastaralý a 30. 9. 26 se vyřadí z provozu. Pokud se chcete vyhnout přerušení služeb, doporučujeme migrovat do sady Azure Mapy JavaScript REST SDK do 30. 9. 26. Další informace najdete v tématu JavaScript/TypeScript REST SDK – Příručka pro vývojáře (Preview).

Použití modulu služeb na webové stránce

Vytvořte nový soubor HTML.
Načtěte modul služeb Azure Mapy. Můžete ho načíst jedním ze dvou způsobů:
- Použijte globálně hostované prostředí Azure Content Delivery Network verze modulu služeb Azure Mapy. Přidejte odkaz na skript k <head> prvku souboru:
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- Případně načtěte modul služeb pro zdrojový kód sady Azure Mapy Web SDK místně pomocí balíčku npm azure-maps-rest a pak ho hostujte s vaší aplikací. Tento balíček obsahuje také definice TypeScriptu. Použijte tento příkaz:
  
  npm install azure-maps-rest
  
  Pak pomocí deklarace importu přidejte modul do zdrojového souboru:
```
import * as service from "azure-maps-rest";
```

Vytvořte ověřovací kanál. Před inicializací koncového bodu klienta adresy URL služby je nutné vytvořit kanál. K ověření klienta Azure Mapy Search použijte vlastní klíč účtu Azure Mapy nebo přihlašovací údaje Microsoft Entra. V tomto příkladu se vytvoří klient Search URL.

Pokud k ověřování použijete klíč předplatného:

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

Pokud pro ověřování použijete ID Microsoft Entra:

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

Další informace najdete v tématu Ověřování pomocí Azure Mapy.

Následující kód používá nově vytvořeného klienta adresy URL Azure Mapy Search k geokódování adresy: "1 Microsoft Way, Redmond, WA". Kód použije searchAddress funkci a zobrazí výsledky jako tabulku v textu stránky.

// 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('');
});

Tady je úplná ukázka spuštěného kódu:

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

Následující obrázek je snímek obrazovky znázorňující výsledky tohoto ukázkového kódu, tabulku s adresou, kterou jste hledali, spolu s výslednými souřadnicemi.

Snímek obrazovky tabulky HTML s prohledánou adresou a výslednými souřadnicemi

Podpora cloudu Azure Government

Sada Azure Mapy Web SDK podporuje cloud Azure Government. Všechny adresy URL JavaScriptu a CSS používané pro přístup k sadě Azure Mapy Web SDK zůstanou stejné, ale pro připojení ke cloudové verzi Azure Government platformy Azure Mapy je potřeba provést následující úlohy.

Při použití interaktivního mapového ovládacího prvku před vytvořením instance Map třídy přidejte následující řádek kódu.

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

Při ověřování map a služeb nezapomeňte použít podrobnosti ověřování Azure Mapy z cloudové platformy Azure Government.

Při vytváření instance koncového bodu adresy URL rozhraní API je potřeba nastavit doménu pro služby. Například následující kód vytvoří instanci SearchURL třídy a nasoudí doménu do cloudu Azure Government.

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

Pokud přímo přistupujete ke službám Azure Mapy REST, změňte doménu adresy URL na atlas.azure.us. Pokud například používáte službu vyhledávacího rozhraní API, změňte doménu adresy URL z https://atlas.microsoft.com/search/ na https://atlas.azure.us/search/.