Usar o controle de mapeamento do Azure Mapas

A biblioteca Javascript do lado do cliente do Controle de Mapeamento permite renderizar mapas e funcionalidade inserida nos Azure Mapas em seu aplicativo Web ou móvel.

Esta documentação usa o SDK da Web dos Azure Mapas, no entanto, os serviços dos Azure Mapas podem ser usados com qualquer controle de mapa. Aqui estão alguns controles de mapa de software livre populares para os quais a equipe do Azure Mapas criou plug-ins.

Pré-requisitos

Para usar o Controle de Mapeamento em uma página da Web, você deve ter um dos seguintes pré-requisitos:

Criar um novo mapa em uma página da web

Você pode inserir um mapa em uma página da Web usando a biblioteca JavaScript do lado do cliente do Controle de Mapeamento.

  1. Criar um novo arquivo HTML.

  2. Carregar no SDK Web do Azure Mapas. Escolha uma das duas opções:

    • Use a versão CDN hospedada globalmente do SDK da Web dos Azure Mapas adicionando referências ao JavaScript e à folha de estilos no elemento <head> do arquivo HTML:

      <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css">
      <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.js"></script>
      
    • Carregue o código-fonte do SDK da Web dos Azure Mapas localmente usando o pacote NPM azure-maps-control e hospede-o no aplicativo. Esse pacote também inclui definições de TypeScript.

      npm install azure-maps-control

    Em seguida, adicione referências à folha de estilos dos Azure Mapas ao elemento <head> do arquivo:

    <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css" />
    

    Observação

    As definições do typescript podem ser importadas para o aplicativo adicionando o seguinte código:

    import * as atlas from 'azure-maps-control';
    
  3. Para renderizar o mapa de modo que ele preencha a página inteira, adicione o seguinte elemento <style> ao elemento <head>.

     <style>
         html, body {
             margin: 0;
         }
    
         #myMap {
             height: 100vh;
             width: 100vw;
         }
     </style>
    
  4. No corpo da página, adicione um elemento <div> e dê a ele um id de myMap.

     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
    
  5. Agora, inicializaremos o controle de mapa. Para autenticar o controle, você precisará ter uma chave de assinatura dos Azure Mapas ou usar as credenciais do Azure Active Directory (AAD) com opções de autenticação.

    Se você estiver usando uma chave de assinatura para autenticação, copie e cole o seguinte elemento de script dentro do elemento <head> e abaixo do primeiro elemento <script>. Substitua <Your Azure Maps Key> pela sua chave de assinatura primária dos Azure Mapas.

    <script type="text/javascript">
       function InitMap()
       {
           var map = new atlas.Map('myMap', {
               center: [-122.33, 47.6],
               zoom: 12,
               language: 'en-US',
               authOptions: {
                   authType: 'subscriptionKey',
                   subscriptionKey: '<Your Azure Maps Key>'
               }
           });
      }
    </script>
    

    Se você estiver usando o Azure Active Directory (AAD) para autenticação, copie e cole o seguinte elemento de script dentro do elemento <head> e abaixo do primeiro elemento <script>.

    <script type="text/javascript">
      function InitMap()
      {
          var map = new atlas.Map('myMap', {
              center: [-122.33, 47.6],
              zoom: 12,
              language: 'en-US',
              authOptions: {
                  authType: 'aad',
                  clientId: '<Your AAD Client Id>',
                  aadAppId: '<Your AAD App Id>',
                  aadTenant: '<Your AAD Tenant Id>'
              }
          });
      }
    </script>
    

    Para obter mais informações sobre a autenticação com os Azure Mapas, veja o documento Autenticação com os Azure Mapas. Além disso, uma lista de exemplos que mostram como integrar o Azure Active Directory (AAD) com os Azure Mapas pode ser encontrada aqui.

    Dica

    Neste exemplo, passamos o id do mapa <div>. Outra maneira de fazer isso é passar o objeto HTMLElement passando document.getElementById('myMap') como o primeiro parâmetro.

  6. Opcionalmente, talvez seja útil adicionar os seguintes elementos meta ao elemento head da página:

     <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
     <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
     <!-- Ensures the web page looks good on all screen sizes. -->
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
  7. Ao final, o arquivo HTML deve ser parecido com a seguinte marcação:

     <!DOCTYPE html>
     <html>
     <head>
         <title></title>
    
         <meta charset="utf-8">
    
         <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
         <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
         <!-- Ensures the web page looks good on all screen sizes. -->
         <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
         <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
         <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css">
         <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.js"></script>
    
    
         <script type="text/javascript">
             //Create an instance of the map control and set some options.
             function InitMap()
             {
                 var map = new atlas.Map('myMap', {
                     center: [-122.33, 47.6],
                     zoom: 12,
                     language: 'en-US',
                     authOptions: {
                         authType: 'subscriptionKey',
                         subscriptionKey: '<Your Azure Maps Key>'
                     }
                 });
             }
         </script>
    
         <style>
             html, body {
                 margin: 0;
             }
    
             #myMap {
                 height: 100vh;
                 width: 100vw;
             }
         </style>
     </head>
     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
     </html>
    
  8. Abra o arquivo no seu navegador da Web e exiba o mapa renderizado. Ele deverá ter a aparência mostrada na imagem abaixo:

    Imagem do mapa mostrando resultado renderizado

<a name="localizing-the-map">Como localizar o mapa

Os Azure Mapas fornecem duas maneiras diferentes de definir o idioma e a exibição regional do mapa renderizado. A primeira opção é adicionar essas informações ao namespace atlas global, o que fará com que todas as instâncias de controle de mapa no aplicativo usem essas configurações como padrão. O seguinte define o idioma como francês ("fr-FR") e a exibição regional como "Automática":

atlas.setLanguage('fr-FR');
atlas.setView('Auto');

A segunda opção é passar essas informações para as opções do mapa ao carregar o mapa desta forma:

map = new atlas.Map('myMap', {
    language: 'fr-FR',
    view: 'Auto',

    authOptions: {
        authType: 'aad',
        clientId: '<Your AAD Client Id>',
        aadAppId: '<Your AAD App Id>',
        aadTenant: '<Your AAD Tenant Id>'
    }
});

Observação

É possível carregar várias instâncias de mapa na mesma página com diferentes configurações de idioma e região. Além disso, essas configurações podem ser atualizadas depois que o mapa é carregado usando a função setStyle do mapa.

Veja a seguir um exemplo dos Azure Mapas com o idioma definido como “fr-FR” e a exibição regional definida como “Automática”.

Imagem do mapa mostrando rótulos em francês

Uma lista completa de idiomas e exibições regionais compatíveis está documentada aqui.

Suporte da nuvem do Azure Governamental

O SDK da Web dos Azure Mapas dá suporte à nuvem do Azure Governamental. Todas as URLs de JavaScript e CSS usadas para acessar o SDK da Web dos Azure Mapas permanecem as mesmas. As tarefas a seguir precisarão ser realizadas para se conectar à versão de nuvem do Azure Governamental da plataforma dos 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');

Use os detalhes de autenticação dos Azure Mapas da plataforma de nuvem do Azure Governamental ao autenticar o mapa e os serviços.

Ao usar o módulo de serviços, o domínio para os serviços precisa ser definido ao criar uma instância de um ponto de extremidade de URL de 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/.

Estruturas do JavaScript

Se você estiver desenvolvendo com uma estrutura JavaScript, um dos seguintes projetos open-source pode ser útil:

Próximas etapas

Saiba como criar e interagir com um mapa:

Saiba como definir o estilo de um mapa:

Conheça as melhores práticas e veja exemplos:

Para obter uma lista de exemplos que mostram como integrar o Azure Active Directory (AAD) aos Azure Mapas, veja: