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

[アーティクル]
04/05/2023

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

免責事項

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 宛てに質問またはコメントをお送りください。

次の方法で共有

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

免責事項

作業の開始

前提条件

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

MapsSearchClient の作成と認証

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

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

主要な概念

クライアントの同期

非同期クライアント

例

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

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

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

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

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

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

Geometry 内を検索する

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

トラブルシューティング

全般

ログの記録

その他

次のステップ

その他のサンプルコード

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

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

免責事項

作業の開始

前提条件

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

MapsSearchClient の作成と認証

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

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

主要な概念

クライアントの同期

非同期クライアント

例

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

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

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

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

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

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

Geometry 内を検索する

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

トラブルシューティング

全般

ログの記録

その他

次のステップ

その他のサンプル コード

その他のドキュメント

共同作成

その他のリソース

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

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

その他のサンプルコード