biblioteca cliente de Azure Maps Search para .NET: versión 1.0.0-beta.4

Artículo
07/20/2023

Azure Maps Search es una biblioteca que puede consultar ubicaciones, puntos de interés o buscar dentro de un área geométrica.

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.Search --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 SearchClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsSearchClient client = new MapsSearchClient(credential);

Autenticación de Azure AD

Para interactuar con el servicio Azure Maps, deberá crear una instancia de la clase MapsSearchClient. 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 TENANT_ID, y en CLIENT_SECRET la variable de entorno y llame DefaultAzureCredential() al método para obtener CLIENT_IDlas credenciales. CLIENT_IDy son el identificador y CLIENT_SECRET el secreto de la entidad de servicio que pueden acceder a Azure Maps cuenta.

También es necesario Azure Maps id. de cliente que puede obtener de Azure Maps pestaña Autenticación de > página > "Id. de cliente" en la sección Autenticación de Azure Active Directory.

// Create a MapsSearchClient that will authenticate through AAD
DefaultAzureCredential credential = new DefaultAzureCredential();
string clientId = "<My Map Account Client Id>";
MapsSearchClient client = new MapsSearchClient(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.Search;
using Azure.Maps.Search.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 MapsSearchClient. 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);
MapsSearchClient client = new MapsSearchClient(sasCredential);

Conceptos clave

MapsSearchClient está diseñado para:

Comunicarse con Azure Maps punto de conexión para consultar direcciones o puntos de ubicaciones
Comunicarse con Azure Maps punto de conexión para solicitar los datos de geometría, como una ciudad o un esquema de país para un conjunto de entidades
Comunicarse con Azure Maps punto de conexión para realizar una búsqueda de forma libre dentro de una única geometría o con muchas de ellas

Para más información, consulte nuestros 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.

Ejemplo de obtención de polígonos

// Get Addresses
Response<SearchAddressResult> searchResult = await client.SearchAddressAsync("Seattle");

// Extract geometry ids from addresses
string geometry0Id = searchResult.Value.Results[0].DataSources.Geometry.Id;
string geometry1Id = searchResult.Value.Results[1].DataSources.Geometry.Id;

// Extract position coordinates
GeoPosition positionCoordinates = searchResult.Value.Results[0].Position;

// Get polygons from geometry ids
PolygonResult polygonResponse = await client.GetPolygonsAsync(new[] { geometry0Id, geometry1Id });

// Get polygons objects
IReadOnlyList<PolygonObject> polygonList = polygonResponse.Polygons;

Ejemplo de búsqueda aproximada

Response<SearchAddressResult> fuzzySearchResponse = await client.FuzzySearchAsync("coffee", new FuzzySearchOptions
{
    Coordinates = new GeoPosition(121.56, 25.04),
    Language = SearchLanguage.EnglishUsa
});

// Print out the possible results
Console.WriteLine("The possible results for coffee shop:");
foreach (SearchAddressResultItem result in fuzzySearchResponse.Value.Results)
{
    Console.WriteLine("Coordinate: {0}, Address: {1}",
        result.Position, result.Address.FreeformAddress);
}

Ejemplo de dirección postal cruzada de búsqueda inversa

var reverseResult = await client.ReverseSearchCrossStreetAddressAsync(new ReverseSearchCrossStreetOptions
{
    Coordinates = new GeoPosition(121.0, 24.0),
    Language = SearchLanguage.EnglishUsa
});

Dirección estructurada de búsqueda de ejemplo

var address = new StructuredAddress
{
    CountryCode = "US",
    StreetNumber = "15127",
    StreetName = "NE 24th Street",
    Municipality = "Redmond",
    CountrySubdivision = "WA",
    PostalCode = "98052"
};
Response<SearchAddressResult> searchResult = await client.SearchStructuredAddressAsync(address);

SearchAddressResultItem resultItem = searchResult.Value.Results[0];
Console.WriteLine("First result - Coordinate: {0}, Address: {1}",
    resultItem.Position, resultItem.Address.FreeformAddress);

Búsqueda de ejemplo dentro de geometry

GeoPolygon sfPolygon = new GeoPolygon(new[]
{
    new GeoPosition(-122.43576049804686, 37.752415234354402),
    new GeoPosition(-122.4330139160, 37.706604725423119),
    new GeoPosition(-122.36434936523438, 37.712059855877314),
    new GeoPosition(-122.43576049804686, 37.7524152343544)
});

GeoPolygon taipeiPolygon = new GeoPolygon(new[]
{
    new GeoPosition(121.56, 25.04),
    new GeoPosition(121.565, 25.04),
    new GeoPosition(121.565, 25.045),
    new GeoPosition(121.56, 25.045),
    new GeoPosition(121.56, 25.04)
});

// Search coffee shop in Both polygons, return results in en-US
Response<SearchAddressResult> searchResponse = await client.SearchInsideGeometryAsync("coffee", new GeoCollection(new[] { sfPolygon, taipeiPolygon }), new SearchInsideGeometryOptions
{
    Language = SearchLanguage.EnglishUsa
});

// Get Taipei Cafe and San Francisco cafe and print first place
SearchAddressResultItem taipeiCafe = searchResponse.Value.Results.Where(addressItem => addressItem.SearchAddressResultType == "POI" && addressItem.Address.Municipality == "Taipei City").First();
SearchAddressResultItem sfCafe = searchResponse.Value.Results.Where(addressItem => addressItem.SearchAddressResultType == "POI" && addressItem.Address.Municipality == "San Francisco").First();

Console.WriteLine("Possible Coffee shop in the Polygons:");
Console.WriteLine("Coffee shop address in Taipei: {0}", taipeiCafe.Address.FreeformAddress);
Console.WriteLine("Coffee shop address in San Francisco: {0}", sfCafe.Address.FreeformAddress);

Dirección de búsqueda de ejemplo

Response<SearchAddressResult> searchResult = await client.SearchAddressAsync("Seattle");

SearchAddressResultItem resultItem = searchResult.Value.Results[0];
Console.WriteLine("First result - Coordinate: {0}, Address: {1}",
    resultItem.Position, resultItem.Address.FreeformAddress);

Solución de problemas

General

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

Por ejemplo, si intenta buscar con coordenadas no válidas, se devuelve un error, que indica "Solicitud incorrecta".400

Pasos siguientes

Más ejemplos

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.

Compartir a través de