Python REST SDK 개발자 가이드(미리 보기)

아티클
08/16/2024

Azure Maps Python SDK를 Python 애플리케이션 및 라이브러리와 통합하여 지도 관련 및 위치 인식 애플리케이션을 빌드할 수 있습니다. Azure Maps Python SDK에는 검색, 경로, 렌더링 및 지리적 위치용 API가 포함되어 있습니다. 이러한 API는 주소 검색, 서로 다른 좌표 간 라우팅, 특정 IP 주소의 지리적 위치 가져오기와 같은 작업을 지원합니다.

필수 조건

Azure Maps 계정.
구독 키 또는 다른 형태의 Azure Maps 인증.
3.8 이상에서 Python. 최신 릴리스를 사용하는 것이 좋습니다. 자세한 내용은 Python용 Azure SDK 버전 지원 정책을 참조하세요.

팁

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

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

Python 프로젝트 만들기

다음 예제에서는 Python을 사용하여 demo라는 콘솔 프로그램을 만드는 방법을 보여 줍니다.

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

필요한 Python 패키지 설치

Azure Maps의 각 서비스는 자체 패키지에 포함되어 있습니다. Azure Maps Python SDK를 사용하는 경우 필요한 서비스의 패키지만 설치할 수 있습니다.

여기서는 Azure Maps Search 패키지를 설치합니다. 아직 공개 미리 보기 상태이므로 --pre 플래그를 추가해야 합니다.

pip install azure-maps-search --pre

Azure Maps 서비스

Azure Maps Python SDK는 Python 버전 3.8 이상을 지원합니다. 향후 Python 버전에 대한 자세한 내용은 Python용 Azure SDK 버전 지원 정책을 참조하세요.

서비스 이름	PyPi 패키지	샘플
Search	azure-maps-search	검색 샘플
Route	azure-maps-route	경로 샘플
렌더링	azure-maps-render	렌더링 샘플
지리적 위치	azure-maps-geolocation	지리적 위치 샘플

MapsSearchClient 만들기 및 인증

Azure Maps 검색 API에 액세스하는 데 사용되는 MapsSearchClient 개체를 만들 때 인증을 위해 credential 개체가 필요합니다. Microsoft Entra 자격 증명 또는 Azure 구독 키를 사용하여 인증할 수 있습니다. 자세한 내용은 Azure Maps로 인증을 참조하세요.

팁

MapsSearchClient는 Azure Maps 검색 라이브러리를 사용하는 개발자를 위한 기본 인터페이스입니다. 사용 가능한 검색 방법에 대한 자세한 내용은 Azure Maps Search 패키지 클라이언트 라이브러리를 참조하세요.

Microsoft Entra 자격 증명 사용

Azure ID 패키지를 사용하여 Microsoft Entra ID로 인증을 받을 수 있습니다. DefaultAzureCredential 공급자를 사용하려면 Azure ID 클라이언트 패키지를 설치해야 합니다.

pip install azure-identity

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

다음으로 맵의 클라이언트 ID를 지정하여 사용하려는 Azure Maps 계정을 지정해야 합니다. Azure Maps 계정 클라이언트 ID는 Azure Maps 계정의 인증 섹션에서 찾을 수 있습니다. 자세한 내용은 인증 세부 정보 보기를 참조하세요.

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

환경 변수	설명
AZURE_CLIENT_ID	등록된 애플리케이션의 애플리케이션(클라이언트) ID
AZURE_CLIENT_SECRET	등록된 애플리케이션의 클라이언트 암호 값
AZURE_TENANT_ID	등록된 애플리케이션의 디렉터리(테넌트) ID
MAPS_CLIENT_ID	Azure Maps 계정의 클라이언트 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 클라이언트를 인스턴스화하는 데 사용할 수 있습니다. demo.py라는 파일을 만들고 다음 코드를 추가합니다.

import os
from azure.identity import DefaultAzureCredential 
from azure.maps.search import MapsSearchClient 

credential = DefaultAzureCredential()
maps_client_id = os.getenv("MAPS_CLIENT_ID")
maps_search_client = MapsSearchClient(
    client_id=maps_client_id,
    credential=credential
)

Important

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

구독 키 자격 증명 사용

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

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

$Env:SUBSCRIPTION_KEY="your subscription key"

환경 변수가 만들어지면 코드에서 액세스할 수 있습니다. demo.py라는 파일을 만들고 다음 코드를 추가합니다.

import os

from azure.core.credentials import AzureKeyCredential
from azure.maps.search import MapsSearchClient

# Use Azure Maps subscription key authentication
subscription_key = os.getenv("SUBSCRIPTION_KEY")
maps_search_client = MapsSearchClient(
   credential=AzureKeyCredential(subscription_key)
)

주소 지오코딩

다음 코드 조각은 간단한 콘솔 애플리케이션에서 지정된 주소에 대한 경도 및 위도 좌표를 가져오는 방법을 보여 줍니다. 이 예제에서는 구독 키 자격 증명을 사용하여 MapsSearchClient를 인증합니다. demo.py의 경우

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding(query="15127 NE 24th Street, Redmond, WA 98052")
        if result.get('features', False):
            coordinates = result['features'][0]['geometry']['coordinates']
            longitude = coordinates[0]
            latitude = coordinates[1]

            print(longitude, latitude)
        else:
            print("No results")

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode()

이 샘플 코드는 Azure Maps 구독 키로 AzureKeyCredential을 인스턴스화한 다음, MapsSearchClient 개체를 인스턴스화하는 데 사용합니다. MapsSearchClient에서 제공하는 메서드는 요청을 Azure Maps REST 엔드포인트로 전달합니다. 결국 프로그램은 결과를 반복하고 각 결과에 대한 좌표를 출력합니다.

일괄 처리 지오코드 주소

이 샘플에서는 일괄 처리 검색 주소를 수행하는 방법을 보여 줍니다.

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode_batch():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding_batch({
          "batchItems": [
            {"query": "400 Broad St, Seattle, WA 98109"},
            {"query": "15127 NE 24th Street, Redmond, WA 98052"},
          ],
        },)

        if not result.get('batchItems', False):
            print("No batchItems in geocoding")
            return

        for item in result['batchItems']:
            if not item.get('features', False):
                print(f"No features in item: {item}")
                continue

            coordinates = item['features'][0]['geometry']['coordinates']
            longitude, latitude = coordinates
            print(longitude, latitude)

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode_batch()

역방향 주소 검색을 만들어 좌표 위치를 주소로 변환

좌표를 사람이 읽을 수 있는 주소로 변환할 수 있습니다. 이 프로세스를 역방향 지오코딩이라고도 합니다. 이는 GPS 피드를 사용하고 특정 좌표점에서 주소를 검색하려는 애플리케이션에 자주 사용됩니다.

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding(coordinates=[-122.138679, 47.630356])
        if result.get('features', False):
            props = result['features'][0].get('properties', {})
            if props and props.get('address', False):
                print(props['address'].get('formattedAddress', 'No formatted address found'))
            else:
                print("Address is None")
        else:
            print("No features available")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode()

역방향 지오코딩에 대한 일괄 처리 요청

이 샘플에서는 지정된 좌표를 일괄 처리하여 역방향 검색을 수행하는 방법을 보여 줍니다.

import os
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import HttpResponseError
from azure.maps.search import MapsSearchClient

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode_batch():
    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding_batch({
              "batchItems": [
                {"coordinates": [-122.349309, 47.620498]},
                {"coordinates": [-122.138679, 47.630356]},
              ],
            },)

        if result.get('batchItems', False):
            for idx, item in enumerate(result['batchItems']):
                features = item['features']
                if features:
                    props = features[0].get('properties', {})
                    if props and props.get('address', False):
                        print(
                            props['address'].get('formattedAddress', f'No formatted address for item {idx + 1} found'))
                    else:
                        print(f"Address {idx + 1} is None")
                else:
                    print(f"No features available for item {idx + 1}")
        else:
            print("No batch items found")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode_batch()

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

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

import os

from azure.core.exceptions import HttpResponseError
from azure.maps.search import Resolution
from azure.maps.search import BoundaryResultType


subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def get_polygon():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_polygon(
          coordinates=[-122.204141, 47.61256],
          result_type=BoundaryResultType.LOCALITY,
          resolution=Resolution.SMALL,
        )

        if not result.get('geometry', False):
            print("No geometry found")
            return

        print(result["geometry"])
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    get_polygon()

검색 및 렌더링에 V1 SDK 사용

검색 V1 및 Render V1 SDK를 사용하려면 V1 SDK 패키지 검색 페이지 및 Render V1 SDK 패키지를 참조하세요.

추가 정보

Python용 Azure SDK 미리 보기 설명서의 Azure Maps Search 패키지 클라이언트 라이브러리

다음을 통해 공유