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

  • Artículo

Azure Maps Render es una biblioteca que puede capturar iconos de imagen e información de copyright.

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

Introducción

Instalar el paquete

Instale la biblioteca cliente para .NET con NuGet:

dotnet add package Azure.Maps.Rendering --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 MapsRenderingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRenderingClient client = new MapsRenderingClient(credential);

Autenticación de Azure AD

Para interactuar con el servicio Azure Maps, deberá crear una instancia de la MapsRenderingClient 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, las variables de entorno como se describe en el archivo Léame de identidad de Azure y crean una DefaultAzureCredential instancia que se usará con MapsRenderingClient.

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.

AzureMapsPortalSitio web de 

// Create a MapsRenderingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRenderingClient client = new MapsRenderingClient(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.Maps.Rendering;

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 MapsRenderingClient. 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);
MapsRenderingClient client = new MapsRenderingClient(sasCredential);

Conceptos clave

MapsRenderingClient está diseñado para:

  • Comunicarse con Azure Maps punto de conexión para obtener imágenes e iconos
  • Comunicarse con Azure Maps punto de conexión para obtener derechos de autor de imágenes e iconos

Más información sobre 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

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

Puede familiarizarse con diferentes API mediante nuestros ejemplos. La representación de iconos de mapa requiere conocimientos sobre los niveles de zoom y el sistema de cuadrícula de mosaicos. Consulte la documentación para obtener más información.

Obtención de iconos de imágenes

Este es un ejemplo sencillo de representación de iconos de imágenes:

int zoom = 10, tileSize = 256;

// Get tile X, Y index by coordinate, zoom and tile size information
MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(new GeoPosition(13.3854, 52.517), zoom, tileSize);

// Fetch imagery map tiles
GetMapTileOptions GetMapTileOptions = new GetMapTileOptions(
    MapTileSetId.MicrosoftImagery,
    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
);
Response<Stream> mapTile = client.GetMapTile(GetMapTileOptions);

// Prepare a file stream to save the imagery
using (FileStream fileStream = File.Create(".\\BerlinImagery.png"))
{
    mapTile.Value.CopyTo(fileStream);
}

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 intenta obtener un icono de imágenes con un índice de mosaico incorrecto, se devuelve un error, que indica "Solicitud incorrecta" (HTTP 400).

try
{
    var options = new GetMapTileOptions(
        MapTileSetId.MicrosoftBaseHybrid,
        new MapTileIndex(12, 12, 2)
    );

    Response<Stream> imageryTile = client.GetMapTile(options);
    using var imageryStream = new MemoryStream();
    imageryTile.Value.CopyTo(imageryStream);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Pasos siguientes

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