Guía para desarrolladores de SDK de REST en C#

Artículo
11/06/2024

El SDK de Azure Maps en C# admite toda la funcionalidad disponible en la API REST de Azure Maps, como buscar una dirección, enrutar entre diferentes coordenadas y obtener la ubicación geográfica de una dirección IP específica. En este artículo se presenta el SDK de REST de C# con ejemplos que le ayudarán a empezar a crear aplicaciones compatibles con la ubicación en C# que incorporan la eficacia de Azure Maps.

Nota:

El SDK de Azure Maps en C# admite cualquier versión de .NET compatible con la versión .NET Standard 2.0 o superior. Para ver una tabla interactiva, consulte Versiones de .NET Standard.

Requisitos previos

Una cuenta de Azure Maps.
Una clave de suscripción u otra forma de Autenticación con Azure Maps.
.NET Standard, versión 2.0 o posterior.

Sugerencia

Puede crear una cuenta de Azure Maps mediante programación. A continuación se muestra un ejemplo mediante la CLI de Azure:

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

Creación de un proyecto de .NET

El fragmento de código de PowerShell siguiente muestra cómo usar PowerShell para crear un programa de consola MapsDemo con .NET 7.0. Puede usar cualquier versión compatible con .NET Standard 2.0 como marco de trabajo.

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

Instalación de los paquetes requeridos

Para usar el SDK de Azure Maps en C#, es necesario instalar los paquetes requeridos. Cada uno de los servicios Azure Maps, como la búsqueda, el enrutamiento, la representación y la geolocalización, se encuentran en su propio paquete. Dado que el SDK de Azure Maps en C# está en versión preliminar pública, debe agregar la marca --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

Servicios de Azure Maps

Nombre del servicio	Paquete de NuGet	Ejemplos
Búsqueda	Azure.Maps.Search	ejemplos de búsqueda
Enrutamiento	Azure.Maps.Routing	ejemplos de enrutamiento
Representación	Azure.Maps.Rendering	ejemplo de representación
Geolocalización	Azure.Maps.Geolocation	ejemplo de geolocalización

Creación y autenticación de un objeto MapsSearchClient

El objeto de cliente que se usa para acceder a las API de búsqueda de Azure Maps requiere que un objeto AzureKeyCredential se autentique al usar una clave de suscripción de Azure Maps o un objeto TokenCredential con el identificador de cliente de Azure Maps al autenticarse mediante Microsoft Entra ID. Para obtener más información sobre la autenticación, consulte Autenticación con Azure Maps.

Uso de la credencial de Microsoft Entra

Puede autenticarse con Microsoft Entra ID mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential, debe instalar la biblioteca cliente de Azure Identity para .NET:

dotnet add package Azure.Identity

Debe registrar la nueva aplicación de Microsoft Entra y conceder acceso a Azure Maps mediante la asignación del rol necesario a la entidad de servicio. Para más información, consulte Hospedaje de un demonio en recursos que no son de Azure. Se devuelve el id. de aplicación (cliente), un id. de directorio (inquilino) y un secreto de cliente. Copie estos valores y guárdelos en lugar seguro. Los necesitará en los pasos siguientes.

Establezca los valores del identificador de aplicación (cliente), el identificador de directorio (inquilino) y el secreto de cliente de la aplicación de Microsoft Entra, así como el identificador de cliente del recurso de asignación, como variables de entorno:

Variable de entorno	Descripción
AZURE_CLIENT_ID	Identificador de aplicación (cliente) de la aplicación registrada
AZURE_CLIENT_SECRET	Valor del secreto de cliente de la aplicación registrada
AZURE_TENANT_ID	Identificador de directorio (inquilino) de la aplicación registrada
MAPS_CLIENT_ID	Identificador de cliente del recurso de Azure Maps

Ahora puede crear variables de entorno en PowerShell para almacenar estos valores:

$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"

Después de configurar las variables de entorno, puede usarlas en el programa para crear instancias del cliente 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);

Importante

Las demás variables de entorno creadas en el fragmento de código anterior, aunque no se usan en el ejemplo de código, son necesarias para DefaultAzureCredential(). Si no establece correctamente estas variables de entorno, con las mismas convenciones de nomenclatura, obtendrá errores en tiempo de ejecución. Por ejemplo, si AZURE_CLIENT_ID falta o no es válido, obtendrá un error InvalidAuthenticationTokenTenant.

Uso de una credencial de clave de suscripción

Puede autenticarse con la clave de suscripción de Azure Maps. Encontrará la clave de suscripción en la sección Autenticación de la cuenta de Azure Maps, como se muestra en la captura de pantalla siguiente:

Ahora puede crear variables de entorno en PowerShell para almacenar la clave de suscripción:

$Env:SUBSCRIPTION_KEY="your subscription key"

Una vez que se haya creado la variable de entorno, puede acceder a ella en el código:

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

Geocodificación de una dirección

Llame al método GetGeocoding para obtener las coordenadas de una dirección.

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

Direcciones de geocodificación por lotes

En este ejemplo, se muestra cómo realizar la búsqueda por lotes de direcciones.

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

Geocodificación inversa de una coordenada

Puede traducir las coordenadas en direcciones legibles para cualquier persona. Este proceso también se denomina geocodificación inversa.

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

Geocodificación inversa por lotes de un conjunto de coordenadas

La búsqueda de Azure Maps también proporciona algunas API de consulta por lotes. La API Reverse Geocoding Batch envía lotes de consultas a la API Reverse Geocoding mediante una sola llamada API. La API permite al autor de llamada procesar por lotes hasta 100 consultas.

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

Obtención de polígonos para una ubicación determinada

En este ejemplo se muestra cómo buscar polígonos.

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

Uso de SDK V1 para Búsqueda y Representar

Para más información sobre el uso de Search v1, consulte Biblioteca cliente de Search de Azure Maps para .NET. Para más información sobre el uso de Render v1, consulte Biblioteca cliente de Render de Azure Maps para .NET.

Información adicional

Espacio de nombres Azure.Maps en la documentación de .NET.

Compartir a través de