Příručka pro vývojáře v sadě C# REST SDK

Článek
10/14/2024

Sada Azure Maps C# SDK podporuje funkce dostupné v rozhraní Rest API služby Azure Maps, jako je hledání adresy, směrování mezi různými souřadnicemi a získání geografického umístění konkrétní IP adresy. Tento článek představuje sadu C# REST SDK s příklady, které vám pomůžou začít vytvářet aplikace pracující s umístěním v jazyce C#, které zahrnují výkon služby Azure Maps.

Poznámka:

Sada Azure Maps C# SDK podporuje libovolnou verzi .NET, která je kompatibilní se standardem .NET verze 2.0 nebo vyšší. Interaktivní tabulku najdete v tématu Verze .NET Standard.

Požadavky

Účet Azure Maps.
Klíč předplatného nebo jiná forma ověřování pomocí Azure Maps.
.NET Standard verze 2.0 nebo vyšší.

Tip

Účet Azure Maps můžete vytvořit programově. Tady je příklad s využitím Azure CLI:

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

Vytvoření projektu .NET

Následující fragment kódu PowerShellu ukazuje, jak pomocí PowerShellu vytvořit konzolový program MapsDemo s .NET 7.0. Jako architekturu můžete použít libovolnou verzi kompatibilní se standardem .NET 2.0.

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

Instalace požadovaných balíčků

Abychom mohli používat sadu Azure Maps C# SDK, musíme nainstalovat požadované balíčky. Každá ze služeb Azure Maps, včetně vyhledávání, směrování, vykreslování a geografické polohy, jsou každá z nich ve vlastním balíčku. Vzhledem k tomu, že sada Azure Maps C# SDK je ve verzi Public Preview, musíte přidat --prerelease příznak:

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

Služby Azure Maps

Název služby	Balíček NuGet	Vzorky
Vyhledat	Azure.Maps.Search	ukázky hledání
Směrování	Azure.Maps.Routing	ukázky směrování
Vykreslování	Azure.Maps.Rendering	ukázka vykreslování
Geografická poloha	Azure.Maps.Geolocation	Ukázka geografické polohy

Vytvoření a ověření MapsSearchClient

Objekt klienta použitý pro přístup k rozhraním API služby Azure Maps Search vyžaduje AzureKeyCredential ověření objektu při použití klíče předplatného Azure Maps nebo TokenCredential objektu s ID klienta Azure Maps při ověřování pomocí Microsoft Entra ID. Další informace o ověřování najdete v tématu Ověřování pomocí Azure Maps.

Použití přihlašovacích údajů Microsoft Entra

Ověřování pomocí Microsoft Entra ID můžete provést pomocí knihovny identit Azure. Pokud chcete použít zprostředkovatele DefaultAzureCredential , musíte nainstalovat klientskou knihovnu Azure Identity pro .NET:

dotnet add package Azure.Identity

Musíte zaregistrovat novou aplikaci Microsoft Entra a udělit přístup ke službě Azure Maps přiřazením požadované role k instančnímu objektu. Další informace najdete v tématu Hostování démona u prostředků mimo Azure. Vrátí se ID aplikace (klienta), ID adresáře (tenanta) a tajný klíč klienta. Zkopírujte tyto hodnoty a uložte je na bezpečném místě. Budete je potřebovat v následujících krocích.

Nastavte hodnoty ID aplikace (klienta), ID adresáře (tenanta) a tajného klíče klienta vaší aplikace Microsoft Entra a ID klienta prostředku mapy jako proměnné prostředí:

Proměnná prostředí	Popis
AZURE_CLIENT_ID	ID aplikace (klienta) ve vaší registrované aplikaci
AZURE_CLIENT_SECRET	Hodnota tajného klíče klienta v registrované aplikaci
AZURE_TENANT_ID	ID adresáře (tenanta) ve vaší registrované aplikaci
MAPS_CLIENT_ID	ID klienta ve vašem prostředku Azure Map

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení těchto hodnot:

$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"

Po nastavení proměnných prostředí je můžete v programu použít k vytvoření instance AzureMapsSearch klienta:

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

Důležité

Ostatní proměnné prostředí vytvořené v předchozím fragmentu kódu, zatímco v ukázce kódu se nepoužívají, jsou vyžadovány DefaultAzureCredential(). Pokud tyto proměnné prostředí nenastavíte správně pomocí stejných zásad vytváření názvů, zobrazí se chyby za běhu. Pokud například chybí nebo AZURE_CLIENT_ID je neplatný, zobrazí se InvalidAuthenticationTokenTenant chyba.

Použití přihlašovacích údajů klíče předplatného

Můžete se ověřit pomocí klíče předplatného Azure Maps. Klíč předplatného najdete v části Ověřování v účtu Azure Maps, jak je znázorněno na následujícím snímku obrazovky:

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení klíče předplatného:

$Env:SUBSCRIPTION_KEY="your subscription key"

Jakmile je proměnná prostředí vytvořená, můžete k ní přistupovat v kódu:

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

Geografické kódování adresy

GetGeocoding Voláním metody získáte souřadnici adresy.

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

Adresy geografického kódu služby Batch

Tato ukázka ukazuje, jak provést dávkovou adresu vyhledávání.

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

Zpětné geografické kódování souřadnic

Souřadnice můžete přeložit na adresy ulice čitelné člověkem. Tento proces se také označuje jako zpětné geokódování.

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 geocode a set of coordinates

Služba Azure Maps Search také poskytuje některá rozhraní API dávkového dotazu. Rozhraní BATCH API služby Reverse Geocoding odesílá dávky dotazů do rozhraní API zpětného kódování pomocí jediného volání rozhraní API. Rozhraní API umožňuje volajícímu dávkovat až 100 dotazů.

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

Získání mnohoúhelníku pro dané umístění

Tato ukázka ukazuje, jak hledat mnohoúhelníky.

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

Použití sad SDK V1 pro vyhledávání a vykreslování

Další informace o používání služby Search v1 najdete v klientské knihovně služby Azure Maps Search pro .NET. Další informace o použití renderu v1 najdete v klientské knihovně Azure Maps Render pro .NET.

Další informace

Obor názvů Azure.Maps v dokumentaci k .NET.

Sdílet prostřednictvím