Руководство разработчиков пакета SDK для C# ДЛЯ REST

Пакет SDK для C# для Azure Карты поддерживает функциональные возможности, доступные в Rest API Azure Карты, например поиск адреса, маршрутизация между разными координатами и получение географического расположения определенного IP-адреса. В этой статье представлен пакет SDK REST для C# с примерами, которые помогут приступить к созданию приложений с учетом расположения в C#, которые включают возможности Azure Карты.

Примечание.

Пакет SDK для C# для Azure Карты поддерживает любую версию .NET, совместимую с .NET standard версии 2.0 или более поздней. На сайте Версии .NET Standard доступна интерактивная таблица.

Необходимые компоненты

• Учетная запись azure Карты.
• Ключ подписки или другая форма проверки подлинности с помощью Azure Карты.
• .NET standard версии 2.0 или более поздней.

Совет

Вы можете создать учетную запись Azure Карты программным способом. Ниже приведен пример с помощью 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 Карты, необходимо установить необходимые пакеты. Каждая из служб Azure Карты, включая поиск, маршрутизацию, отрисовку и геолокацию, находятся в собственном пакете. Так как пакет SDK для C# azure Карты находится в общедоступной предварительной версии, необходимо добавить --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

Имя службы	Пакет NuGet	Образцы
Поиск	Azure. Карты. Поиск	Примеры поиска
Маршрутизация	Azure. Карты. Маршрутизации	Примеры маршрутизации
Отрисовка	Azure. Карты. Визуализации	Пример отрисовки
Геопозиционирование	Azure. Карты. Географического расположения	Пример географического расположения

Создание и проверка подлинности Карты SearchClient

Клиентский объект, используемый для доступа к API поиска Azure Карты, требует AzureKeyCredential проверки подлинности объекта при использовании ключа подписки Azure Карты или TokenCredential объекта с идентификатором клиента Azure Карты при проверке подлинности с помощью идентификатора Microsoft Entra. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Карты".

Использование учетных данных Microsoft Entra

Вы можете пройти проверку подлинности с помощью идентификатора Microsoft Entra с помощью библиотеки удостоверений Azure. Чтобы использовать поставщик DefaultAzureCredential , необходимо установить клиентская библиотека удостоверений Azure для .NET:

dotnet add package Azure.Identity 

Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Карты, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от 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 Карты. Ключ подписки можно найти в разделе "Проверка подлинности" в учетной записи azure Карты, как показано на следующем снимке экрана:

Теперь можно создать переменные среды в 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); 

Нечеткий поиск сущности

В следующем фрагменте кода показано, как в простом консольном приложении импортировать Azure.Maps.Search пакет и выполнить нечеткий поиск в "Starbucks" недалеко от Сиэтла. В Program.cs:

using System;
using Azure; 
using Azure.Core.GeoJson; 
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); 

SearchAddressResult searchResult = client.FuzzySearch( 
    "Starbucks", new FuzzySearchOptions 
    { 
        Coordinates = new GeoPosition(-122.34255, 47.61010), 
        Language = SearchLanguage.EnglishUsa 
    }); 


// Print the search results 
foreach (var result in searchResult.Results) 
{ 
    Console.WriteLine($""" 
        * {result.Address.StreetNumber} {result.Address.StreetName} 
          {result.Address.Municipality} {result.Address.CountryCode} {result.Address.PostalCode} 
          Coordinate: ({result.Position.Latitude:F4}, {result.Position.Longitude:F4}) 
        """); 
} 

В приведенном выше фрагменте кода показано, как создать MapsSearchClient объект с помощью учетных данных Azure, а затем использовать его метод FuzzySearch , передавая в точку интереса (POI) имя "Starbucks" и координаты GeoPosition(-122.31, 47.61). Пакеты SDK и отправляют результаты в конечные точки REST Azure Карты. Когда результаты поиска возвращаются, они записываются на экран с помощью Console.WriteLine.

Используются следующие библиотеки:

1. Azure.Maps.Search требуется для MapsSearchClient класса.
2. Azure.Maps.Search.Models требуется для SearchAddressResult класса.
3. Azure.Core.GeoJson требуется для структуры, GeoPosition используемой классом FuzzySearchOptions .

Чтобы запустить приложение, перейдите в папку проекта и выполните в dotnet run PowerShell:

dotnet run 

Вы увидите список адресов и координат Starbucks:

* 1912 Pike Place 
  Seattle US 98101 
  Coordinate: 47.61016, -122.34248 
* 2118 Westlake Avenue 
  Seattle US 98121 
  Coordinate: 47.61731, -122.33782 
* 2601 Elliott Avenue 
  Seattle US 98121 
  Coordinate: 47.61426, -122.35261 
* 1730 Howell Street 
  Seattle US 98101 
  Coordinate: 47.61716, -122.3298 
* 220 1st Avenue South 
  Seattle US 98104 
  Coordinate: 47.60027, -122.3338 
* 400 Occidental Avenue South 
  Seattle US 98104 
  Coordinate: 47.5991, -122.33278 
* 1600 East Olive Way 
  Seattle US 98102 
  Coordinate: 47.61948, -122.32505 
* 500 Mercer Street 
  Seattle US 98109 
  Coordinate: 47.62501, -122.34687 
* 505 5Th Ave S 
  Seattle US 98104 
  Coordinate: 47.59768, -122.32849 
* 425 Queen Anne Avenue North 
  Seattle US 98109 
  Coordinate: 47.62301, -122.3571 

Поиск адреса

SearchAddress Вызовите метод, чтобы получить координату адреса. Измените основную программу из примера следующим образом:

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

SearchAddressResult searchResult = client.SearchAddress(
    "1301 Alaskan Way, Seattle, WA 98101, US");

if (searchResult.Results.Count > 0) 
{
    SearchAddressResultItem result = searchResult.Results.First(); 
    Console.WriteLine($"The Coordinate: ({result.Position.Latitude:F4}, {result.Position.Longitude:F4})"); 
}

Метод SearchAddress возвращает результаты, упорядоченные по оценке достоверности и так как searchResult.Results.First() используется, возвращаются только координаты первого результата.

Пакетный обратный поиск

Поиск Карты Azure также предоставляет некоторые методы пакетного запроса. Эти методы возвращают объекты Long Running Operations (LRO). Запросы могут не сразу возвращать все результаты, чтобы пользователи могли ждать завершения или периодически запрашивать результат. В следующем примере показано, как вызвать пакетные методы обратного поиска:

var queries = new List<ReverseSearchAddressQuery>() 
{ 
    new ReverseSearchAddressQuery(new ReverseSearchOptions() 
    { 
        Coordinates = new GeoPosition(2.294911, 48.858561) 
    }), 
    new ReverseSearchAddressQuery(new ReverseSearchOptions() 
    { 
        Coordinates = new GeoPosition(-122.127896, 47.639765), 
        RadiusInMeters = 5000 
    }) 
};

В приведенном выше примере два запроса передаются пакетному запросу обратного поиска. Чтобы получить результаты LRO, у вас есть несколько вариантов. Первый вариант — передать WaitUntil.Completed методу. Запрос ожидает завершения всех запросов и возвращает результаты:

// Wait until the LRO return batch results 
Response<ReverseSearchAddressBatchOperation> waitUntilCompletedResults = client.ReverseSearchAddressBatch(WaitUntil.Completed, queries); 

// Print the result addresses 
printReverseBatchAddresses(waitUntilCompletedResults.Value); 

Другим вариантом является передача WaitUntil.Started. Запрос возвращается немедленно, и необходимо вручную опрашивать результаты:

// Manual polling the batch results 
Response<ReverseSearchAddressBatchOperation> manualPollingOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

// Keep polling until we get the results
while (true)
{
    manualPollingOperation.Value.UpdateStatus();
    if (manualPollingOperation.Value.HasCompleted) break;
    Task.Delay(1000);
}
printReverseBatchAddresses(manualPollingOperation);

Мы также можем вызвать WaitUntilCompletion() явное ожидание результата:

Response<ReverseSearchAddressBatchOperation> manualPollingResult = manualPollingResults.WaitUntilCompleted();

printReverseBatchAddresses(manualPollingResult.Value);

Третий метод требует, чтобы идентификатор операции получил результаты, который кэшируется на стороне сервера в течение 14 дней:

  ReverseSearchAddressBatchOperation longRunningOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

  // Get batch results by ID 
  string operationId = longRunningOperation.Value.Id;

  // After the LRO completes, create a new operation
  // to get the results from the server
  ReverseSearchAddressBatchOperation newOperation = new ReverseSearchAddressBatchOperation(client, operationId);
  Response<ReverseSearchAddressBatchOperation> newOperationResult = newOperation.WaitForCompletion();

printReverseBatchAddresses(newOperationResult);

Полный код для пакетного поиска обратного адреса с идентификатором операции:

using system;
using Azure;
using Azure.Core.GeoJson;
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); 

var queries = new List<ReverseSearchAddressQuery>()
{
    new ReverseSearchAddressQuery(new ReverseSearchOptions()
    {
        Coordinates = new GeoPosition(2.294911, 48.858561)
    }),
    new ReverseSearchAddressQuery(new ReverseSearchOptions()
    {
        Coordinates = new GeoPosition(-122.127896, 47.639765),
        RadiusInMeters = 5000
    })
};

// Manual polling the batch results
ReverseSearchAddressBatchOperation longRunningOperation = client.ReverseSearchAddressBatch(WaitUntil.Started, queries);

// Get batch results by ID
string operationId = longRunningOperation.Id;

// A few days later, create a new operation and get the result from server
ReverseSearchAddressBatchOperation newOperation = new ReverseSearchAddressBatchOperation(client, operationId);
Response<ReverseSearchAddressBatchResult> newOperationResult = newOperation.WaitForCompletion();
printReverseBatchAddresses(newOperationResult.Value);
void printReverseBatchAddresses(ReverseSearchAddressBatchResult batchResult)
{
    // Print the search results
    for (int i = 0; i < batchResult.Results.Count; i++)
    {
        Console.WriteLine($"Possible addresses for query {i}:");
        var result = batchResult.Results[i];
        foreach (var address in result.Addresses)
        {
            Console.WriteLine($"{address.Address.FreeformAddress}");
        }
    }
}

Дополнительная информация:

Azure.Карты Пространство имен в документации по .NET.