Migrate Azure Maps Search 1.0 APIs

Pesquisa A versão da API 2026-01-01 substitui a versão 1.0 da Search API. A versão mais recente introduz endpoints específicos para tarefas, intenções mais claras e melhora a escalabilidade. Este artigo explica como migrar integrações existentes do Search v1.

Importante

A versão 1.0 da API de Pesquisa do Azure Maps foi substituída pela versão 2026-01-01. Enquanto o Search v1 continuar a funcionar, os novos desenvolvimentos deverão usar a mais recente API de Pesquisa para aceder a endpoints específicos de tarefas, desempenho melhorado e suporte a longo prazo. Para evitar futuras interrupções no serviço, migre as integrações existentes do Search v1 para Search 2026-01-01.

Mapeamento de equivalência de API

Purpose API de pesquisa v1 Pesquisa API 2026-01-01
Geocodificação direta Obter Endereço de Pesquisa Obtenha Geocodificação
Morada Obter Pesquisa Fuzzy (final) Obtenha Geocodificação
Preenchimento Automático Get Search Fuzzy (sugestão instantânea) Obtenha o preenchimento automático do geocódigo
Geocodificação em lote Obter Lote de Endereço de Pesquisa Obtenha Geocoding Batch
Geocodificação reversa Obter Reverso do Endereço de Pesquisa Obtenha Geocodificação Inversa
Inversão em lote Obter Endereço de Pesquisa Batch Inverso Obtenha o Batch de Geocodificação Reversa
Boundaries Obter Polígono de Pesquisa Adquirir Polygon

Diferenças notáveis

As APIs de Search 2026-01-01 introduzem endpoints específicos de intenção, semântica de requisições mais clara e um comportamento de resultados mais rigoroso em comparação com à Search v1. A tabela seguinte resume as diferenças mais importantes a ter em conta ao migrar.

Area Pesquisa v1 Pesquisa 2026-01-01
Conceção da API Endpoints de múltiplos propósitos (por exemplo, Pesquisa Fuzzy utilizada tanto para autocompletar como para pesquisa final) APIs específicas de intenção (por exemplo, Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding)
Comportamento de autocompletamento Implementado usando Search Fuzzy com typeahead=true API dedicada Get Geocode Autocomplete
Geocodificação final Muitas vezes dependia de correspondência difusa para dar uma "melhor estimativa" O Get Geocoding prioriza a correção e pode não dar resultados
Resultados vazios Muitas vezes regressava a um combate de baixa confiança Pode devolver HTTP 200 com um array de resultados vazio quando não for encontrada correspondência
Gestão da confiança dos resultados A confiança e a qualidade do jogo estavam frequentemente implícitas Confiança, códigos de correspondência e tipo de entidade são explícitos e devem ser avaliados
Tratamento da hierarquia de entidades Resultados difusos podem devolver entidades vagamente relacionadas Os resultados podem ser agrupados para uma entidade de nível superior (por exemplo, condado ou região) e devem ser filtrados por tipo de entidade
Utilização em lote APIs em lote disponíveis, mas muitas vezes opcionais APIs em lote são recomendadas para fluxos de trabalho de grande escala e de enriquecimento
Fluxos de trabalho de enriquecimento de dados Frequentemente retentado com pesquisa difusa Suporta explicitamente padrões de enriquecimento com sinalização de não-correspondência mais clara
Estrutura do URL Versionado em /search/* endpoints Endpoints simplificados e específicos de cada tarefa (por exemplo, /geocode, /reverseGeocode)
Extensibilidade futura Capacidade limitada de evoluir comportamentos individuais As APIs evoluem independentemente com base na intenção (autocompletamento, geocodificação, inverso)

Diferenças no uso das transações

A Pesquisa 2026-01-01 utiliza APIs específicas de intenção, que podem alterar a forma como as transações são consumidas em comparação com a Pesquisa v1.

Na Search v1, um único endpoint versátil era frequentemente usado tanto para autocompletar como para a geocodificação final. No Search 2026-01-01, estes cenários são separados em APIs distintas, o que ajuda a alinhar o uso das transações mais de perto com a intenção do utilizador.

Considerações chave na migração:

  • Utilize Get Geocode Autocomplete apenas para interações de utilizadores com sugestões automáticas.
  • Use o Get Geocoding apenas quando for necessário um endereço ou local final.
  • Evite chamar repetidamente APIs finais de geocodificação durante cenários de digitação interativa.
  • Prefiro APIs em lote para fluxos de trabalho de geocodificação em grande escala ou em segundo plano.

Para detalhes sobre como as transações Azure Maps são calculadas e faturadas, consulte Compreender as transações Azure Maps.

Alterações na gestão dos resultados

A Pesquisa 2026-01-01 dá maior ênfase à exatidão dos resultados e à sinalização explícita de correspondência do que a Pesquisa v1.

Ao migrar, revise como a sua aplicação interpreta as respostas de pesquisa.

  • Um pedido bem-sucedido pode não devolver resultados quando não for encontrada correspondência adequada. Para mais informações, consulte Compreender resultados vazios de geocodificação.
  • Correspondências de baixa confiança ou ligeiramente relacionadas têm menos probabilidade de serem devolvidas automaticamente.
  • As aplicações devem avaliar valores de confiança, códigos de correspondência e tipos de entidades ao determinar se um resultado é aceitável. Para mais informações, consulte Melhorar a qualidade dos resultados para geocodificação baseada em consultas.
  • Se uma entidade solicitada não for encontrada, o serviço pode devolver uma entidade de nível superior na hierarquia de endereços (por exemplo, uma região em vez de uma cidade). Para mais informações sobre avaliação da qualidade dos resultados e validação de que os tipos de entidades retornadas correspondem ao cenário de pesquisa pretendido, consulte Melhores práticas para geocodificação direta em Melhores práticas para o serviço Azure Maps Search.

Não presuma que todos os pedidos bem-sucedidos devolvem um resultado utilizável. É necessária uma avaliação explícita dos resultados para manter a qualidade dos dados.

Comparação de exemplos de pedidos e respostas

Os exemplos seguintes mostram como os pedidos comuns do Azure Maps Search v1 correspondem aos seus equivalentes na Search API 2026-01-01. Cada exemplo concentra-se na mesma intenção do utilizador, realçando a transição de endpoints v1 multifuncionais para APIs específicas para determinadas intenções.

Geocodificação direta (coordenadas → endereço)

Na Search API v1, a geocodificação direta era normalmente realizada usando os endpoints Search Address ou Search Fuzzy. Na Search API 2026-01-01, esta funcionalidade é fornecida pela Get Geocoding API, que resolve introdução de endereços estruturados ou não estruturados em coordenadas geográficas usando um endpoint dedicado e específico para a intenção.

Pesquisa v1 – Procurar Endereço

GET https://atlas.microsoft.com/search/address/json
  ?api-version=1.0
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Pesquisa 2026-01-01 – Obter Geocodificação

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Pesquisa de endereço ou local aproximada (resultado final)

A API de Pesquisa v1 expôs endereços difusos e resolução de posições através de um único endpoint de Pesquisa Fuzzy. Na Search API 2026-01-01, este comportamento é substituído pelo Get Geocoding, que lida com consultas de endereço e colocação livres, separando os cenários de autopreenchimento e sugestão em APIs distintas.

Pesquisa v1 – Pesquisa Fuzzy

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=Space%20Needle

Pesquisa 2026-01-01 – Obter Geocodificação

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=Space%20Needle

Sugestões de autocompletar / digitar antecipadamente

Na Search API v1, o comportamento de digitação antecipada era ativado ao definir typeahead=true no endpoint [Search Fuzzy]. Na Search API 2026-01-01, os cenários de autopreenchimento são tratados explicitamente pela API Get Geocode Autocomplete , que está otimizada para entrada interativa do utilizador e sugestões em tempo real.

Pesquisa v1 – Pesquisa Fuzzy (uso por digitação antecipada)

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=1%20Mic
  &typeahead=true

Pesquisa 2026-01-01-01 – Obtenha Autocomplete de Geocódigo

GET https://atlas.microsoft.com/geocode:autocomplete
  ?api-version=2026-01-01
  &query=1%20Mic
  &coordinates=-122.129,47.639

Para mais informações, consulte Introdução à API de Autopreenchimento do Geocódigo do Azure Maps.

Geocodificação direta por lote

A API de Pesquisa v1 suportava a resolução de endereços por lote através do endpoint de Pesquisa de Endereços em Lote. Na Search API 2026-01-01, esta funcionalidade é fornecida pelo Get Geocoding Batch, permitindo que múltiplas consultas a endereços sejam submetidas e processadas num único pedido para cargas de trabalho em grande escala ou em segundo plano.

Pesquisa v1 – Processamento de Lote de Endereços de Pesquisa

POST https://atlas.microsoft.com/search/address/batch/json
  ?api-version=1.0

Pesquise 2026-01-01-01 – Obtenha Geocoding Batch

POST https://atlas.microsoft.com/geocode:batch
  ?api-version=2026-01-01

Geocodificação inversa (coordenadas → endereço)

A geocodificação reversa na Search API v1 foi realizada usando o endpoint de Endereço de Pesquisa Reverso. Na Search API 2026-01-01, esta funcionalidade está disponível através do Get Reverse Geocoding, que converte coordenadas de longitude e latitude para um endereço legível por humanos usando uma API dedicada de pesquisa reversa.

Pesquisa v1 – Reverso do Endereço de Pesquisa

GET https://atlas.microsoft.com/search/address/reverse/json
  ?api-version=1.0
  &position=47.639,-122.129

Pesquisa 2026-01-01 – Obtenha Geocodificação Reversa

GET https://atlas.microsoft.com/reverseGeocode
  ?api-version=2026-01-01
  &coordinates=-122.129,47.639

Geocodificação inversa em lote

A API de Pesquisa v1 permitiu consultas reversas por lote através do Get Search Address Reverse Batch. Na Search API 2026-01-01, este cenário é suportado pelo Get Reverse Geocoding Batch, permitindo que múltiplos pares de coordenadas sejam convertidos em endereços num único pedido para pipelines de telemetria, rastreamento ou enriquecimento.

Pesquisa v1 – Lote de Pesquisa Reversa de Endereço

POST https://atlas.microsoft.com/search/address/reverse/batch/json
  ?api-version=1.0

Pesquisa 2026-01-01-01 – Obtenha Reverse Geocoding Batch

POST https://atlas.microsoft.com/reverseGeocode:batch
  ?api-version=2026-01-01

Recuperação de limites administrativos

Na Search API v1, a geometria da fronteira administrativa foi recuperada usando o Get Search Polygon. Na Search API 2026-01-01, esta funcionalidade é fornecida pela Get Polygon API, que devolve geometria dos limites para entidades administrativas suportadas, como países/regiões e cidades.

Pesquisa Versão 1 – Obter Polígono de Pesquisa

GET https://atlas.microsoft.com/search/polygon/json
  ?api-version=1.0
  &entityId=US-WA

Pesquisa 2026-01-01-01 – Obtenha Polygon

GET https://atlas.microsoft.com/polygon
  ?api-version=2026-01-01
  &entityId=US-WA

Lista de verificação de migração

  • Inventariar todos os endpoints de Pesquisa v1 em uso
  • Identificar intenção (preenchimento automático vs geocodificação final)
  • Substituir os endpoints da v1 por aqueles equivalentes a 2026‑01‑01
  • Atualizar parâmetros de consulta
  • Validar análise sintática de respostas
  • Introduzir APIs por lote quando aplicável
  • Atualizar documentação e exemplos

Passos seguintes

Práticas recomendadas para o serviço de Pesquisa do Azure Maps

  • Última atualização a