Azure Maps Renderclientbibliothek für .NET– Version 1.0.0-beta.2

Azure Maps Rendern ist eine Bibliothek, die Bildkacheln und Copyrightinformationen abrufen kann.

Quellcode | API-Referenzdokumentation | REST-API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Installieren des Pakets

Installieren Sie die Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Maps.Rendering --prerelease

Voraussetzungen

Sie benötigen ein Azure-Abonnement und Azure Maps Konto.

Zum Erstellen eines neuen Azure Maps-Kontos können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Beispiel für die Verwendung der Azure-Befehlszeilenschnittstelle:

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

Authentifizieren des Clients

Es gibt zwei Möglichkeiten, den Client zu authentifizieren: Authentifizierung mit gemeinsam genutztem Schlüssel und Azure AD.

Authentifizierung mit gemeinsam verwendetem Schlüssel

• Wechseln Sie zur Registerkarte "Authentifizierung" Azure Maps Kontos>.
• Kopieren Primary Key oder Secondary Key im Abschnitt "Authentifizierung mit gemeinsam genutztem Schlüssel "

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

Azure AD-Authentifizierung

Um mit dem Azure Maps-Dienst zu interagieren, müssen Sie eine instance der MapsRenderingClient -Klasse erstellen. Die Azure Identity-Bibliothek erleichtert das Hinzufügen von Azure Active Directory-Unterstützung für die Authentifizierung von Azure SDK-Clients mit den entsprechenden Azure-Diensten.

Um die AAD-Authentifizierung zu verwenden, erstellen Sie die Umgebungsvariablen, wie in der Infodatei für Azure Identity beschrieben, und erstellen sie eine DefaultAzureCredential instance, die MapsRenderingClientmit verwendet werden soll.

Außerdem benötigen wir eine Azure Maps Client-ID, die im Abschnitt "Azure Active Directory-Authentifizierung" auf der Azure Maps > Seite > Authentifizierung registerkarte "Client-ID" zu finden ist.

// Create a MapsRenderingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRenderingClient client = new MapsRenderingClient(credential, clientId);

SAS-Authentifizierung (Shared Access Signature)

Shared Access Signature (SAS)-Token sind Authentifizierungstoken, die mit dem JSON-Webtoken-Format (JWT) erstellt und kryptografisch signiert werden, um die Authentifizierung für eine Anwendung gegenüber der Azure Maps-REST-API nachzuweisen.

Vor der Integration der SAS-Tokenauthentifizierung müssen wir und Azure.ResourceManager.Maps (Version 1.1.0-beta.2 oder höher) installierenAzure.ResourceManager:

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

Im Code müssen die folgenden Zeilen sowohl für Azure Maps SDK als auch für ResourceManager importiert werden:

using Azure.Maps.Rendering;

using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

Anschließend können wir das SAS-Token über die Sas-API auflisten abrufen und es MapsRenderingClientzuweisen. Im folgenden Codebeispiel rufen wir eine bestimmte Zuordnungskontoressource ab und erstellen ein SAS-Token für die Ablaufzeit von 1 Tag, wenn der Code ausgeführt wird.

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

Wichtige Begriffe

MapsRenderingClient ist für Folgendes konzipiert:

• Kommunizieren mit Azure Maps Endpunkt zum Abrufen von Bildern und Kacheln
• Kommunizieren mit Azure Maps Endpunkt, um Urheberrechte für Bilder und Kacheln zu erhalten

Weitere Informationen zu Beispielen

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Mithilfe unserer Beispiele können Sie sich mit verschiedenen APIs vertraut machen. Das Rendern von Kartenkacheln erfordert Kenntnisse über Zoomstufen und das Kachelrastersystem. Weitere Informationen finden Sie in der Dokumentation .

Abrufen von Bilddatenkacheln

Hier sehen Sie ein einfaches Beispiel für das Rendern von Bilddatenkacheln:

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

Problembehandlung

Allgemein

Wenn Sie mit den Azure Maps-Diensten interagieren, entsprechen die vom Dienst zurückgegebenen Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise versuchen, eine Bildkachel mit einem falschen Kachelindex abzurufen, wird ein Fehler zurückgegeben, der auf "Ungültige Anforderung" (HTTP 400) hinweist.

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

Nächste Schritte

• Weitere Kontext- und zusätzliche Szenarien finden Sie unter Ausführliche Beispiele.

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter <cla.microsoft.com>.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.