通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Maps适用于 .NET 的路由客户端库 - 版本 1.0.0-beta.2

  • 项目

Azure Maps路由是一个库，可以查找指向某个位置或兴趣点的路线。

源代码 | API 参考文档 | REST API 参考文档 | 产品文档

入门

安装包

使用 NuGet 安装适用于 .NET 的客户端库：

dotnet add package Azure.Maps.Routing --prerelease

先决条件

必须具有 Azure 订阅和Azure Maps帐户。

若要创建新的Azure Maps帐户，可以使用 Azure 门户、Azure PowerShell或 Azure CLI。 下面是使用 Azure CLI 的示例：

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

验证客户端

可通过两种方式对客户端进行身份验证：共享密钥身份验证和 Azure AD。

共享密钥身份验证

  • 转到“Azure Maps帐户>身份验证”选项卡
  • 复制或在“共享密钥身份验证”部分下复制Primary Key或Secondary Key
// Create a MapsRoutingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRoutingClient client = new MapsRoutingClient(credential);

Azure AD 身份验证

若要与 Azure Maps 服务交互，需要创建 类的MapsRoutingClient实例。 使用 Azure 标识库 可以轻松添加 Azure Active Directory 支持，以便使用相应的 Azure 服务对 Azure SDK 客户端进行身份验证。

若要使用 AAD 身份验证，请根据 Azure 标识 README 中所述设置环境变量，并创建一个 DefaultAzureCredential 用于 的 MapsRoutingClient实例。

我们还需要一个Azure Maps客户端 ID，可在 Azure Active Directory 身份验证部分的“身份验证”选项卡>“客户端 ID”Azure Maps页>中找到。

AzureMapsPortal

// Create a MapsRoutingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRoutingClient client = new MapsRoutingClient(credential, clientId);

共享访问签名 (SAS) 身份验证

共享访问签名 (SAS) 令牌是使用 JSON Web 令牌 (JWT) 格式创建的身份验证令牌，通过加密签名来证明应用程序对 Azure Maps REST API 的身份验证。

在集成 SAS 令牌身份验证之前，需要安装 Azure.ResourceManager 并 Azure.ResourceManager.Maps (版本 1.1.0-beta.2 或更高版本) ：

dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease

在代码中，我们需要为 Azure Maps SDK 和 ResourceManager 导入以下行：

using Azure.Core.GeoJson;
using Azure.Maps.Routing;
using Azure.Maps.Routing.Models;

using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

然后，可以通过列出 Sas API 获取 SAS 令牌并将其 MapsRoutingClient分配给 。 在下面的代码示例中，我们提取特定的地图帐户资源，并在执行代码时创建 1 天的过期时间的 SAS 令牌。

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);

string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";

// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);

// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;

// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");

MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);

// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsRoutingClient client = new MapsRoutingClient(sasCredential);

关键概念

MapsRoutingClient 用于：

  • 与Azure Maps终结点通信以获取指向位置或兴趣点的路由
  • 与Azure Maps终结点通信，根据指定的燃料、能源、时间或距离预算计算一组可从出发点到达的位置
  • 与Azure Maps终结点通信以计算由源位置和目标位置定义的一组路由的路由摘要矩阵

通过查看示例中的示例了解详细信息

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。 这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

可以使用 我们的示例熟悉不同的 API。

在调用路由 API 之前，请先实例化 。MapsRoutingClient 此示例使用 AAD 创建客户端实例：

// Create a MapsRoutingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRoutingClient client = new MapsRoutingClient(credential, clientId);

路线方向

下面是路由到某个位置的简单示例：

// Create origin and destination routing points
List<GeoPosition> routePoints = new List<GeoPosition>()
{
    new GeoPosition(123.751, 45.9375),
    new GeoPosition(123.791, 45.96875),
    new GeoPosition(123.767, 45.90625)
};

// Create Route direction query object
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
Response<RouteDirections> result = client.GetDirections(query);

// Route direction result
Console.WriteLine($"Total {0} route results", result.Value.Routes.Count);
Console.WriteLine(result.Value.Routes[0].Summary.LengthInMeters);
Console.WriteLine(result.Value.Routes[0].Summary.TravelTimeDuration);

// Route points
foreach (RouteLeg leg in result.Value.Routes[0].Legs)
{
    Console.WriteLine("Route path:");
    foreach (GeoPosition point in leg.Points)
    {
        Console.WriteLine($"point({point.Latitude}, {point.Longitude})");
    }
}

在路由到兴趣点时，还可以指定旅行模式、路线类型、语言和其他选项：

// Create origin and destination routing points
List<GeoPosition> routePoints = new List<GeoPosition>()
{
    new GeoPosition(123.751, 45.9375),
    new GeoPosition(123.791, 45.96875),
    new GeoPosition(123.767, 45.90625)
};

RouteDirectionOptions options = new RouteDirectionOptions()
{
    RouteType = RouteType.Fastest,
    UseTrafficData = true,
    TravelMode = TravelMode.Bicycle,
    Language = RoutingLanguage.EnglishUsa,
};

// Create Route direction query object
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
Response<RouteDirections> result = client.GetDirections(query);

// Route direction result
Console.WriteLine($"Total {0} route results", result.Value.Routes.Count);
Console.WriteLine(result.Value.Routes[0].Summary.LengthInMeters);
Console.WriteLine(result.Value.Routes[0].Summary.TravelTimeDuration);

// Route points
foreach (RouteLeg leg in result.Value.Routes[0].Legs)
{
    Console.WriteLine("Route path:");
    foreach (GeoPosition point in leg.Points)
    {
        Console.WriteLine($"point({point.Latitude}, {point.Longitude})");
    }
}

有关更详细的示例，请参阅 路线方向示例 页。

路线矩阵

若要查找多个起点和目标之间的路由矩阵，Azure Maps路由矩阵 API 应满足你的需求。 简单的路由矩阵请求示例如下所示：

// A simple route matrix request
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
{
    // two origin points
    Origins = new List<GeoPosition>()
    {
        new GeoPosition(123.751, 45.9375),
        new GeoPosition(123.791, 45.96875)
    },
    // one destination point
    Destinations = new List<GeoPosition>() { new GeoPosition(123.767, 45.90625) },
};
Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);

异步路由矩阵请求如下所示。 这在拥有 origin * destination > 100 数据点时很有用。

// Instantiate route matrix query
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
{
    // two origin points
    Origins = new List<GeoPosition>()
    {
        new GeoPosition(123.751, 45.9375),
        new GeoPosition(123.791, 45.96875)
    },
    // one destination point
    Destinations = new List<GeoPosition>() { new GeoPosition(123.767, 45.90625) },
};

// Instantiate route matrix options
RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery)
{
    TravelTimeType = TravelTimeType.All,
};

// Invoke an long-running operation route matrix request and directly wait for completion
GetRouteMatrixOperation result = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);

有关更详细的示例，请参阅 路由矩阵示例 页。

路线范围

路线范围 API 有助于根据指定的燃料、能源、时间或距离预算查找可从起点到达的一组位置。 逆时针方向返回多边形边界 (或等时线) ，以及原点结果的精确多边形中心。

// Search from a point of time budget that can be reached in 2000 seconds
RouteRangeOptions options = new RouteRangeOptions(123.75, 46)
{
    TimeBudget = new TimeSpan(0, 20, 0)
};
Response<RouteRangeResult> result = client.GetRouteRange(options);

有关更详细的示例，请参阅 路由范围示例 页。

疑难解答

常规

与Azure Maps服务交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果传递了错误的路由点，则会返回错误，指示“错误请求” (HTTP 400) 。

try
{
    // An empty route points list
    List<GeoPosition> routePoints = new List<GeoPosition>() { };
    RouteDirectionQuery query = new RouteDirectionQuery(routePoints);

    Response<RouteDirections> result = client.GetDirections(query);
    // Do something with result ...
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

后续步骤

  • 有关更多上下文和其他方案，请参阅： 详细示例

供稿

有关构建、测试和参与此库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 <cla.microsoft.com>。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

曝光数