C# REST SDK 개발자 가이드

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

엔터티에 대한 퍼지 검색

다음 코드 조각은 간단한 콘솔 애플리케이션에서 Azure.Maps.Search 패키지를 가져오고 시애틀 근처의 "스타벅스"에 대해 퍼지 검색을 수행하는 방법을 보여 줍니다. 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}) 
        """); 
} 

위의 코드 조각은 Azure 자격 증명을 사용하여 MapsSearchClient 개체를 만든 다음, FuzzySearch 메서드를 사용하여 POI(관심 지점) 이름 "Starbucks"를 전달하고 GeoPosition(-122.31, 47.61)을 조정하는 방법을 보여 줍니다. SDK는 결과를 패키지하고 Azure Maps REST 엔드포인트로 보냅니다. 검색 결과가 반환되면 Console.WriteLine을 사용하여 화면에 기록됩니다.

다음 라이브러리가 사용됩니다.

1. Azure.Maps.Search는 MapsSearchClient 클래스에 필요합니다.
2. Azure.Maps.Search.Models는 SearchAddressResult 클래스에 필요합니다.
3. Azure.Core.GeoJson은 FuzzySearchOptions 클래스에서 사용하는 GeoPosition 구조체에 필요합니다.

애플리케이션을 실행하려면 프로젝트 폴더로 이동하여 PowerShell에서 dotnet run을 실행합니다.

dotnet run 

스타벅스 주소 목록과 좌표 결과가 표시됩니다.

* 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 

주소 검색

SearchAddress 메서드를 호출하여 주소의 좌표를 가져옵니다. 다음과 같이 샘플에서 Main 프로그램을 수정합니다.

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

SearchAddress 메서드는 신뢰도 점수에 따라 순서가 지정된 결과를 반환하며 searchResult.Results.First()가 사용되므로 첫 번째 결과의 좌표만 반환됩니다.

일괄 처리 역방향 검색

Azure Maps Search는 일부 일괄 처리 쿼리 방법도 제공합니다. 이러한 메서드는 LRO(Long Running Operations) 개체를 반환합니다. 요청이 모든 결과를 즉시 반환하지 않을 수 있으므로 완료될 때까지 기다리거나 주기적으로 결과를 쿼리하도록 선택할 수 있습니다. 다음 예에서는 일괄 처리 역방향 검색 메서드를 호출하는 방법을 보여 줍니다.

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

위의 예제에서는 두 개의 쿼리가 일괄 처리된 역방향 검색 요청에 전달됩니다. LRO 결과를 얻으려면 몇 가지 옵션이 있습니다. 첫 번째 옵션은 메서드에 WaitUntil.Completed를 전달하는 것입니다. 요청은 모든 요청이 완료될 때까지 기다렸다가 결과를 반환합니다.

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

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

또 다른 옵션은 WaitUntil.Started를 전달하는 것입니다. 요청이 즉시 반환되므로 결과를 수동으로 폴링해야 합니다.

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

WaitUntilCompletion()을 호출하여 결과가 표시될 때까지 명시적으로 기다릴 수도 있습니다.

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

printReverseBatchAddresses(manualPollingResult.Value);

세 번째 방법에서는 결과를 가져오려면 작업 ID가 필요하며, 결과는 14일 동안 서버 쪽에 캐시됩니다.

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

작업 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}");
        }
    }
}

추가 정보

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