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

Artikel
07/20/2023

Azure Maps Geolocation ist eine Bibliothek, die die Geolocation an einem Standort oder an Sehenswürdigkeiten finden 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.Geolocation --prerelease

Voraussetzungen

Sie müssen über ein Azure-Abonnement und Azure Maps Konto verfügen.

Um ein neues Azure Maps-Konto zu erstellen, 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 freigegebenem Schlüssel und Azure AD.

Authentifizierung mit gemeinsam verwendetem Schlüssel

Wechseln Sie zur Registerkarte "Kontoauthentifizierung>" Azure Maps.
Kopieren Primary Key oder Secondary Key im Abschnitt Authentifizierung mit freigegebenem Schlüssel

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

Azure AD-Authentifizierung

Um mit dem Azure Maps-Dienst zu interagieren, müssen Sie eine instance der MapsGeolocationClient -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, legen Sie die Umgebungsvariablen wie in der Azure Identity-INFODATEI beschrieben fest, und erstellen Sie eine DefaultAzureCredential instance, die MapsRouteClientmit verwendet werden soll.

Außerdem benötigen wir Azure Maps Client-ID, die von Azure Maps Seite > Authentifizierungsregisterkarte > "Client-ID" im Abschnitt Azure Active Directory-Authentifizierung abgerufen werden kann.

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(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 für beide Azure Maps ResourceManager importiert werden:

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

Anschließend können wir SAS-Token über die List Sas-API abrufen und es MapsGeolocationClientzuweisen. Im folgenden Codebeispiel rufen wir eine bestimmte Zuordnungskontoressource ab und erstellen ein SAS-Token für eine 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);
MapsGeolocationClient client = new MapsGeolocationClient(sasCredential);

Wichtige Begriffe

MapsGeolocationClient ist konzipiert für:

Kommunizieren mit Azure Maps Geolocation SDK-Endpunkt, um den Standort von der angegebenen IP-Adresse abzurufen

Weitere Informationen zu Beispielen in 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

Beispiele

Mithilfe unserer Beispiele können Sie sich mit verschiedenen APIs vertraut machen.

Instanziieren Sie vor dem Aufrufen von Geolocation-APIs eine MapsGeolocationClient erste Instanz. Das folgende Beispiel verwendet AAD, um den Client instance zu erstellen:

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

Speicherort abrufen

Dieser Dienst gibt den ISO-Ländercode für die angegebene IP-Adresse zurück. Entwickler können diese Informationen verwenden, um bestimmte Inhalte basierend auf geografischen Standorten zu blockieren oder zu ändern, von denen aus die Anwendung angezeigt wird.

//Get location by given IP address
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);

//Get location result country code
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");

Ausführlichere Beispiele finden Sie auf der Seite Geolocationbeispiele .

Problembehandlung

Allgemein

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

Wenn Sie beispielsweise eine falsche IP-Adresse übergeben, wird ein Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist (HTTP-Statuscode: 400).

try
{
    // An invalid IP address
    IPAddress inValidIpAddress = IPAddress.Parse("2001:4898:80e8:b:123123213123");

    Response<CountryRegionResult> result = client.GetCountryCode(inValidIpAddress);
    // Do something with result ...
}
catch (FormatException e)
{
    Console.WriteLine(e.ToString());
}

Nächste Schritte

Weitere Kontext- und zusätzliche Szenarien finden Sie unter: Ausführlichere Beispiele

Mitwirken

Weitere 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.

Aufrufe

Share via