Korzystanie z modułu usług Azure Maps

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

Uwaga / Notatka

Wycofanie modułu usługi Web SDK Azure Maps

Moduł usługi Web SDK usługi Azure Maps 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 usługi Azure Maps 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ł usług Azure Maps. 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 usług Azure Maps. 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 Azure Maps Web SDK lokalnie przy użyciu pakietu npm azure-maps-rest, a następnie hostuj go z Twoją 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. Zanim będzie można zainicjować punkt końcowy klienta adresu URL usługi, należy utworzyć pipeline. Użyj własnego klucza konta usługi Azure Maps lub poświadczeń usługi Microsoft Entra, aby uwierzytelnić klienta usługi Azure Maps Search. W tym przykładzie jest tworzony klient adresu URL usługi 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 Maps (Uwierzytelnianie za pomocą usługi Azure Maps).

Poniższy kod używa nowo utworzonego klienta adresu URL usługi Azure Maps Search 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.

Wsparcie dla chmury Azure Government

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

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 użyć szczegółów uwierzytelniania usługi Azure Maps z platformy w chmurze Azure Government podczas uwierzytelniania mapy i usług.

Domena dla usług musi zostać ustawiona podczas tworzenia końcówki adresu URL 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 uzyskujesz bezpośredni dostęp do usług REST usługi Azure Maps, 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/.

Dalsze kroki

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

MapsURL

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-04-21