Azure Maps biblioteca cliente de enrutamiento para .NET: versión 1.0.0-beta.2

Artículo
07/20/2023

Azure Maps Enrutamiento es una biblioteca que puede encontrar la ruta a una ubicación o a puntos de interés.

Código | fuenteDocumentación | de referencia de APIDocumentación | de referencia de la API REST Documentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente para .NET con NuGet:

dotnet add package Azure.Maps.Routing --prerelease

Requisitos previos

Debe tener una suscripción de Azure y una cuenta de Azure Maps.

Para crear una nueva cuenta de Azure Maps, puede usar Azure Portal, Azure PowerShell o la CLI de Azure. A continuación se facilita un ejemplo mediante el uso de la CLI de Azure:

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

Autenticar el cliente

Hay dos maneras de autenticar el cliente: autenticación de clave compartida y Azure AD.

Autenticación de clave compartida

Vaya a Azure Maps pestaña Autenticación de cuenta>.
Copia Primary Key o Secondary Key en la sección Autenticación de clave compartida

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

Autenticación de Azure AD

Para interactuar con el servicio Azure Maps, deberá crear una instancia de la MapsRoutingClient clase . La biblioteca de identidades de Azure facilita la incorporación de compatibilidad con Azure Active Directory para autenticar clientes del SDK de Azure con sus servicios de Azure correspondientes.

Para usar la autenticación de AAD, establezca las variables de entorno como se describe en el archivo Léame de identidad de Azure y cree una DefaultAzureCredential instancia para usarla con MapsRoutingClient.

También necesitamos un identificador de cliente Azure Maps que se puede encontrar en la pestaña Autenticación de Azure Maps página >> "Id. de cliente" en la sección Autenticación de 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);

Autenticación de firma de acceso compartido (SAS)

Los tokens de firma de acceso compartido (SAS) son tokens de autenticación creados con el formato JSON Web Token (JWT) y están firmados criptográficamente para demostrar la autenticación de una aplicación en la API de REST de Azure Maps.

Antes de integrar la autenticación de tokens de SAS, es necesario instalar Azure.ResourceManager y Azure.ResourceManager.Maps (versión 1.1.0-beta.2 o superior):

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

En el código, es necesario importar las líneas siguientes para Azure Maps SDK y 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;

Y, a continuación, podemos obtener el token de SAS a través de list Sas API y asignarlo a MapsRoutingClient. En el ejemplo de código siguiente, capturamos un recurso de cuenta de mapas específico y creamos un token de SAS durante un día de expiración cuando se ejecuta el código.

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

Conceptos clave

MapsRoutingClient está diseñado para:

Comunicarse con Azure Maps punto de conexión para obtener rutas a ubicaciones o puntos de interés
Comunicarse con Azure Maps punto de conexión para calcular un conjunto de ubicaciones a las que se puede acceder desde el punto de origen en función del presupuesto de combustible, energía, tiempo o distancia especificado
Comunicarse con Azure Maps punto de conexión para calcular una matriz de resúmenes de ruta para un conjunto de rutas definidas por ubicaciones de origen y destino

Para más información, consulte nuestros ejemplos en ejemplos.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

Puede familiarizarse con diferentes API mediante nuestros ejemplos.

Antes de llamar a las API de ruta, cree una MapsRoutingClient instancia en primer lugar. En este ejemplo se usa AAD para crear la instancia de 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);

Indicaciones de ruta

Este es un ejemplo sencillo de enrutamiento a una ubicación:

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

También puede especificar el modo de desplazamiento, el tipo de ruta, el idioma y otras opciones cuando se enruta a un punto de interés:

// 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 obtener ejemplos más detallados, consulte la página de ejemplos de dirección de ruta .

Matriz de ruta

Para encontrar la matriz de rutas entre varios orígenes y destinos, Azure Maps API de matriz de rutas debe satisfacer sus necesidades. Un ejemplo de solicitud de matriz de ruta simple es similar al fragmento de código siguiente:

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

Una solicitud de matriz de rutas asincrónica es similar a la siguiente. Esto resulta útil cuando tiene origin * destination > 100 puntos de datos.

// 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 obtener ejemplos más detallados, consulte la página de ejemplos de matriz de rutas .

Rango de rutas

La API de intervalo de rutas ayuda a encontrar un conjunto de ubicaciones a las que se puede acceder desde el punto de origen en función del combustible, la energía, el tiempo o el presupuesto de distancia especificados. Se devuelve un límite de polígono (o Isochrone) en una orientación en sentido contrario a las agujas del reloj, así como el centro de polígono preciso que era el resultado del punto de origen.

// 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 obtener ejemplos más detallados, consulte la página de ejemplos del intervalo de rutas .

Solución de problemas

General

Al interactuar con los servicios de Azure Maps, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST.

Por ejemplo, si pasa puntos de enrutamiento incorrectos, se devuelve un error, que indica "Solicitud incorrecta" (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());
}

Pasos siguientes

Para obtener más contexto y escenarios adicionales, consulte: ejemplos detallados.

Contribuciones

Consulte la CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite <cla.microsoft.com>.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de