Azure Maps 搜索 .NET

# Search (地理编码、逆地理编码)
dotnet add package Azure.Maps.Search --prerelease
Routing (路线规划、路由矩阵)
dotnet add package Azure.Maps.Routing --prerelease
Rendering (地图瓦片、静态图像)
dotnet add package Azure.Maps.Rendering --prerelease
Geolocation (IP 定位)
dotnet add package Azure.Maps.Geolocation --prerelease
Weather (天气)
dotnet add package Azure.Maps.Weather --prerelease
Resource Management (账户管理、SAS 令牌)
dotnet add package Azure.ResourceManager.Maps --prerelease
身份验证必需
dotnet add package Azure.Identity

AZURE_MAPS_SUBSCRIPTION_KEY=<your-subscription-key>
AZURE_MAPS_CLIENT_ID=<your-client-id>  # 用于 Entra ID 认证

using Azure;
using Azure.Maps.Search;
var subscriptionKey = Environment.GetEnvironmentVariable("AZURE_MAPS_SUBSCRIPTION_KEY");
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

using Azure.Identity;
using Azure.Maps.Search;
var credential = new DefaultAzureCredential();
var clientId = Environment.GetEnvironmentVariable("AZURE_MAPS_CLIENT_ID");
var client = new MapsSearchClient(credential, clientId);

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;
using Azure.Maps.Search;
// 使用 Azure Resource Manager 进行身份验证
ArmClient armClient = new ArmClient(new DefaultAzureCredential());
// 获取 Maps 账户资源
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(
    subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);
// 生成 SAS 令牌
MapsAccountSasContent sasContent = new MapsAccountSasContent(
    MapsSigningKey.PrimaryKey, 
    principalId, 
    maxRatePerSecond: 500, 
    start: DateTime.UtcNow.ToString("O"), 
    expiry: DateTime.UtcNow.AddDays(1).ToString("O"));
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);
// 使用 SAS 令牌创建客户端
var sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
var client = new MapsSearchClient(sasCredential);

Azure.Maps.Search
└── MapsSearchClient
    ├── GetGeocoding()                    → 地址地理编码
    ├── GetGeocodingBatch()               → 批量地理编码
    ├── GetReverseGeocoding()             → 坐标转地址 (逆地理编码)
    ├── GetReverseGeocodingBatch()        → 批量逆地理编码
    └── GetPolygon()

## 核心工作流

1. 地理编码 (地址转坐标)

### 2. 批量地理编码

### 3. 逆地理编码 (坐标转地址)

### 4. 获取边界多边形

### 5. 路线指引

// Redmond
};

RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
Response<RouteDirections> result = client.GetDirections(query);
foreach (var route in result.Value.Routes)
{
    Console.WriteLine($"Distance: {route.Summary.LengthInMeters} meters");
    Console.WriteLine($"Duration: {route.Summary.TravelTimeDuration}");
    
    foreach (RouteLeg leg in route.Legs)
    {
        Console.WriteLine($"Leg points: {leg.Points.Count}");
    }
}

RouteDirectionOptions options = new RouteDirectionOptions()
{
    RouteType = RouteType.Fastest,
    UseTrafficData = true,
    TravelMode = TravelMode.Bicycle,
    Language = RoutingLanguage.EnglishUsa,
    InstructionsType = RouteInstructionsType.Text,
};
RouteDirectionQuery query = new RouteDirectionQuery(routePoints)
{
    RouteDirectionOptions = options
};
Response<RouteDirections> result = client.GetDirections(query);

RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
{
    Origins = new List<GeoPosition>()
    {
        new GeoPosition(-122.34, 47.61),
        new GeoPosition(-122.13, 47.64)
    },
    Destinations = new List<GeoPosition>() 
    { 
        new GeoPosition(-122.20, 47.62),
        new GeoPosition(-122.40, 47.65)
    },
};
// 同步请求（最多 100 组路线组合）
Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);
foreach (var cell in result.Value.Matrix.SelectMany(row => row))
{
    Console.WriteLine($"Distance: {cell.Response?.RouteSummary?.LengthInMeters}");
    Console.WriteLine($"Duration: {cell.Response?.RouteSummary?.TravelTimeDuration}");
}
// 异步请求（最多 700 组路线组合）
RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery)
{
    TravelTimeType = TravelTimeType.All,
};
GetRouteMatrixOperation asyncResult = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);

RouteRangeOptions options = new RouteRangeOptions(-122.34, 47.61)
{
    TimeBudget = new TimeSpan(0, 20, 0)  // 20 分钟
};
Response<RouteRangeResult> result = client.GetRouteRange(options);
// result.Value.ReachableRange 包含多边形数据
Console.WriteLine($"Boundary points: {result.Value.ReachableRange.Boundary.Count}");

using Azure;
using Azure.Maps.Rendering;
var client = new MapsRenderingClient(new AzureKeyCredential(subscriptionKey));
int zoom = 10;
int tileSize = 256;
// 将坐标转换为瓦片索引
MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(
    new GeoPosition(13.3854, 52.517), zoom, tileSize);
// 获取地图瓦片
GetMapTileOptions options = new GetMapTileOptions(
    MapTileSetId.MicrosoftImagery,
    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
);
Response<Stream> mapTile = client.GetMapTile(options);
// 保存到文件
using (FileStream fileStream = File.Create("./MapTile.png"))
{
    mapTile.Value.CopyTo(fileStream);
}

using System.Net;
using Azure;
using Azure.Maps.Geolocation;
var client = new MapsGeolocationClient(new AzureKeyCredential(subscriptionKey));
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);
Console.WriteLine($"Country ISO Code: {result.Value.IsoCode}");

using Azure;
using Azure.Core.GeoJson;
using

## 关键类型参考

Search 包
| 类型 | 用途 |
|------|---------|
| MapsSearchClient | 搜索操作的主客户端 |
| GeocodingResponse | 地理编码结果 |
| GeocodingBatchResponse | 批量地理编码结果 |
| GeocodingQuery | 批量地理编码查询 |
| ReverseGeocodingQuery | 批量逆地理编码查询 |
| GetPolygonOptions | 多边形检索选项 |
| Boundary | 边界多边形结果 |
| BoundaryResultTypeEnum | 边界类型（Locality, AdminDistrict 等） |
| ResolutionEnum | 多边形分辨率（Small, Medium, Large） |
Routing 包
| 类型 | 用途 |
|------|---------|
| MapsRoutingClient | 路由操作的主客户端 |
| RouteDirectionQuery | 路线方向查询 |
| RouteDirectionOptions | 路线计算选项 |
| RouteDirections | 路线方向结果 |
| RouteLeg | 路线分段 |
| RouteMatrixQuery | 路由矩阵查询 |
| RouteMatrixResult | 路由矩阵结果 |
| RouteRangeOptions | 等时线选项 |
| RouteRangeResult | 等时线结果 |
| RouteType | 路线类型（Fastest, Shortest, Eco, Thrilling） |
| TravelMode | 旅行模式（Car, Truck, Bicycle, Pedestrian） |
Rendering 包
| 类型 | 用途 |
|------|---------|
| MapsRenderingClient | 渲染主客户端 |
| GetMapTileOptions | 地图瓦片选项 |
| MapTileIndex | 瓦片坐标 (X, Y, Zoom) |
| MapTileSetId | 瓦片集标识符 |
通用类型
| 类型 | 用途 |
|------|---------|
| GeoPosition | 地理位置（经度，纬度） |
| GeoBoundingBox | 地理区域的边界框 |
最佳实践
1. 生产环境使用 Entra ID — 优先于订阅密钥
2. 批量操作 — 针对多个地址使用批量地理编码
3. 缓存结果 — 地理编码结果不会频繁更改
4. 使用合适的瓦片尺寸 — 根据显示设备选择 256 或 512 像素
5. 处理速率限制 — 实现指数退避机制
6. 使用异步路由矩阵 — 适用于大规模矩阵计算（>100）
7. 考虑交通数据 — 设置 UseTrafficData = true 以获得准确的预计到达时间 (ETA)
错误处理