Руководство разработчиков пакета SDK для C# ДЛЯ REST
Пакет SDK для Azure Maps C# поддерживает функциональные возможности, доступные в REST API Azure Maps, например поиск адреса, маршрутизация между различными координатами и получение географического расположения определенного IP-адреса. В этой статье представлен пакет SDK REST для C# с примерами, которые помогут вам приступить к созданию приложений с учетом расположения в C#, которые включают возможности Azure Maps.
Примечание.
Пакет SDK для Azure Maps C# поддерживает любую версию .NET, совместимую с .NET standard версии 2.0 или более поздней. На сайте Версии .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 для создания консольной программы MapsDemo с .NET 7.0. В качестве платформы можно использовать любую версию , совместимую с .NET standard 2.0.
dotnet new console -lang C# -n MapsDemo -f net7.0
cd MapsDemo
Установка необходимых пакетов
Чтобы использовать пакет SDK для C# для Azure Maps, необходимо установить необходимые пакеты. Каждая из служб Azure Maps, включая поиск, маршрутизацию, отрисовку и географическое расположение, находятся в собственном пакете. Так как пакет SDK для C# Azure Maps находится в общедоступной предварительной версии, необходимо добавить --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
Создание и проверка подлинности MapsSearchClient
Клиентский объект, используемый для доступа к API поиска Azure Maps, требует AzureKeyCredential либо объекта для проверки подлинности при использовании ключа подписки Azure Maps, либо TokenCredential объекта с идентификатором клиента Azure Maps при проверке подлинности с помощью идентификатора Microsoft Entra ID. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Maps".
Использование учетных данных Microsoft Entra
Вы можете пройти проверку подлинности с помощью идентификатора Microsoft Entra с помощью библиотеки удостоверений Azure. Чтобы использовать поставщик DefaultAzureCredential , необходимо установить клиентская библиотека удостоверений Azure для .NET:
dotnet add package Azure.Identity
Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Maps, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от Azure. Возвращаются идентификатор приложения (клиента), идентификатор каталога (клиента) и секрет клиента. Скопируйте эти значения и сохраните их в безопасном месте. Вам потребуется выполнить следующие действия.
Задайте значения идентификатора приложения (клиента), идентификатор каталога (клиента) и секрет клиента приложения Microsoft Entra и идентификатор клиента карты в качестве переменных среды:
| Переменная среды | Description |
|---|---|
| AZURE_CLIENT_ID | Идентификатор приложения (клиента) в зарегистрированном приложении |
| AZURE_CLIENT_SECRET | Значение секрета клиента в зарегистрированном приложении |
| AZURE_TENANT_ID | Идентификатор каталога (клиента) в зарегистрированном приложении |
| MAPS_CLIENT_ID | Идентификатор клиента в ресурсе Azure Map |
Теперь можно создать переменные среды в 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);
Внимание
Другие переменные среды, созданные в предыдущем фрагменте кода, не используемые в примере кода, требуются 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);
Географический код адреса
GetGeocoding Вызовите метод, чтобы получить координату адреса.
using System;
using Azure;
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);
Response<GeocodingResponse> searchResult = client.GetGeocoding(
"1 Microsoft Way, Redmond, WA 98052");
for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}
Адреса геокода пакетной службы
В этом примере показано, как выполнять пакетный поиск по адресу.
using System;
using Azure;
using Azure.Maps.Search;
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;
// Use Azure Maps subscription key authentication
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);
List<GeocodingQuery> queries = new List<GeocodingQuery>
{
new GeocodingQuery()
{
Query ="15171 NE 24th St, Redmond, WA 98052, United States"
},
new GeocodingQuery()
{
AddressLine = "400 Broad St"
},
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);
//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
{
Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
}
}
Обратный геокодирование координат
Координаты можно перевести на адреса, доступные для чтения с помощью человека. Этот процесс также называется обратным геокодированием.
using System;
using Azure;
using Azure.Maps.Search;
using Azure.Core.GeoJson;
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);
GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);
//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}
Пакетный обратный геокод набор координат
Поиск Azure Maps также предоставляет некоторые API пакетного запроса. API обратной геокодирования отправляет пакетные пакеты запросов в API обратного геокодирования с помощью одного вызова API. API позволяет вызывающей службе пакетировать до 100 запросов.
using System;
using Azure;
using Azure.Maps.Search;
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;
// Use Azure Maps subscription key authentication
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);
List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
new ReverseGeocodingQuery()
{
Coordinates = new GeoPosition(-122.349309, 47.620498)
},
new ReverseGeocodingQuery()
{
Coordinates = new GeoPosition(-122.138679, 47.630356),
ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
},
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}
Получение многоугольников для заданного расположения
В этом примере показано, как выполнять поиск многоугольников.
using System;
using Azure;
using Azure.Maps.Search;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Options;
// Use Azure Maps subscription key authentication
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);
GetPolygonOptions options = new GetPolygonOptions()
{
Coordinates = new GeoPosition(-122.204141, 47.61256),
ResultType = BoundaryResultTypeEnum.Locality,
Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);
var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
for (var j = 0; j < coorCount; j++)
{
Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
}
}
Использование пакетов SDK версии 1 для поиска и отрисовки
Дополнительные сведения об использовании службы поиска версии 1 см. в клиентской библиотеке поиска Azure Maps для .NET. Дополнительные сведения об использовании render версии 1 см . в клиентской библиотеке Azure Maps Render для .NET.