De Azure Kaarten-servicesmodule gebruiken

Artikel
04/07/2024

De Azure Kaarten Web SDK biedt een servicesmodule. Deze module is een helperbibliotheek waarmee u eenvoudig de Azure Kaarten REST-services in web- of Node.js-toepassingen kunt gebruiken met behulp van JavaScript of TypeScript.

Notitie

Buitengebruikstelling van Azure Kaarten Web SDK-servicemodule

De Azure Kaarten Web SDK-servicemodule is nu afgeschaft en wordt buiten gebruik gesteld op 30-9-26. Om serviceonderbrekingen te voorkomen, wordt u aangeraden om te migreren naar de Azure Kaarten JavaScript REST SDK voor 30-9-26. Zie de ontwikkelaarshandleiding voor JavaScript/TypeScript REST SDK (preview) voor meer informatie.

De servicesmodule op een webpagina gebruiken

Maak een nieuw HTML-bestand.
Laad de Azure Kaarten-servicesmodule. U kunt deze op twee manieren laden:
- Gebruik de wereldwijd gehoste Azure Content Delivery Network-versie van de Azure Kaarten-servicesmodule. Voeg een scriptreferentie toe aan het <head> element van het bestand:
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- U kunt ook de servicesmodule voor de broncode van de Azure Kaarten Web SDK lokaal laden met behulp van het npm-pakket azure-maps-rest en deze vervolgens hosten met uw app. Dit pakket bevat ook TypeScript-definities. Gebruik deze opdracht
  
  npm install azure-maps-rest
  
  Gebruik vervolgens een importdeclaratie om de module toe te voegen aan een bronbestand:
```
import * as service from "azure-maps-rest";
```

Maak een verificatiepijplijn. De pijplijn moet worden gemaakt voordat u een service-URL-clienteindpunt kunt initialiseren. Gebruik uw eigen Azure Kaarten-accountsleutel of Microsoft Entra-referenties om een Azure Kaarten Search-service-client te verifiëren. In dit voorbeeld wordt de Search-service URL-client gemaakt.

Als u een abonnementssleutel gebruikt voor verificatie:

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

Als u Microsoft Entra-id gebruikt voor verificatie:

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

Zie Verificatie met Azure Kaarten voor meer informatie.

De volgende code maakt gebruik van de zojuist gemaakte Azure Kaarten Search-service URL-client om een adres te coderen: '1 Microsoft Way, Redmond, WA'. De code gebruikt de searchAddress functie en geeft de resultaten weer als een tabel in de hoofdtekst van de pagina.

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

Hier volgt het volledige codevoorbeeld:

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

De volgende afbeelding is een schermopname met de resultaten van deze voorbeeldcode, een tabel met het adres waarnaar is gezocht, samen met de resulterende coördinaten.

Een schermopname van een HTML-tabel met het gezochte adres en de resulterende coördinaten.

Azure Government-cloudondersteuning

De Azure Kaarten Web SDK ondersteunt de Azure Government-cloud. Alle JavaScript- en CSS-URL's die worden gebruikt voor toegang tot de Azure Kaarten Web SDK blijven hetzelfde, maar de volgende taken moeten worden uitgevoerd om verbinding te maken met de Azure Government-cloudversie van het Azure Kaarten-platform.

Wanneer u het interactieve kaartbeheer gebruikt, voegt u de volgende regel code toe voordat u een exemplaar van de Map klasse maakt.

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

Zorg ervoor dat u een Azure Kaarten verificatiegegevens van het Azure Government-cloudplatform gebruikt bij het verifiëren van de kaart en services.

Het domein voor de services moet worden ingesteld bij het maken van een exemplaar van een API-URL-eindpunt. Met de volgende code wordt bijvoorbeeld een exemplaar van de SearchURL klasse gemaakt en wordt het domein naar de Azure Government-cloud verwezen.

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

Als u rechtstreeks toegang hebt tot de Azure Kaarten REST-services, wijzigt u het URL-domein in atlas.azure.us. Als u bijvoorbeeld de zoek-API-service gebruikt, wijzigt u het URL-domein van https://atlas.microsoft.com/search/ in https://atlas.azure.us/search/.