Utiliser le module des services Azure Maps

Article
04/11/2024

Le Kit de développement logiciel (SDK) web Azure Maps fournit un module des services. Ce module est une bibliothèque d’assistance facilitant l’utilisation des services REST Azure Maps dans des applications web ou Node.js en utilisant JavaScript ou TypeScript.

Remarque

Mise hors service du module de services du kit de développement logiciel (SDK) web Azure Maps

Le module de services du kit de développement logiciel (SDK) web Azure Maps est désormais déconseillé et va être mis hors service le 30 septembre 2026. Pour éviter toute interruption de service, nous vous recommandons de migrer vers le kit de développement logiciel (SDK) REST JavaScript Azure Maps avant le 30 septembre 2006. Pour plus d’informations, consultez le Guide des développeurs du SDK JavaScript/TypeScript REST (préversion).

Utiliser le module des services dans une page web

Créez un fichier HTML.
Chargez le module des services Azure Maps. Vous pouvez le faire de deux façons :
- Utiliser la version d’Azure Content Delivery Network du module des services Azure Maps hébergée globalement. Ajoutez une référence de script à l’élément <head> du fichier :
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- Vous pouvez également charger le module de services pour le code source du kit SDK web d’Azure Maps localement à l’aide du package npm azure-maps-control, puis l’héberger avec votre application. Ce package inclut aussi des définitions de TypeScript. Utilisez la commande suivante :
  
  npm install azure-maps-rest
  
  Ensuite, utilisez une déclaration d’importation pour ajouter le module dans un fichier source :
```
import * as service from "azure-maps-rest";
```

Créez un pipeline d’authentification. Pour pouvoir initialiser un point de terminaison de client d’URL du service, il est nécessaire que le pipeline soit créé au préalable. Pour authentifier un client du service Search Azure Maps, utilisez votre propre clé de compte Azure Maps ou vos informations d’identification Microsoft Entra. Dans cet exemple, le client d’URL du service Recherche est créé.

Si vous utilisez une clé d’abonnement pour l’authentification :

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

Si vous utilisez Microsoft Entra ID pour l’authentification :

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

Pour plus d’informations, voir Authentification avec Azure Maps.

Le code suivant utilise le nouveau client d’URL du service Recherche Azure Maps pour associer un géocode à une adresse : « 1 Microsoft Way, Redmond, WA ». Le code utilise la fonction searchAddress et affiche les résultats sous la forme d’une table dans le corps de la page.

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

Voici l’exemple complet de code en cours d’exécution :

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

L’image suivante est une capture d’écran montrant les résultats de cet exemple de code, une table avec l’adresse recherchée, ainsi que les coordonnées obtenues.

Capture d’écran d’une table HTML montrant l’adresse recherchée et les coordonnées obtenues.

Prise en charge du cloud Azure Government

Le SDK web d’Azure Maps prend en charge le cloud Azure Government. Toutes les URL JavaScript et CSS utilisées pour accéder au SDK web d’Azure Maps restent les mêmes. Toutefois, les tâches suivantes doivent être effectuées pour se connecter à la version du cloud Azure Government de la plateforme Azure Maps.

Quand vous utilisez le contrôle de carte interactif, ajoutez la ligne de code suivante avant de créer une instance de la classe Map.

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

Veillez à utiliser les détails d’une authentification Azure Maps à partir de la plateforme du cloud Azure Government lors de l’authentification de la carte et des services.

Le domaine des services doit être défini lors de la création d’une instance d’un point de terminaison d’URL d’API. Par exemple, le code suivant crée une instance de la classe SearchURL et pointe le domaine vers le cloud Azure Government.

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

Si vous accédez directement aux services REST d’Azure Maps, définissez le domaine de l’URL sur atlas.azure.us. Par exemple, si vous utilisez le service API de recherche, remplacez le domaine URL https://atlas.microsoft.com/search/ par https://atlas.azure.us/search/.