Ontwikkelaarshandleiding voor C# REST SDK

Artikel
10/18/2023

De Azure Kaarten C#SDK ondersteunt functionaliteit die beschikbaar is in de Azure Kaarten Rest API, zoals zoeken naar een adres, routering tussen verschillende coördinaten en het ophalen van de geografische locatie van een specifiek IP-adres. In dit artikel maakt u kennis met de C# REST SDK met voorbeelden waarmee u aan de slag kunt met het bouwen van locatiebewuste toepassingen in C# die de kracht van Azure Kaarten bevat.

Notitie

Azure Kaarten C#SDK ondersteunt elke .NET-versie die compatibel is met .NET Standard versie 2.0 of hoger. Zie .NET Standard-versies voor een interactieve tabel.

Vereisten

Azure Kaarten-account.
Abonnementssleutel of een andere vorm van verificatie met Azure Kaarten.
.NET Standard versie 2.0 of hoger.

Tip

U kunt programmatisch een Azure Kaarten-account maken. Hier volgt een voorbeeld met behulp van de Azure CLI:

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

Een .NET-project maken

In het volgende PowerShell-codefragment ziet u hoe u PowerShell gebruikt om een consoleprogramma MapsDemo te maken met .NET 7.0. U kunt elke .NET Standard 2.0-compatibele versie als framework gebruiken.

dotnet new console -lang C# -n MapsDemo -f net7.0 
cd MapsDemo

De vereiste pakketten installeren

Als u Azure Kaarten C#SDK wilt gebruiken, moeten we de vereiste pakketten installeren. Elk van de Azure Kaarten-services, waaronder zoeken, routering, rendering en geolocatie, bevinden zich elk in hun eigen pakket. Omdat de Azure Kaarten C#SDK in openbare preview is, moet u de --prerelease vlag toevoegen:

dotnet add package Azure.Maps.Rendering --prerelease
dotnet add package Azure.Maps.Routing --prerelease
dotnet add package Azure.Maps.Search --prerelease
dotnet add package Azure.Maps.Geolocation --prerelease

Azure Maps Services

Servicenaam	NuGet-pakket	Monsters
Zoeken	Azure. Kaarten. Zoek	zoekvoorbeelden
Routering	Azure. Kaarten. Routering	routeringsvoorbeelden
Rendering	Azure. Kaarten. Rendering	renderingvoorbeeld
Geolocation	Azure. Kaarten. Geolocation	voorbeeld van geolocatie

Een Kaarten SearchClient maken en verifiëren

Voor het clientobject dat wordt gebruikt voor toegang tot de Azure Kaarten Search-API's, is een AzureKeyCredential object vereist om te verifiëren bij het gebruik van een Azure Kaarten-abonnementssleutel of een TokenCredential object met de Azure Kaarten-client-id bij het verifiëren met behulp van Microsoft Entra-id. Zie Verificatie met Azure Kaarten voor meer informatie over verificatie.

Een Microsoft Entra-referentie gebruiken

U kunt verifiëren met Microsoft Entra-id met behulp van de Azure Identity-bibliotheek. Als u de DefaultAzureCredential-provider wilt gebruiken, moet u de Azure Identity-clientbibliotheek voor .NET installeren:

dotnet add package Azure.Identity

U moet de nieuwe Microsoft Entra-toepassing registreren en toegang verlenen tot Azure Kaarten door de vereiste rol toe te wijzen aan uw service-principal. Zie Een daemon hosten voor niet-Azure-resources voor meer informatie. De toepassings-id (client), een map-id (tenant) en een clientgeheim worden geretourneerd. Kopieer deze waarden en sla ze op een veilige plaats op. U hebt ze nodig in de volgende stappen.

Stel de waarden in van de toepassings-id (client),map-id (tenant) en het clientgeheim van uw Microsoft Entra-toepassing en de client-id van de toewijzingsresource als omgevingsvariabelen:

Omgevingsvariabele	Beschrijving
AZURE_CLIENT_ID	Toepassings-id (client) in uw geregistreerde toepassing
AZURE_CLIENT_SECRET	De waarde van het clientgeheim in uw geregistreerde toepassing
AZURE_TENANT_ID	Map-id (tenant) in uw geregistreerde toepassing
MAPS_CLIENT_ID	De client-id in uw Azure Map-resource

U kunt nu omgevingsvariabelen maken in PowerShell om deze waarden op te slaan:

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

Nadat u de omgevingsvariabelen hebt ingesteld, kunt u deze in uw programma gebruiken om de AzureMapsSearch client te instantiëren:

using System;
using Azure.Identity; 
using Azure.Maps.Search; 

var credential = new DefaultAzureCredential(); 
var clientId = Environment.GetEnvironmentVariable("MAPS_CLIENT_ID"); 
var client = new MapsSearchClient(credential, clientId);

Belangrijk

De andere omgevingsvariabelen die zijn gemaakt in het vorige codefragment, terwijl ze niet worden gebruikt in het codevoorbeeld, zijn vereist voor DefaultAzureCredential(). Als u deze omgevingsvariabelen niet correct instelt met dezelfde naamconventies, krijgt u runtimefouten. Als uw AZURE_CLIENT_ID bestand bijvoorbeeld ontbreekt of ongeldig is, krijgt u een InvalidAuthenticationTokenTenant foutmelding.

Een abonnementssleutelreferentie gebruiken

U kunt zich verifiëren met uw Azure Kaarten-abonnementssleutel. Uw abonnementssleutel vindt u in de sectie Verificatie in het Azure Kaarten-account, zoals wordt weergegeven in de volgende schermopname:

U kunt nu omgevingsvariabelen maken in PowerShell om de abonnementssleutel op te slaan:

$Env:SUBSCRIPTION_KEY="your subscription key"

Zodra uw omgevingsvariabele is gemaakt, kunt u deze openen in uw code:

using System;
using Azure; 
using Azure.Maps.Search; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

Fuzzy zoeken in een entiteit

In het volgende codefragment ziet u hoe u in een eenvoudige consoletoepassing het Azure.Maps.Search pakket importeert en een fuzzy zoekopdracht uitvoert op Starbucks in de buurt van Seattle. In Program.cs:

using System;
using Azure; 
using Azure.Core.GeoJson; 
using Azure.Maps.Search; 
using Azure.Maps.Search.Models; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

SearchAddressResult searchResult = client.FuzzySearch( 
    "Starbucks", new FuzzySearchOptions 
    { 
        Coordinates = new GeoPosition(-122.34255, 47.61010), 
        Language = SearchLanguage.EnglishUsa 
    }); 


// Print the search results 
foreach (var result in searchResult.Results) 
{ 
    Console.WriteLine($""" 
        * {result.Address.StreetNumber} {result.Address.StreetName} 
          {result.Address.Municipality} {result.Address.CountryCode} {result.Address.PostalCode} 
          Coordinate: ({result.Position.Latitude:F4}, {result.Position.Longitude:F4}) 
        """); 
}

Het bovenstaande codefragment laat zien hoe u een MapsSearchClient object maakt met behulp van uw Azure-referenties en vervolgens de FuzzySearch-methode gebruikt, waarbij de nuttige plaatsnaam 'Starbucks' wordt doorgegeven en GeoPosition(-122.31, 47.61) wordt doorgegeven. De SDK-pakketten en verzendt de resultaten naar de Azure Kaarten REST-eindpunten. Wanneer de zoekresultaten worden geretourneerd, worden ze naar het scherm geschreven met behulp van Console.WriteLine.

De volgende bibliotheken worden gebruikt:

Azure.Maps.Search is vereist voor de MapsSearchClient klasse.
Azure.Maps.Search.Models is vereist voor de SearchAddressResult klasse.
Azure.Core.GeoJson is vereist voor de GeoPosition struct die door de FuzzySearchOptions klasse wordt gebruikt.

Als u uw toepassing wilt uitvoeren, gaat u naar de projectmap en voert u deze uit dotnet run in PowerShell:

dotnet run

Als het goed is, ziet u een lijst met Starbucks-adressen en coördinaatresultaten:

* 1912 Pike Place 
  Seattle US 98101 
  Coordinate: 47.61016, -122.34248 
* 2118 Westlake Avenue 
  Seattle US 98121 
  Coordinate: 47.61731, -122.33782 
* 2601 Elliott Avenue 
  Seattle US 98121 
  Coordinate: 47.61426, -122.35261 
* 1730 Howell Street 
  Seattle US 98101 
  Coordinate: 47.61716, -122.3298 
* 220 1st Avenue South 
  Seattle US 98104 
  Coordinate: 47.60027, -122.3338 
* 400 Occidental Avenue South 
  Seattle US 98104 
  Coordinate: 47.5991, -122.33278 
* 1600 East Olive Way 
  Seattle US 98102 
  Coordinate: 47.61948, -122.32505 
* 500 Mercer Street 
  Seattle US 98109 
  Coordinate: 47.62501, -122.34687 
* 505 5Th Ave S 
  Seattle US 98104 
  Coordinate: 47.59768, -122.32849 
* 425 Queen Anne Avenue North 
  Seattle US 98109 
  Coordinate: 47.62301, -122.3571

Een adres zoeken

Roep de SearchAddress methode aan om de coördinaat van een adres op te halen. Wijzig het hoofdprogramma als volgt uit het voorbeeld:

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

SearchAddressResult searchResult = client.SearchAddress(
    "1301 Alaskan Way, Seattle, WA 98101, US");

if (searchResult.Results.Count > 0) 
{
    SearchAddressResultItem result = searchResult.Results.First(); 
    Console.WriteLine($"The Coordinate: ({result.Position.Latitude:F4}, {result.Position.Longitude:F4})"); 
}

De SearchAddress methode retourneert resultaten gesorteerd op betrouwbaarheidsscore en omdat searchResult.Results.First() deze wordt gebruikt, worden alleen de coördinaten van het eerste resultaat geretourneerd.

Batch reverse search

Azure Kaarten Search biedt ook enkele batchquerymethoden. Deze methoden retourneren LRO-objecten (Long Running Operations). De aanvragen retourneren mogelijk niet onmiddellijk alle resultaten, zodat gebruikers ervoor kunnen kiezen om te wachten totdat het resultaat is voltooid of het resultaat periodiek op te vragen. In het volgende voorbeeld ziet u hoe u de batched reverse search-methoden aanroept:

var queries = new List<ReverseSearchAddressQuery>() 
{ 
    new ReverseSearchAddressQuery(new ReverseSearchOptions() 
    { 
        Coordinates = new GeoPosition(2.294911, 48.858561) 
    }), 
    new ReverseSearchAddressQuery(new ReverseSearchOptions() 
    { 
        Coordinates = new GeoPosition(-122.127896, 47.639765), 
        RadiusInMeters = 5000 
    }) 
};

In het bovenstaande voorbeeld worden twee query's doorgegeven aan de aanvraag voor reverse search in batches. Als u de LRO-resultaten wilt ophalen, hebt u enkele opties. De eerste optie is om door te geven WaitUntil.Completed aan de methode. De aanvraag wacht totdat alle aanvragen zijn voltooid en retourneert de resultaten:

// Wait until the LRO return batch results 
Response<ReverseSearchAddressBatchOperation> waitUntilCompletedResults = client.ReverseSearchAddressBatch(WaitUntil.Completed, queries); 

// Print the result addresses 
printReverseBatchAddresses(waitUntilCompletedResults.Value);

Een andere optie is om door te geven WaitUntil.Started. De aanvraag wordt onmiddellijk geretourneerd en u moet de resultaten handmatig peilen:

// Manual polling the batch results 
Response<ReverseSearchAddressBatchOperation> manualPollingOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

// Keep polling until we get the results
while (true)
{
    manualPollingOperation.Value.UpdateStatus();
    if (manualPollingOperation.Value.HasCompleted) break;
    Task.Delay(1000);
}
printReverseBatchAddresses(manualPollingOperation);

We kunnen ook aanroepen WaitUntilCompletion() om expliciet te wachten op het resultaat:

Response<ReverseSearchAddressBatchOperation> manualPollingResult = manualPollingResults.WaitUntilCompleted();

printReverseBatchAddresses(manualPollingResult.Value);

Voor de derde methode is de bewerkings-id vereist om de resultaten op te halen, die gedurende 14 dagen in de cache op de server worden opgeslagen:

  ReverseSearchAddressBatchOperation longRunningOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

  // Get batch results by ID 
  string operationId = longRunningOperation.Value.Id;

  // After the LRO completes, create a new operation
  // to get the results from the server
  ReverseSearchAddressBatchOperation newOperation = new ReverseSearchAddressBatchOperation(client, operationId);
  Response<ReverseSearchAddressBatchOperation> newOperationResult = newOperation.WaitForCompletion();

printReverseBatchAddresses(newOperationResult);

De volledige code voor batchzoekopdrachten met reverse address met bewerkings-id:

using system;
using Azure;
using Azure.Core.GeoJson;
using Azure.Maps.Search;
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

var queries = new List<ReverseSearchAddressQuery>()
{
    new ReverseSearchAddressQuery(new ReverseSearchOptions()
    {
        Coordinates = new GeoPosition(2.294911, 48.858561)
    }),
    new ReverseSearchAddressQuery(new ReverseSearchOptions()
    {
        Coordinates = new GeoPosition(-122.127896, 47.639765),
        RadiusInMeters = 5000
    })
};

// Manual polling the batch results
ReverseSearchAddressBatchOperation longRunningOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

// Get batch results by ID
string operationId = longRunningOperation.Id;

// A few days later, create a new operation and get the result from server
ReverseSearchAddressBatchOperation newOperation = new ReverseSearchAddressBatchOperation(client, operationId);
Response<ReverseSearchAddressBatchResult> newOperationResult = newOperation.WaitForCompletion();
printReverseBatchAddresses(newOperationResult.Value);
void printReverseBatchAddresses(ReverseSearchAddressBatchResult batchResult)
{
    // Print the search results
    for (int i = 0; i < batchResult.Results.Count; i++)
    {
        Console.WriteLine($"Possible addresses for query {i}:");
        var result = batchResult.Results[i];
        foreach (var address in result.Addresses)
        {
            Console.WriteLine($"{address.Address.FreeformAddress}");
        }
    }
}

Aanvullende informatie

Azure.Kaarten Naamruimte in de .NET-documentatie.

Delen via