Korzystanie z modułu usług Azure Mapy

Artykuł
04/07/2024

Zestaw Azure Mapy Web SDK udostępnia moduł usług. Ten moduł jest biblioteką pomocnika, która ułatwia korzystanie z usług REST platformy Azure Mapy w sieci Web lub Node.js przy użyciu języka JavaScript lub TypeScript.

Uwaga

Wycofanie modułu usługi azure Mapy Web SDK

Moduł usługi azure Mapy Web SDK jest teraz przestarzały i zostanie wycofany w dniu 30.09.26. Aby uniknąć przerw w działaniu usługi, zalecamy migrację do zestawu SDK REST języka JavaScript platformy Azure Mapy do 30.09.26. Aby uzyskać więcej informacji, zobacz JavaScript/TypeScript REST SDK Developers Guide (wersja zapoznawcza).

Korzystanie z modułu usług na stronie internetowej

Utwórz nowy plik HTML.
Załaduj moduł azure Mapy services. Można go załadować na jeden z dwóch sposobów:
- Użyj globalnie hostowanej wersji usługi Azure Content Delivery Network modułu Azure Mapy Services. Dodaj odwołanie do skryptu do <head> elementu pliku:
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- Alternatywnie załaduj moduł usług dla kodu źródłowego zestawu WEB SDK platformy Azure Mapy lokalnie przy użyciu pakietu npm azure-maps-rest, a następnie hostuj go z aplikacją. Ten pakiet zawiera również definicje języka TypeScript. Użyj następującego polecenia:
  
  npm install azure-maps-rest
  
  Następnie użyj deklaracji importu, aby dodać moduł do pliku źródłowego:
```
import * as service from "azure-maps-rest";
```

Utwórz potok uwierzytelniania. Przed zainicjowaniem punktu końcowego klienta adresu URL usługi należy utworzyć potok. Użyj własnego klucza konta usługi Azure Mapy lub poświadczeń usługi Microsoft Entra, aby uwierzytelnić klienta usługi Azure Mapy usługa wyszukiwania. W tym przykładzie jest tworzony klient adresu URL usługa wyszukiwania.

Jeśli używasz klucza subskrypcji do uwierzytelniania:

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

Jeśli używasz identyfikatora Entra firmy Microsoft do uwierzytelniania:

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

Aby uzyskać więcej informacji, zobacz Authentication with Azure Mapy (Uwierzytelnianie przy użyciu usługi Azure Mapy).

Poniższy kod używa nowo utworzonego klienta adresu URL usługi Azure Mapy usługa wyszukiwania do geokodowania adresu: "1 Microsoft Way, Redmond, WA". Kod używa searchAddress funkcji i wyświetla wyniki jako tabelę w treści strony.

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

Oto pełna, uruchomiona próbka kodu:

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

Na poniższej ilustracji przedstawiono zrzut ekranu przedstawiający wyniki tego przykładowego kodu, tabelę z wyszukiwanym adresem wraz ze współrzędnymi wynikowymi.

Zrzut ekranu przedstawiający tabelę HTML z przeszukanymi adresami i wynikowymi współrzędnymi.

Obsługa chmury platformy Azure Government

Zestaw Azure Mapy Web SDK obsługuje chmurę Azure Government. Wszystkie adresy URL języka JavaScript i CSS używane do uzyskiwania dostępu do zestawu Azure Mapy Web SDK pozostają takie same, jednak należy wykonać następujące zadania w celu nawiązania połączenia z wersją chmury azure government platformy Azure Mapy.

W przypadku korzystania z interaktywnej kontrolki mapy dodaj następujący wiersz kodu przed utworzeniem wystąpienia Map klasy.

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

Pamiętaj, aby podczas uwierzytelniania mapy i usług używać szczegółów uwierzytelniania usługi Azure Mapy z platformy w chmurze Azure Government.

Domena usług należy ustawić podczas tworzenia wystąpienia punktu końcowego adresu URL interfejsu API. Na przykład poniższy kod tworzy wystąpienie SearchURL klasy i wskazuje domenę w chmurze Azure Government.

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

Jeśli bezpośredni dostęp do usług REST usługi Azure Mapy, zmień domenę adresu URL na atlas.azure.us. Na przykład w przypadku korzystania z usługi interfejsu API wyszukiwania zmień domenę adresu URL z https://atlas.microsoft.com/search/ na https://atlas.azure.us/search/.

Następne kroki

Dowiedz się więcej o klasach i metodach używanych w tym artykule:

Mapy URL

SearchURL

Routeurl

SubscriptionKeyCredential

TokenCredential

Aby uzyskać więcej przykładów kodu korzystających z modułu usług, zobacz następujące artykuły:

Pokaż wyniki wyszukiwania na mapie

Pobieranie informacji ze współrzędnych

Pokaż wskazówki od A do B

Korzystanie z modułu usług Azure Mapy

Korzystanie z modułu usług na stronie internetowej

Obsługa chmury platformy Azure Government

Następne kroki

Dodatkowe zasoby