C# REST SDK 開發人員指南

發行項
10/16/2024

Azure 地圖服務 C# SDK 支援 Azure 地圖服務 Rest API 中可用的功能，例如搜尋地址、在不同座標之間進行路線規劃，以及取得特定 IP 位址的地理位置。本文介紹 C# REST SDK 與數個範例，以協助您使用 C# 開始建置包含 Azure 地圖服務功能的位置感知應用程式。

注意

Azure 地圖服務 C# SDK 支援與 .NET Standard 2.0 版或更新版本相容的任何 .NET 版本。若為互動式資料表，請參閱 .NET Standard 版本。

必要條件

Azure 地圖服務帳戶。
訂用帳戶金鑰或其他形式的 Azure 地圖服務驗證。
.NET Standard 2.0 版或更新版本。

提示

您可以透過程式設計方式建立 Azure 地圖服務帳戶，以下是使用 Azure CLI 的範例：

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

建立 .NET 專案

下列 PowerShell 程式碼片段示範如何使用 PowerShell 建立具有 .NET 7.0 的主控台程式 MapsDemo。您可以使用任何 .NET Standard 2.0 相容版本作為架構。

dotnet new console -lang C# -n MapsDemo -f net7.0 
cd MapsDemo

安裝必要的套件

若要使用 Azure 地圖服務 C# SDK，我們需要安裝必要的套件。每個 Azure 地圖服務，包括搜尋、路線規劃、呈現和地理位置，各自位於本身的套件中。由於 Azure 地圖服務 C# SDK 處於公開預覽狀態，因此您必須新增 --prerelease 旗標：

dotnet add package Azure.Maps.Rendering --prerelease
dotnet add package Azure.Maps.Routing --prerelease
dotnet add package Azure.Maps.Search --prerelease
dotnet add package Azure.Maps.Geolocation --prerelease

Azure 地圖服務

服務名稱	Nuget 套件	範例
Search	Azure.Maps.Search (英文)	搜尋樣本 (英文)
路由	Azure.Maps.Routing (英文)	路由樣本 (英文)
轉譯	Azure.Maps.Rendering (英文)	轉譯樣本 (英文)
地理位置	Azure.Maps.Geolocation (英文)	地理位置範例

建立及驗證 MapsSearchClient

用來存取 Azure 地圖服務搜尋 API 的用戶端物件在使用 Azure 地圖服務訂用帳戶金鑰時，需要 AzureKeyCredential 物件來進行驗證，或在使用 Microsoft Entra ID 進行驗證時，需要具有 Azure 地圖服務用戶端識別碼的 TokenCredential 物件。如需關於驗證的詳細資訊，請參閱驗證 Azure 地圖服務。

使用 Microsoft Entra 認證

您可以使用 Azure 身分識別程式庫向 Microsoft Entra ID 進行驗證。若要使用 DefaultAzureCredential 提供者，您必須安裝適用於 .NET 的 Azure 身分識別用戶端程式庫：

dotnet add package Azure.Identity

您必須註冊新的 Microsoft Entra 應用程式，並將所需的角色指派給服務主體，以授與對 Azure 地圖服務的存取權。如需詳細資訊，請參閱在非 Azure 資源上裝載精靈。系統會傳回應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼，以及用戶端密碼。複製這些值，並將其儲存在安全的地方。在下列步驟中，您會需要用到這些資料。

將應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼和 Microsoft Entra 應用程式用戶端密碼的值，以及地圖資源的用戶端識別碼的值設定為環境變數：

環境變數	描述
AZURE_CLIENT_ID	已註冊應用程式中的應用程式 (用戶端) 識別碼
AZURE_CLIENT_SECRET	已註冊應用程式中用戶端密碼的值
AZURE_TENANT_ID	已註冊應用程式中的目錄 (租用戶) 識別碼
MAPS_CLIENT_ID	Azure 地圖服務資源中的用戶端識別碼

現在您可以在 PowerShell 中建立環境變數來儲存這些值：

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

設定環境變數之後，您可以在程式中使用這些變數來具現化 AzureMapsSearch 用戶端：

using System;
using Azure.Identity; 
using Azure.Maps.Search; 

var credential = new DefaultAzureCredential(); 
var clientId = Environment.GetEnvironmentVariable("MAPS_CLIENT_ID"); 
var client = new MapsSearchClient(credential, clientId);

重要

DefaultAzureCredential() 需要使用在之前的程式碼片段中建立的其他環境變數，但在程式碼範例中未使用這些變數。如果您並未使用相同的命名慣例正確設定這些環境變數，您將會收到執行階段錯誤。例如，如果您的 AZURE_CLIENT_ID 遺失或無效，您將會收到 InvalidAuthenticationTokenTenant 錯誤。

使用訂用帳戶金鑰認證

您可以使用 Azure 地圖服務訂用帳戶金鑰進行驗證。您可以在 Azure 地圖服務帳戶的 [驗證] 區段中找到您的訂用帳戶金鑰，如下列螢幕擷取畫面所示：

現在您可以在 PowerShell 中建立環境變數來儲存這些訂用帳戶金鑰：

$Env:SUBSCRIPTION_KEY="your subscription key"

建立環境變數之後，您可以在程式碼中進行存取：

using System;
using Azure; 
using Azure.Maps.Search; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

地理編碼地址

呼叫 GetGeocoding 方法來取得地址的座標。

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

Response<GeocodingResponse> searchResult = client.GetGeocoding(
    "1 Microsoft Way, Redmond, WA 98052");

for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
    Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}

批次地理編碼地址

此範例示範如何執行批次搜尋地址。

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

List<GeocodingQuery> queries = new List<GeocodingQuery>
{
    new GeocodingQuery()
    {
        Query ="15171 NE 24th St, Redmond, WA 98052, United States"
    },
    new GeocodingQuery()
    {
        AddressLine = "400 Broad St"
    },
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);

//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
    for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
    {
        Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
    }
}

對座標進行反向地理編碼

您可以將座標轉譯成人類可讀的街道地址。此程序也稱為反向地理編碼。

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);

//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
    Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}

批次反向地理編碼一組座標

Azure 地圖服務搜尋也會提供一些批次查詢 API。反向地理編碼批次 API 只會使用單一 API 呼叫，將查詢批次傳送至反向地理編碼 API。 API 可讓呼叫端批次處理最多 100 個查詢。

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.349309, 47.620498)
    },
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.138679, 47.630356),
        ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
    },
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}

取得指定位置的多邊形

此範例示範如何搜尋多邊形。

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Options;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

GetPolygonOptions options = new GetPolygonOptions()
{
    Coordinates = new GeoPosition(-122.204141, 47.61256),
    ResultType = BoundaryResultTypeEnum.Locality,
    Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);

var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
    var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
    for (var j = 0; j < coorCount; j++)
    {
        Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
    }
}

使用 V1 SDK 進行搜尋和轉譯

如需使用搜尋 v1 的詳細資訊，請參閱適用於 .NET 的 Azure 地圖服務搜尋用戶端程式庫。如需使用轉譯 v1 的詳細資訊，請參閱適用於 .NET 的 Azure 地圖服務轉譯用戶端程式庫。

其他資訊

.NET 文件中的 Azure.Maps Namespace。

共用方式為