Uso del módulo de servicios de Azure Maps

Artigo
04/12/2024

El SDK web de Azure Maps proporciona un módulo de servicios. Este módulo es una biblioteca de ayuda que facilita el uso de los servicios REST de Azure Maps en la web o aplicaciones de Node.js mediante JavaScript o TypeScript.

Nota:

Retirada del módulo de servicio del SDK de Azure Maps para web

El módulo de servicio del SDK de Azure Maps para web ya está en desuso y se retirará el 30 de septiembre de 2026. Para evitar interrupciones del servicio, se recomienda migrar al SDK de Azure Maps para REST de JavaScript antes del 30 de septiembre de 2026. Para obtener más información, consulte la Guía para desarrolladores del SDK de REST de JavaScript/TypeScript.

Uso del módulo de servicios en una página web

Cree un archivo HTML.
Cargue el módulo de servicios de Azure Maps. Puede realizar ese procedimiento de alguna de estas dos formas:
- Utilizar la versión de Azure Content Delivery Network hospedada globalmente del módulo de servicios de Azure Maps. Agregue una referencia de script al elemento <head> del archivo:
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- Si lo desea, también puede cargar localmente el módulo de servicios del SDK web de Azure Maps utilizando el paquete npm azure-maps-rest y hospedarlo después con la aplicación. Este paquete también incluye las definiciones de TypeScript. Use este comando:
  
  npm install azure-maps-rest
  
  Después, use una declaración de importación para agregar el módulo a un archivo de código fuente:
```
import * as service from "azure-maps-rest";
```

Cree una canalización de autenticación. Para poder inicializar un punto de conexión de cliente con la dirección URL del servicio, primero debe crearse la canalización. Use su propia clave de cuenta de Azure Maps o las credenciales de Microsoft Entra para autenticar un cliente del servicio de búsqueda de Azure Maps. En este ejemplo, se crea el cliente de la dirección URL del servicio de búsqueda.

Si usa una clave de suscripción para la autenticación:

// 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 usa Microsoft Entra ID para la autenticación:

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

Para obtener más información, consulte Autenticación con Azure Maps.

El código siguiente usa el cliente de dirección URL de servicio de Azure Maps Search recién creado para establecer un código geográfico de una dirección: "1 Microsoft Way, Redmond, WA". El código usa la función searchAddress y muestra los resultados en forma de tabla en el cuerpo de la página.

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

Aquí se muestra el ejemplo de código de ejecución completo:

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

La siguiente imagen es una captura de pantalla que muestra los resultados de este código de ejemplo, una tabla con la dirección buscada, junto con las coordenadas resultantes.

Captura de pantalla de una tabla HTML que muestra la dirección buscada y las coordenadas resultantes.

Compatibilidad con la nube de Azure Government

El SDK web de Azure Maps es compatible con la nube de Azure Government. Todas las direcciones URL de JavaScript y CSS que se usan para acceder al SDK web de Azure Maps siguen siendo las mismas; sin embargo, es necesario realizar las tareas siguientes para conectarse a la versión de la plataforma Azure Maps situada en la nube de Azure Government.

Cuando utilice el control de mapas interactivos, agregue la siguiente línea de código antes de crear una instancia de la clase Map.

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

No olvide usar los datos de autenticación de Azure Maps de la plataforma en la nube de Azure Government cuando autentique el mapa y los servicios.

El dominio de los servicios debe establecerse al crear una instancia de un punto de conexión de la dirección URL de la API. Por ejemplo, el código siguiente crea una instancia de la clase SearchURL y hace que el dominio apunte a la nube de Azure Government.

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

Si tiene acceso directo a los servicios REST de Azure Maps, cambie el dominio de la dirección URL a atlas.azure.us. Por ejemplo, si utiliza el servicio de la API de búsqueda, cambie el dominio de la dirección URL de https://atlas.microsoft.com/search/ a https://atlas.azure.us/search/.