Ontwikkelaarshandleiding voor C# REST SDK

De Azure Maps C#SDK ondersteunt functionaliteit die beschikbaar is in de Rest API van Azure Maps, 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 Maps bevat.

Notitie

Azure Maps 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 Maps-account.
• Abonnementssleutel of een andere vorm van verificatie met Azure Maps.
• .NET Standard versie 2.0 of hoger.

Tip

U kunt programmatisch een Azure Maps-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 de Azure Maps C#SDK wilt gebruiken, moeten we de vereiste pakketten installeren. Elk van de Azure Maps-services, waaronder zoeken, routering, rendering en geolocatie, zijn elk in hun eigen pakket. Omdat de Azure Maps 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.Maps.Search	zoekvoorbeelden
Routering	Azure.Maps.Routing	routeringsvoorbeelden
Rendering	Azure.Maps.Rendering	renderingvoorbeeld
Geolocatie	Azure.Maps.Geolocation	voorbeeld van geolocatie

Een MapsSearchClient maken en verifiëren

Voor het clientobject dat wordt gebruikt voor toegang tot de Azure Maps Search-API's, is een AzureKeyCredential object vereist om te verifiëren bij het gebruik van een Azure Maps-abonnementssleutel of een TokenCredential object met de Azure Maps-client-id bij verificatie met behulp van Microsoft Entra-id. Zie Verificatie met Azure Maps 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 Maps 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 verifiëren met uw Azure Maps-abonnementssleutel. Uw abonnementssleutel vindt u in de sectie Verificatie in het Azure Maps-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); 

Een adres geocoderen

Roep de GetGeocoding methode aan om de coördinaat van een adres op te halen.

using System;
using Azure; 
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); 

Response<GeocodingResponse> searchResult = client.GetGeocoding(
    "1 Microsoft Way, Redmond, WA 98052");

for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
    Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}

Batch-geocodeadressen

In dit voorbeeld ziet u hoe u een batchzoekadres uitvoert.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

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

List<GeocodingQuery> queries = new List<GeocodingQuery>
{
    new GeocodingQuery()
    {
        Query ="15171 NE 24th St, Redmond, WA 98052, United States"
    },
    new GeocodingQuery()
    {
        AddressLine = "400 Broad St"
    },
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);

//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
    for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
    {
        Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
    }
}

Geocoderen van coördinaten omkeren

U kunt coördinaten omzetten in door mensen leesbare straatadressen. Dit proces wordt ook wel omgekeerde geocodering genoemd.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
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); 

GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);

//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
    Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}

Batch reverse geocodeer een set coördinaten

Azure Maps Search biedt ook enkele batchquery-API's. Met de Batch-API voor reverse geocodering worden batches met query's verzonden naar reverse geocoderings-API met slechts één API-aanroep. Met de API kan de aanroeper maximaal 100 query's batches uitvoeren.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

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

List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.349309, 47.620498)
    },
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.138679, 47.630356),
        ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
    },
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}

Veelhoeken voor een bepaalde locatie ophalen

In dit voorbeeld ziet u hoe u veelhoeken kunt doorzoeken.

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

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

GetPolygonOptions options = new GetPolygonOptions()
{
    Coordinates = new GeoPosition(-122.204141, 47.61256),
    ResultType = BoundaryResultTypeEnum.Locality,
    Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);

var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
    var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
    for (var j = 0; j < coorCount; j++)
    {
        Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
    }
}

V1 SDK's gebruiken voor zoeken en weergeven

Zie de Azure Maps Search-clientbibliotheek voor .NET voor meer informatie over het gebruik van Search v1. Zie de Azure Maps Render-clientbibliotheek voor .NET voor meer informatie over het gebruik van Render v1.

Aanvullende informatie

De Azure.Maps-naamruimte in de .NET-documentatie.