Python 用 Azure Maps Search Package クライアント ライブラリ - バージョン 1.0.0b2

このパッケージには、Azure Maps Services for Search 用の Python SDK が含まれています。 Azure Maps サービスの詳細については、こちらを参照してください

ソースコード | API リファレンス ドキュメント | 製品ドキュメント

免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、https://github.com/Azure/azure-sdk-for-python/issues/20691 を参照してください

作業の開始

前提条件

• このパッケージを使用するには、Python 3.6 以降が必要です。
• Azure サブスクリプションとAzure Maps アカウント。
• デプロイされた Maps Services リソース。 リソースは、 Azure Portal または Azure CLI を使用して作成できます。

Azure CLI を使用する場合は、任意の と <account-name> を置き換え<resource-group-name>、 パラメーターを使用してニーズに基づいて適切な価格レベルを<sku-name>選択します。 詳細については、このページを参照してください。

az maps account create --resource-group <resource-group-name> --account-name <account-name> --sku <sku-name>

パッケージをインストールする

Azure Maps Service Search SDK をインストールします。

pip install azure-maps-search

MapsSearchClient の作成と認証

Azure Maps Search API にアクセスするためのクライアント オブジェクトを作成するには、資格情報オブジェクトが必要です。 Azure Maps Search クライアントでは、認証する 2 つの方法もサポートされています。

1. サブスクリプション キーの資格情報を使用して認証する

Azure Maps サブスクリプション キーを使用して認証できます。 Azure Maps サブスクリプション キーが作成されたら、キーの値を環境変数 として設定しますAZURE_SUBSCRIPTION_KEY。 次に、 credential パラメーターとして を AzureKeyCredential のインスタンスに渡しますAZURE_SUBSCRIPTION_KEY。

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

credential = AzureKeyCredential(os.environ.get("AZURE_SUBSCRIPTION_KEY"))

search_client = MapsSearchClient(
    credential=credential,
)

2. Azure Active Directory 資格情報を使用して認証する

Azure Id ライブラリを使用して、Azure Active Directory (AAD) トークン資格情報を使用して認証できます。 AAD を使用した認証には、いくつかの初期セットアップが必要です。

• azure-identity をインストールする
• 新しい AAD アプリケーションを登録する
• 適切なロールをサービス プリンシパルに割り当てることで、Azure Mapsへのアクセス権を付与します。 認証の管理に関するページを参照してください。

セットアップ後、使用する資格情報azure.identityの種類を選択できます。 たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。

次に、AAD アプリケーションのクライアント ID、テナント ID、およびクライアント シークレットの値を環境変数として設定します。 AZURE_CLIENT_IDAZURE_TENANT_IDAZURE_CLIENT_SECRET

また、クライアント オプションで を指定して、使用するAzure Maps リソースを指定するclientId必要があります。 Azure Maps リソース クライアント ID は、Azure Maps リソースの認証セクションにあります。 検索方法については、 ドキュメント を参照してください。

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

credential = DefaultAzureCredential()
search_client = MapsSearchClient(credential=credential)

主要な概念

Python 用Azure Maps Search クライアント ライブラリを使用すると、専用のクライアント オブジェクトを使用して各コンポーネントを操作できます。

クライアントの同期

MapsSearchClientは、Python 用の Azure Maps Search クライアント ライブラリを使用する開発者向けの主要なクライアントです。 クラスをMapsSearchClient初期化したら、このクライアント オブジェクトのメソッドを調べて、アクセスできるAzure Maps Search Serviceのさまざまな機能を理解できます。

非同期クライアント

このライブラリには、Python 3.5 以降でサポートされている完全な非同期 API が含まれています。 これを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。

非同期クライアントと資格情報は、不要になったら閉じる必要があります。 これらのオブジェクトは非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。

例

次のセクションでは、最も一般的なAzure Maps検索タスクの一部をカバーするいくつかのコード スニペットを示します。

• 住所の緯度と経度の座標を要求する

• 住所または目的地を検索する

• 住所の逆引き検索を行って座標位置を番地に変換する

• 人間が理解できるクロスストリートに座標位置を変換する

• param と batchid を使用して非同期あいまい検索バッチを取得する

• あいまい検索バッチ同期の取得に失敗する

• Geometry 内を検索する

• 検索用に存在するライブラリを操作する

住所の緯度と経度の座標を要求する

認証されたクライアントを使用して、アドレスを緯度と経度の座標に変換できます。 このプロセスはジオコーディングとも呼ばれています。 応答では、座標が返されるだけでなく、番地、郵便番号、地方自治体、国または地域の情報などの詳細な住所プロパティも返されます。

from azure.maps.search import MapsSearchClient

search_result = client.search_address("400 Broad, Seattle");

住所または目的地を検索する

あいまい検索を使用して、住所または目的地 (POI) を検索できます。 次の例では、特定の国のFrance範囲 (この例では) を検索pizzaする方法を降格します。

from azure.maps.search import MapsSearchClient

fuzzy_search_result = client.fuzzy_search(query: "pizza", country_filter: "fr" );

result_address = fuzzy_search_result.results[0].address

住所の逆引き検索を行って座標位置を番地に変換する

座標を人間が判読できる番地に変換できます。 このプロセスは逆ジオコーディングとも呼ばれます。 これは、GPS フィードを使用し、特定の座標ポイントでアドレスを検出するアプリケーションでよく使用されます。

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_address(coordinates=coordinates);

result_summary = reverse_search_result.summary

人間が理解できるクロスストリートに座標位置を変換する

交差点住所の逆引き検索 API を使用して、座標位置を人間が理解できる交差道路に変換する 多くの場合、これは、デバイスまたはアセットから GPS フィードを受信し、座標が配置されている場所を知る必要があるアプリケーションをトラッキングする場合に必要です。

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_cross_street_address(coordinates=coordinates);

result_address = reverse_search_result.results[0].address

param と batchid を使用して非同期あいまい検索バッチを取得する

このサンプルでは、非同期バッチ メソッドを使用して、場所と lat/lon によるあいまい検索を実行する方法を示します。 この関数は、 と batch_id の両方search_queriesを受け入れ、オブジェクトをAsyncLRO返しています。 ここでは batch_id 、 を使用して、過去 14 日間の LRO オブジェクトを取得できます。

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        search_queries=[
            "350 5th Ave, New York, NY 10118&limit=1",
            "400 Broad St, Seattle, WA 98109&limit=6"
        ]
    )

batch_id = result.batch_id

メソッド begin_fuzzy_search_batch() は、 パラメーターとしても受け入れます batch_id 。 ここでは batch_id 、 を使用して、過去 14 日間の LRO オブジェクトを取得できます。

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        batch_id=batch_id
    )

result = result.response

あいまい検索バッチ同期の取得に失敗する

このサンプルでは、fuzzy_search_batchの検索でエラーがあるかどうかを確認する方法を示します。

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

result = maps_search_client.fuzzy_search_batch(
    search_queries=[
        "350 5th Ave, New York, NY 10118&limit=1",
        "400 Broad St, Seattle, WA 98109&lim"
    ]
)
for item in result.items:
    count = 0
    if item.response.error is not None:
        count = count+1
        print(f"Error: {item.response.error.message}")
print(f"There are total of {count} search queries failed.")

Geometry 内を検索する

このサンプルでは、GeoJson オブジェクトを使用した入力として、 や 複数の異なるジオメトリなど pizza 、指定されたターゲットによってジオメトリ内で検索を実行する方法を示します。

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

geo_json_obj1 = {
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [[
                    [-122.143035,47.653536],
                    [-122.187164,47.617556],
                    [-122.114981,47.570599],
                    [-122.132756,47.654009],
                    [-122.143035,47.653536]
                    ]]
            },
            "properties": {}
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [-122.126986,47.639754]
            },
            "properties": {
                "subType": "Circle",
                "radius": 100
            }
        }
    ]
}
result1 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_json_obj1
)
print("Search inside geometry with standard GeoJson object as input, FeatureCollection:")
print(result1)

検索用に存在するライブラリを操作する

このサンプルでは、 などの他の既存のパッケージを操作して、 などの shapely 指定されたターゲット pizzaによってジオメトリ内で検索を実行する方法を示します。

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

from shapely.geometry import Polygon

geo_interface_obj = Polygon([
    [-122.43576049804686, 37.7524152343544],
    [-122.43301391601562, 37.70660472542312],
    [-122.36434936523438, 37.712059855877314],
    [-122.43576049804686, 37.7524152343544]
])

result3 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_interface_obj
)
print("Search inside geometry with Polygon from third party library `shapely` with geo_interface as result 3:")
print(result2)

トラブルシューティング

全般

Maps Search クライアントでは 、Azure Core で定義されている例外が発生します。

このリストは、スローされた例外をキャッチするための参照に使用できます。 例外の特定のエラー コードを取得するには、 属性 ( error_code つまり) exception.error_codeを使用します。

ログの記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。

要求/応答本文、未変換ヘッダーなど、詳細な DEBUG レベルのログは、 引数を使用してクライアントで logging_enable 有効にすることができます。

import sys
import logging
from azure.maps.search import MapsSearchClient

# Create a logger for the 'azure.maps.search' SDK
logger = logging.getLogger('azure.maps.search')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

service_client.get_service_stats(logging_enable=True)

その他

まだ問題が発生していますか? バグが発生した場合、または提案がある場合は、プロジェクトの [問題 ] セクションで問題を報告してください。

次のステップ

その他のサンプル コード

Maps Search のサンプル (非同期バージョンのサンプル) の使用を開始します。

SDK の GitHub リポジトリには、いくつかのAzure Maps Search Python SDK サンプルが用意されています。 これらのサンプルでは、Maps Search の操作中に一般的に発生するその他のシナリオのサンプル コードを提供します

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-search --pre

python samples/sample_authentication.py
python sample/sample_fuzzy_search.py
python samples/sample_get_point_of_interest_categories.py
python samples/sample_reverse_search_address.py
python samples/sample_reverse_search_cross_street_address.py
python samples/sample_search_nearby_point_of_interest.py
python samples/sample_search_point_of_interest_category.py
python samples/sample_search_point_of_interest.py
python samples/sample_search_structured_address.py

注: --pre フラグは必要に応じて追加できます。これは、 のプレリリースバージョンと開発バージョンを pip install含むものです。 既定では、 pip 安定したバージョンのみが検索されます。

詳細については、サンプルの概要に関するページを参照してください

その他のドキュメント

Azure Maps Search に関するより広範なドキュメントについては、docs.microsoft.com に関する Azure Maps Search のドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。