Azure Mapas biblioteca de clientes de roteamento para .NET – versão 1.0.0-beta.2

Artigo
07/20/2023

Azure Mapas Roteamento é uma biblioteca que pode encontrar uma rota para um local ou pontos de interesse.

Código-fonte | Documentação | de referência da APIDocumentação | de referência da API REST Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes para .NET com o NuGet:

dotnet add package Azure.Maps.Routing --prerelease

Pré-requisitos

Você deve ter uma assinatura do Azure e uma conta Azure Mapas.

Para criar uma nova conta Azure Mapas, você pode usar o Portal do Azure, Azure PowerShell ou a CLI do Azure. Aqui, está um exemplo usando a CLI do Azure:

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

Autenticar o cliente

Há duas maneiras de autenticar o cliente: autenticação de chave compartilhada e Azure AD.

Autenticação de Chave Compartilhada

Vá para Azure Mapas guia Autenticação de conta >
Copiar Primary Key ou Secondary Key na seção Autenticação de Chave Compartilhada

// Create a MapsRoutingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRoutingClient client = new MapsRoutingClient(credential);

Autenticação do Azure AD

Para interagir com o serviço Azure Mapas, você precisará criar uma instância da MapsRoutingClient classe . A biblioteca de Identidade do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com seus serviços correspondentes do Azure.

Para usar a autenticação do AAD, defina as variáveis de ambiente conforme descrito no README de Identidade do Azure e crie uma DefaultAzureCredential instância para usar com o MapsRoutingClient.

Também precisamos de uma ID do cliente Azure Mapas que possa ser encontrada na página > Azure Mapas guia > Autenticação "ID do cliente" na seção Autenticação do Azure Active Directory.

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

Autenticação SAS (Assinatura de Acesso Compartilhado)

Os tokens de SAS (assinatura de acesso compartilhado) são tokens de autenticação criados usando o formato JWT (token Web JSON) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Mapas.

Antes de integrar a autenticação de token SAS, precisamos instalar Azure.ResourceManager e Azure.ResourceManager.Maps (versão 1.1.0-beta.2 ou superior):

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

No código, precisamos importar as seguintes linhas para Azure Mapas SDK e 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;

Em seguida, podemos obter o token SAS por meio da API Sas de Lista e atribuí-lo a MapsRoutingClient. No exemplo de código a seguir, buscamos um recurso de conta de mapas específico e criamos um token SAS por um dia de expiração quando o código é executado.

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

Principais conceitos

O MapsRoutingClient foi projetado para:

Comunicar-se com Azure Mapas ponto de extremidade para obter rota para locais ou ponto de interesse
Comunique-se com Azure Mapas ponto de extremidade para calcular um conjunto de locais que podem ser alcançados do ponto de origem com base no orçamento de combustível, energia, tempo ou distância especificado
Comunique-se com Azure Mapas ponto de extremidade para calcular uma matriz de resumos de rotas para um conjunto de rotas definido por locais de origem e destino

Saiba mais exibindo nossos exemplos em exemplos

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

Você pode se familiarizar com APIs diferentes usando nossos Exemplos.

Antes de chamar APIs de rota, instancie uma MapsRoutingClient primeira. Este exemplo usa o AAD para criar a instância do cliente:

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

Trajeto da Rota

Aqui está um exemplo simples de roteamento para um local:

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

Você também pode especificar o modo de viagem, o tipo de rota, o idioma e outras opções ao rotear para o ponto de interesse:

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

Para obter exemplos mais detalhados, consulte a página de exemplos de direção de rota .

Matrix de Rota

Para localizar a matriz de rotas entre várias origens e destinos, Azure Mapas APIs de matriz de rotas devem corresponder às suas necessidades. Um exemplo de solicitação de matriz de rota simples se parece com o snippet abaixo:

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

Uma solicitação de matriz de rota assíncrona é semelhante a abaixo. Isso é útil quando você tem origin * destination > 100 pontos de dados.

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

Para obter exemplos mais detalhados, consulte a página de exemplos de matriz de rotas .

Intervalo de rotas

A API de intervalo de rotas ajuda a encontrar um conjunto de locais que podem ser alcançados a partir do ponto de origem com base no orçamento de combustível, energia, tempo ou distância especificado. Um limite de polígono (ou Isócrono) é retornado em uma orientação no sentido anti-horário, bem como no centro de polígono preciso que foi o resultado do ponto de origem.

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

Para obter exemplos mais detalhados, consulte a página de exemplos do intervalo de rotas .

Solução de problemas

Geral

Quando você interage com os serviços de Azure Mapas, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST.

Por exemplo, se você passar pontos de roteamento errados, um erro será retornado, indicando "Solicitação Incorreta" (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());
}

Próximas etapas

Para obter mais contexto e cenários adicionais, consulte: exemplos detalhados

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite <cla.microsoft.com>.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via