Guía para desarrolladores de SDK de REST en C#
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.
- 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"
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
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
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 |
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.
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
.
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);
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));
}
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));
}
}
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);
}
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);
}
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]));
}
}
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.
Espacio de nombres Azure.Maps en la documentación de .NET.