Azure Mapas biblioteca de clientes de pesquisa para .NET – versão 1.0.0-beta.4

Azure Mapas Pesquisa é uma biblioteca que pode consultar locais, pontos de interesse ou pesquisar em uma área geométrica.

Código-fonte | Documentação | de referência da APIDocumentação | de referência da API RESTDocumentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes para .NET com o NuGet:

dotnet add package Azure.Maps.Search --prerelease

Pré-requisitos

Você deve ter uma assinatura do Azure e uma conta Azure Mapas.

Para criar uma nova conta Azure Mapas, você pode usar o Portal do Azure, Azure PowerShell ou a CLI do Azure. Aqui, está um exemplo usando a CLI do Azure:

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

Autenticar o cliente

Há duas maneiras de autenticar o cliente: autenticação de chave compartilhada e Azure AD.

Autenticação de Chave Compartilhada

• Acesse Azure Mapas guia Autenticação da conta >
• Copiar Primary Key ou Secondary Key na seção Autenticação de Chave Compartilhada

// Create a SearchClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsSearchClient client = new MapsSearchClient(credential);

Autenticação do Azure AD

Para interagir com o serviço Azure Mapas, você precisará criar uma instância da classe MapsSearchClient. A biblioteca de Identidade do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com seus serviços do Azure correspondentes.

Para usar a autenticação do AAD, defina TENANT_ID, CLIENT_IDe como CLIENT_SECRET variável de ambiente e chame DefaultAzureCredential() o método para obter a credencial. CLIENT_IDe CLIENT_SECRET são a ID da entidade de serviço e o segredo que podem acessar Azure Mapas conta.

Também precisamos de Azure Mapas ID do cliente que possa obter da página Azure Mapas guia >> Autenticação "ID do cliente" na seção Autenticação do Azure Active Directory.

// Create a MapsSearchClient that will authenticate through AAD
DefaultAzureCredential credential = new DefaultAzureCredential();
string clientId = "<My Map Account Client Id>";
MapsSearchClient client = new MapsSearchClient(credential, clientId);

Autenticação SAS (Assinatura de Acesso Compartilhado)

Os tokens de SAS (assinatura de acesso compartilhado) são tokens de autenticação criados usando o formato JWT (token Web JSON) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Mapas.

Antes de integrar a autenticação de token SAS, precisamos instalar Azure.ResourceManager e Azure.ResourceManager.Maps (versão 1.1.0-beta.2 ou superior):

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

No código, precisamos importar as seguintes linhas para Azure Mapas SDK e ResourceManager:

using Azure.Core.GeoJson;
using Azure.Maps.Search;
using Azure.Maps.Search.Models;

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

Em seguida, podemos obter o token SAS por meio da API Sas de Lista e atribuí-lo a MapsSearchClient. No exemplo de código a seguir, buscamos um recurso de conta de mapas específico e criamos um token SAS para um dia de expiração quando o código é executado.

// 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);
MapsSearchClient client = new MapsSearchClient(sasCredential);

Principais conceitos

O MapsSearchClient foi projetado para:

• Comunicar-se com Azure Mapas ponto de extremidade para consultar endereços ou pontos de localização
• Comunique-se com Azure Mapas ponto de extremidade para solicitar os dados de geometria, como uma estrutura de tópicos de cidade ou país para um conjunto de entidades
• Comunique-se com Azure Mapas ponto de extremidade para executar uma pesquisa de formulário livre dentro de uma única geometria ou muitos deles

Saiba mais exibindo nossos exemplos

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | clienteAcessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

Você pode se familiarizar com diferentes APIs usando nossos exemplos.

Exemplo obter polígonos

// Get Addresses
Response<SearchAddressResult> searchResult = await client.SearchAddressAsync("Seattle");

// Extract geometry ids from addresses
string geometry0Id = searchResult.Value.Results[0].DataSources.Geometry.Id;
string geometry1Id = searchResult.Value.Results[1].DataSources.Geometry.Id;

// Extract position coordinates
GeoPosition positionCoordinates = searchResult.Value.Results[0].Position;

// Get polygons from geometry ids
PolygonResult polygonResponse = await client.GetPolygonsAsync(new[] { geometry0Id, geometry1Id });

// Get polygons objects
IReadOnlyList<PolygonObject> polygonList = polygonResponse.Polygons;

Exemplo de pesquisa difusa

Response<SearchAddressResult> fuzzySearchResponse = await client.FuzzySearchAsync("coffee", new FuzzySearchOptions
{
    Coordinates = new GeoPosition(121.56, 25.04),
    Language = SearchLanguage.EnglishUsa
});

// Print out the possible results
Console.WriteLine("The possible results for coffee shop:");
foreach (SearchAddressResultItem result in fuzzySearchResponse.Value.Results)
{
    Console.WriteLine("Coordinate: {0}, Address: {1}",
        result.Position, result.Address.FreeformAddress);
}

Exemplo de pesquisa inversa endereço entre ruas

var reverseResult = await client.ReverseSearchCrossStreetAddressAsync(new ReverseSearchCrossStreetOptions
{
    Coordinates = new GeoPosition(121.0, 24.0),
    Language = SearchLanguage.EnglishUsa
});

Exemplo de endereço estruturado de pesquisa

var address = new StructuredAddress
{
    CountryCode = "US",
    StreetNumber = "15127",
    StreetName = "NE 24th Street",
    Municipality = "Redmond",
    CountrySubdivision = "WA",
    PostalCode = "98052"
};
Response<SearchAddressResult> searchResult = await client.SearchStructuredAddressAsync(address);

SearchAddressResultItem resultItem = searchResult.Value.Results[0];
Console.WriteLine("First result - Coordinate: {0}, Address: {1}",
    resultItem.Position, resultItem.Address.FreeformAddress);

Exemplo de pesquisa dentro da geometria

GeoPolygon sfPolygon = new GeoPolygon(new[]
{
    new GeoPosition(-122.43576049804686, 37.752415234354402),
    new GeoPosition(-122.4330139160, 37.706604725423119),
    new GeoPosition(-122.36434936523438, 37.712059855877314),
    new GeoPosition(-122.43576049804686, 37.7524152343544)
});

GeoPolygon taipeiPolygon = new GeoPolygon(new[]
{
    new GeoPosition(121.56, 25.04),
    new GeoPosition(121.565, 25.04),
    new GeoPosition(121.565, 25.045),
    new GeoPosition(121.56, 25.045),
    new GeoPosition(121.56, 25.04)
});

// Search coffee shop in Both polygons, return results in en-US
Response<SearchAddressResult> searchResponse = await client.SearchInsideGeometryAsync("coffee", new GeoCollection(new[] { sfPolygon, taipeiPolygon }), new SearchInsideGeometryOptions
{
    Language = SearchLanguage.EnglishUsa
});

// Get Taipei Cafe and San Francisco cafe and print first place
SearchAddressResultItem taipeiCafe = searchResponse.Value.Results.Where(addressItem => addressItem.SearchAddressResultType == "POI" && addressItem.Address.Municipality == "Taipei City").First();
SearchAddressResultItem sfCafe = searchResponse.Value.Results.Where(addressItem => addressItem.SearchAddressResultType == "POI" && addressItem.Address.Municipality == "San Francisco").First();

Console.WriteLine("Possible Coffee shop in the Polygons:");
Console.WriteLine("Coffee shop address in Taipei: {0}", taipeiCafe.Address.FreeformAddress);
Console.WriteLine("Coffee shop address in San Francisco: {0}", sfCafe.Address.FreeformAddress);

Exemplo de endereço de pesquisa

Response<SearchAddressResult> searchResult = await client.SearchAddressAsync("Seattle");

SearchAddressResultItem resultItem = searchResult.Value.Results[0];
Console.WriteLine("First result - Coordinate: {0}, Address: {1}",
    resultItem.Position, resultItem.Address.FreeformAddress);

Solução de problemas

Geral

Quando você interage com os Serviços de Azure Mapas, os erros retornados pelo serviço de Linguagem correspondem aos mesmos códigos http status retornados para solicitações da API REST.

Por exemplo, se você tentar pesquisar com coordenadas inválidas, um erro será retornado, indicando "Solicitação Incorreta".400

Próximas etapas

• Mais exemplos

Participante

Consulte a CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite <cla.microsoft.com>.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.