C# REST SDK 개발자 가이드

아티클
09/03/2024

Azure Maps C# SDK는 주소 검색, 다른 좌표 간 라우팅 및 특정 IP 주소의 지리적 위치 가져오기와 같이 Azure Maps Rest API에서 사용할 수 있는 기능을 지원합니다. 이 문서에서는 C# REST SDK에 Azure Maps의 성능을 통합하는 위치 인식 애플리케이션을 C#에서 빌드하는 데 도움이 되는 예제를 소개합니다.

참고 항목

Azure Maps C# SDK는 .NET Standard 버전 2.0 이상과 호환되는 모든 .NET 버전을 지원합니다. 대화형 테이블은 .NET Standard 버전을 참조하세요.

필수 조건

Azure Maps 계정.
구독 키 또는 다른 형태의 Azure Maps 인증.
.NET Standard 버전 2.0 이상

팁

프로그래밍 방식으로 Azure Maps 계정을 만들 수 있습니다. 다음은 Azure CLI를 사용하는 예입니다.

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

.NET 프로젝트 만들기

다음 PowerShell 코드 조각은 PowerShell을 사용하여 .NET 7.0에서 콘솔 프로그램 MapsDemo를 만드는 방법을 보여 줍니다. 모든 .NET Standard 2.0 호환 버전을 프레임워크로 사용할 수 있습니다.

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

필요한 패키지를 설치합니다.

Azure Maps C# SDK를 사용하려면 필요한 패키지를 설치해야 합니다. 검색, 라우팅, 렌더링 및 지리적 위치를 포함한 각 Azure Maps 서비스는 각각 자체 패키지에 있습니다. Azure Maps C# SDK는 퍼블릭 미리 보기 상태이므로 --prerelease 플래그를 추가해야 합니다.

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 서비스

서비스 이름	NuGet 패키지	샘플
Search	Azure.Maps.Search	검색 샘플
라우팅	Azure.Maps.Routing	라우팅 샘플
렌더링	Azure.Maps.Rendering	렌더링 샘플
지리적 위치	Azure.Maps.Geolocation	지리적 위치 샘플

MapsSearchClient 만들기 및 인증

Azure Maps Search API에 액세스하는 데 사용되는 클라이언트 개체에는 Azure Maps 구독 키를 사용할 때 인증하기 위해 AzureKeyCredential 개체가 필요하거나 Microsoft Entra ID를 사용하여 인증할 때 Azure Maps 클라이언트 ID가 있는 TokenCredential 개체가 필요합니다. 자세한 내용은 Azure Maps로 인증을 참조하세요.

Microsoft Entra 자격 증명 사용

Azure ID 라이브러리를 사용하여 Microsoft Entra ID로 인증할 수 있습니다. DefaultAzureCredential 공급자를 사용하려면 .NET용 Azure ID 클라이언트 라이브러리를 설치해야 합니다.

dotnet add package Azure.Identity

서비스 주체에 필요한 역할을 할당하여 새 Microsoft Entra 애플리케이션을 등록하고 Azure Maps에 대한 액세스 권한을 부여해야 합니다. 자세한 내용은 비 Azure 리소스의 디먼 호스트를 참조하세요. 애플리케이션(클라이언트) ID, 디렉터리(테넌트) ID 및 클라이언트 암호가 반환됩니다. 이 값을 복사하여 안전한 장소에 저장합니다. 다음 단계에서 필요합니다.

Microsoft Entra 애플리케이션의 애플리케이션(클라이언트) ID, 디렉터리(테넌트) ID, 클라이언트 암호 값과 맵 리소스의 클라이언트 ID를 환경 변수로 설정합니다.

환경 변수	설명
AZURE_CLIENT_ID	등록된 애플리케이션의 애플리케이션(클라이언트) ID
AZURE_CLIENT_SECRET	등록된 애플리케이션의 클라이언트 암호 값
AZURE_TENANT_ID	등록된 애플리케이션의 디렉터리(테넌트) ID
MAPS_CLIENT_ID	Azure Map 리소스의 클라이언트 ID

이제 PowerShell에서 환경 변수를 만들어 다음 값을 저장할 수 있습니다.

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

환경 변수를 설정한 후 프로그램에서 사용하여 AzureMapsSearch 클라이언트를 인스턴스화할 수 있습니다.

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

Important

이전 코드 조각에서 만들어진 다른 환경 변수는 코드 샘플에서는 사용되지 않았지만 DefaultAzureCredential()에 필요합니다. 동일한 명명 규칙을 사용하여 이러한 환경 변수를 올바르게 설정하지 않으면 런타임 오류가 발생합니다. 예를 들어 AZURE_CLIENT_ID가 누락되었거나 잘못된 경우 InvalidAuthenticationTokenTenant 오류가 발생합니다.

구독 키 자격 증명 사용

Azure Maps 구독 키로 인증할 수 있습니다. 구독 키는 다음 스크린샷과 같이 Azure Maps 계정의 인증 섹션에서 찾을 수 있습니다.

이제 PowerShell에서 환경 변수를 만들어 구독 키를 저장할 수 있습니다.

$Env:SUBSCRIPTION_KEY="your subscription key"

환경 변수가 만들어지면 코드에서 액세스할 수 있습니다.

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

주소 지오코딩

GetGeocoding 메서드를 호출하여 주소의 좌표를 가져옵니다.

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

일괄 처리 지오코드 주소

이 샘플은 주소 일괄 검색을 수행하는 방법을 보여줍니다.

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

좌표 역방향 지오코딩

좌표를 사람이 읽을 수 있는 주소로 변환할 수 있습니다. 이 프로세스를 역방향 지오코딩이라고도 합니다.

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

좌표 집합 일괄 처리 역방향 지오코드

Azure Maps Search는 일부 일괄 처리 쿼리 API도 제공합니다. 역방향 지오코딩 Batch API는 단일 API 호출을 사용하여 역방향 지오코딩 API로 쿼리 배치를 보냅니다. API를 사용하면 호출자가 최대 100개의 쿼리를 일괄 처리할 수 있습니다.

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

지정된 위치에 대한 다각형 가져오기

이 샘플에서는 다각형을 검색하는 방법을 보여 줍니다.

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 사용

Search v1 사용에 대한 자세한 내용은 .NET에 대한 Azure Maps Search 클라이언트 라이브러리를 참조하세요. Render v1 사용에 대한 자세한 내용은 .NET에 대한 Azure Maps Render 클라이언트 라이브러리를 참조하세요.

추가 정보

.NET 설명서의 Azure.Maps 네임스페이스

다음을 통해 공유