Azure Maps .NET 用の位置情報クライアント ライブラリ - バージョン 1.0.0-beta.2

  • [アーティクル]

Azure Maps位置情報は、場所または目的地への位置情報を検索できるライブラリです。

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

作業の開始

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

NuGet を使用して .NET 用のクライアント ライブラリをインストールします。

dotnet add package Azure.Maps.Geolocation --prerelease

必須コンポーネント

Azure サブスクリプションとAzure Maps アカウントが必要です。

新しいAzure Maps アカウントを作成するには、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。 Azure CLI を使う例を次に示します。

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

クライアントを認証する

クライアントを認証するには、共有キー認証と Azure AD の 2 つの方法があります。

共有キー認証

  • [Azure Maps アカウント>の認証] タブに移動します
  • [共有キー認証] セクションのコピーPrimary KeyまたはSecondary Key下
// Create a MapsGeolocationClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsGeolocationClient client = new MapsGeolocationClient(credential);

Azure AD 認証

Azure Maps サービスと対話するには、 クラスのMapsGeolocationClientインスタンスを作成する必要があります。 Azure Identity ライブラリを使用すると、対応する Azure サービスを使用して Azure SDK クライアントを認証するための Azure Active Directory サポートを簡単に追加できます。

AAD 認証を使用するには、「 Azure Identity README 」の説明に従って環境変数を設定し、 で使用するインスタンスを作成 DefaultAzureCredential します MapsRouteClient。

また、Azure Mapsクライアント ID も必要です。これは、Azure Active Directory 認証セクションの [認証] タブの [クライアント ID] Azure Maps > ページ>から取得できます。

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(credential, clientId);

Shared Access Signature (SAS) 認証

Shared Access Signature (SAS) トークンは、JSON Web トークン (JWT) 形式を使用して作成された認証トークンであり、Azure Maps REST API に対するアプリケーションの認証を証明するために暗号化され署名されます。

SAS トークン認証を統合する前に、 と Azure.ResourceManager.Maps (バージョン1.1.0-beta.2以上) をインストールAzure.ResourceManagerする必要があります。

dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease

このコードでは、ResourceManager の両方に対して次の行Azure Mapsインポートする必要があります。

using Azure.Maps.Geolocation;
using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

その後、 List Sas API を使用して SAS トークンを取得し、 に MapsGeolocationClient割り当てることができます。 次のコード サンプルでは、特定のマップ アカウント リソースをフェッチし、コードの実行時に 1 日間の有効期限の SAS トークンを作成します。

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);

string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";

// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);

// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;

// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");

MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);

// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsGeolocationClient client = new MapsGeolocationClient(sasCredential);

主要な概念

MapsGeolocationClient は次の目的で設計されています。

  • geolocation SDK エンドポイントAzure Maps通信して、特定の IP アドレスから場所を取得する

サンプルの例の詳細を確認する

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、スレッド間であっても、クライアント インスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

使用例

サンプルを使用して、さまざまな API について理解することができます。

位置情報 API を呼び出す前に、最初に を MapsGeolocationClient インスタンス化します。 次の例では、AAD を使用してクライアント インスタンスを作成します。

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(credential, clientId);

場所の取得

このサービスは、指定された IP アドレスの ISO 国コードを返します。 開発者は、この情報を使用して、アプリケーションの表示元の地理的な場所に基づいて特定のコンテンツをブロックまたは変更できます。

//Get location by given IP address
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);

//Get location result country code
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");

詳細な例については、 位置情報のサンプル ページを参照してください。

トラブルシューティング

全般

Azure Maps サービスと対話すると、言語サービスによって返されるエラーは、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

たとえば、間違った IP アドレスを渡すと、"Bad Request" (HTTP 状態コード: 400) を示すエラーが返されます。

try
{
    // An invalid IP address
    IPAddress inValidIpAddress = IPAddress.Parse("2001:4898:80e8:b:123123213123");

    Response<CountryRegionResult> result = client.GetCountryCode(inValidIpAddress);
    // Do something with result ...
}
catch (FormatException e)
{
    Console.WriteLine(e.ToString());
}

次の手順

  • その他のコンテキストと追加のシナリオについては、「詳細なサンプル」を参照してください。

共同作成

このライブラリのビルド、テスト、および投稿の詳細については、 CONTRIBUTING.md を参照してください。

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

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

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

インプレッション数