Azure Maps Suchclientbibliothek für .NET– Version 1.0.0-beta.4

Artikel
07/20/2023

Azure Maps Suche ist eine Bibliothek, die Nach Orten, Interessenspunkten oder Suchen innerhalb eines geometrischen Bereichs abfragen 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.Search --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 unter dem Abschnitt "Authentifizierung mit gemeinsam genutztem Schlüssel "

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

Azure AD-Authentifizierung

Um mit dem Azure Maps-Dienst zu interagieren, müssen Sie eine instance der MapsSearchClient-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 TENANT_ID, CLIENT_IDund CLIENT_SECRET auf umgebungsvariable fest, und rufen Sie DefaultAzureCredential() die Methode auf, um Anmeldeinformationen abzurufen. CLIENT_IDund CLIENT_SECRET sind die Dienstprinzipal-ID und das Geheimnis, die auf Azure Maps Konto zugreifen können.

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 MapsSearchClient that will authenticate through AAD
DefaultAzureCredential credential = new DefaultAzureCredential();
string clientId = "<My Map Account Client Id>";
MapsSearchClient client = new MapsSearchClient(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.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;

Anschließend können wir das SAS-Token über die Sas-API auflisten abrufen und es MapsSearchClientzuweisen. 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);
MapsSearchClient client = new MapsSearchClient(sasCredential);

Wichtige Begriffe

MapsSearchClient wurde für Folgendes entwickelt:

Kommunizieren mit Azure Maps Endpunkt, um Adressen oder Standortpunkte abzufragen
Kommunizieren mit Azure Maps Endpunkt, um die Geometriedaten anzufordern, z. B. eine Stadt- oder Ländergliederung für eine Gruppe von Entitäten
Kommunikation mit Azure Maps Endpunkt, um eine Freihandformularsuche innerhalb einer einzelnen Geometrie oder in vielen davon durchzuführen

Weitere Informationen finden Sie in unseren 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.

Beispiel zum Abrufen von Polygonen

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

Beispiel für Fuzzysuche

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

Beispiel für die umgekehrte Straßensuche

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

Beispiel für strukturierte Suchadresse

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

Beispielsuche innerhalb der Geometrie

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

Beispiel-Suchadresse

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

Problembehandlung

Allgemein

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

Wenn Sie beispielsweise versuchen, mit ungültigen Koordinaten zu suchen, wird ein Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist.400

Nächste Schritte

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

Share via