Usar o módulo de serviços do Azure Mapas

Artigo
04/10/2024

O SDK da Web do Azure Mapas fornece um módulo de serviço. Esse módulo é uma biblioteca auxiliar que torna mais fácil usar os serviços REST do Azure Mapas em aplicativos Web ou Node.js usando JavaScript ou TypeScript.

Observação

Desativação do módulo de serviço SDK da Web do Azure Mapas

Atualmente, o módulo de serviço SDK da Web do Azure Mapas foi preterido e será desativado em 30/09/26. Para evitar interrupções de serviço, recomendamos migrar para o REST SDK do JavaScript do Azure Mapas até 30/09/26. Para obter mais informações, confira Guia de desenvolvedores do REST SDK do JavaScript/TypeScript (versão prévia).

Usar o módulo serviços em uma página da Web

Criar um novo arquivo HTML.
Carregar o módulo de serviços do Azure Mapas. É possível carregá-lo de duas formas:
- Use a versão da Rede de Distribuição de Conteúdo do Azure, hospedada globalmente do módulo de serviços do Azure Mapas. Adicione uma referência de script ao <head> elemento do arquivo:
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- Como alternativa, carregue o código-fonte do SDK Web do Azure Mapas localmente usando o pacote npm azure-maps-control e hospede-o com seu aplicativo. Esse pacote também inclui definições de TypeScript. Use este comando:
  
  npm install azure-maps-rest
  
  Em seguida, use uma declaração de importação para adicionar o módulo a um arquivo de origem:
```
import * as service from "azure-maps-rest";
```

Criar um pipeline de autenticação. O pipeline deve ser criado antes de você poder inicializar um ponto de extremidade de cliente da URL de serviço. Use sua própria chave de conta do Azure Mapas ou credenciais do Microsoft Entra para autenticar um cliente do serviço Pesquisa do Azure Mapas. Neste exemplo, o cliente da URL do serviço Pesquisa é criado.

Se estiver usando uma chave de assinatura para autenticação:

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

Se você usar o Microsoft Entra ID para autenticação:

// 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 saber mais, confira Autenticação no Azure Mapas.

O código a seguir usa o cliente URL do serviço de pesquisa do Azure Mapas recém-criado para geocodificar um endereço: "Microsoft Way, 1, Redmond, WA". O código usa a função searchAddress e exibe os resultados como uma tabela no corpo da 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('');
});

Aqui está o exemplo de código completo em execução:

<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 imagem a seguir é uma captura de tela mostrando os resultados deste código de exemplo, uma tabela com o endereço pesquisado, juntamente com as coordenadas resultantes.

Uma captura de tela de uma tabela HTML mostrando o endereço pesquisado e as coordenadas resultantes.

Suporte da nuvem do Azure Governamental

O SDK da Web do Azure Mapas dá suporte à nuvem do Azure Governamental. Todas as URLs de JavaScript e CSS usadas para acessar o SDK da Web do Azure Mapas permanecem as mesmas, no entanto, as tarefas a seguir precisam ser feitas para se conectar à versão de nuvem do Azure Governamental da plataforma Azure Mapas.

Ao usar o controle de mapa interativo, adicione a seguinte linha de código antes de criar uma instância da classeMap.

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

Certifique-se de usar os detalhes de autenticação do Azure Mapas da plataforma de nuvem do Azure Governamental ao autenticar o mapa e os serviços.

O domínio dos serviços precisa ser definido ao criar uma instância de um ponto de extremidade de URL da API. Por exemplo, o código a seguir cria uma instância da classeSearchURL e aponta o domínio para a nuvem do Azure Governamental.

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

Se acessar diretamente os serviços REST dos Azure Mapas, altere o domínio da URL para atlas.azure.us. Por exemplo, se estiver usando o serviço de API de pesquisa, altere o domínio de URL de https://atlas.microsoft.com/search/ para https://atlas.azure.us/search/.