使用 Azure 地圖服務服務模組

發行項
04/07/2024

Azure 地圖服務 Web SDK 提供服務模組。本課程模組是協助程序連結庫，可讓您使用 JavaScript 或 TypeScript，輕鬆地在 Web 或Node.js應用程式中使用 Azure 地圖服務 REST 服務。

注意

Azure 地圖服務 Web SDK 服務模組淘汰

Azure 地圖服務 Web SDK 服務模組現已淘汰，將於 9/30/26 淘汰。若要避免服務中斷，建議您以 9/30/26 移轉至 Azure 地圖服務 JavaScript REST SDK。如需詳細資訊，請參閱 JavaScript/TypeScript REST SDK 開發人員指南（預覽版）。

在網頁中使用服務模組

建立新的 HTML 檔案。
載入 Azure 地圖服務服務模組。您可以透過下列兩種方式之一載入它：
- 使用全域裝載的 Azure 內容傳遞網路版 Azure 地圖服務模組。將文稿參考新增至 <head> 檔案的元素：
```
<script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
```
- 或者，使用 azure-maps-rest npm 套件，在本機載入 Azure 地圖服務 Web SDK 原始程式碼的服務模組，然後將它裝載於您的應用程式。此套件也包含 TypeScript 定義。使用此命令：
  
  npm install azure-maps-rest
  
  然後，使用匯入宣告，將模組新增至來源檔案：
```
import * as service from "azure-maps-rest";
```

建立驗證管線。您必須先建立管線，才能初始化服務 URL 用戶端端點。使用您自己的 Azure 地圖服務帳戶密鑰或 Microsoft Entra 認證來驗證 Azure 地圖服務搜尋服務用戶端。在此範例中，會建立搜尋服務 URL 用戶端。

如果您使用訂用帳戶金鑰進行驗證：

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

如果您使用 Microsoft Entra ID 進行驗證：

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

如需詳細資訊，請參閱使用 Azure 地圖服務進行驗證。

下列程式代碼會使用新建立的 Azure 地圖服務搜尋服務 URL 用戶端來地理編碼位址：「1 Microsoft Way，Redmond， WA」。程序代碼會使用函式， searchAddress 並將結果顯示為頁面主體中的數據表。

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

以下是完整的執行程式碼範例：

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

下圖是螢幕快照，其中顯示此範例程式代碼的結果、搜尋地址的數據表，以及產生的座標。

HTML 數據表的螢幕快照，其中顯示搜尋的位址和產生的座標。

Azure Government 雲端支援

Azure 地圖服務 Web SDK 支援 Azure Government 雲端。所有用來存取 Azure 地圖服務 Web SDK 的 JavaScript 和 CSS URL 都保持不變，不過必須執行下列工作，才能連線到 Azure 地圖服務平臺的 Azure Government 雲端版本。

使用互動式地圖控件時，請先新增下列程式代碼行，再建立類別的 Map 實例。

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

驗證地圖和服務時，請務必從 Azure Government 雲端平臺使用 Azure 地圖服務驗證詳細數據。

建立 API URL 端點的實例時，必須設定服務的網域。例如，下列程式代碼會建立類別的 SearchURL 實例，並將網域指向 Azure Government 雲端。

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

如果直接存取 Azure 地圖服務 REST 服務，請將網址變更為 atlas.azure.us。例如，如果使用搜尋 API 服務，請將網址從 https://atlas.microsoft.com/search/ 變更為 https://atlas.azure.us/search/。

下一步

深入了解本文使用的類別和方法：

地圖 URL

SearchURL

RouteURL

SubscriptionKeyCredential

TokenCredential

如需使用服務模組的更多程式碼範例，請參閱下列文章：

在地圖上顯示搜尋結果

從座標取得資訊

顯示從甲地到乙地的指示

共用方式為

使用 Azure 地圖服務服務模組

在網頁中使用服務模組

Azure Government 雲端支援

下一步

意見反應

其他資源

共用方式為

使用 Azure 地圖服務 服務模組

在網頁中使用服務模組

Azure Government 雲端支援

下一步

意見反應

其他資源

使用 Azure 地圖服務服務模組