Migrar APIs do Azure Mapas Search 1.0

Busca A API versão 2026-01-01 substitui a API de Pesquisa versão 1.0. A versão mais recente apresenta pontos de extremidade específicos da tarefa, intenção mais clara e escalabilidade aprimorada. Este artigo explica como migrar as integrações existentes da Pesquisa v1.

Importante

A API de Pesquisa do Azure Mapas versão 1.0 foi substituída pela API de Pesquisa versão 2026-01-01. Enquanto a Pesquisa v1 continua a funcionar, os novos desenvolvimentos devem utilizar a versão mais recente da API de Pesquisa para acessar pontos de extremidade específicos para tarefas, além de garantir melhor desempenho e suporte a longo prazo. Para evitar futuras interrupções de serviço, migre as integrações existentes da Pesquisa v1 para a Pesquisa 2026-01-01.

Mapeamento de equivalência de API

Propósito Pesquisar a API v1 Pesquisa da API 2026-01-01
Geocodificação direta Obter endereço de pesquisa Obter geocodificação
Endereço Get Search Fuzzy (final) Obter geocodificação
Preenchimento automático Get Search Fuzzy (type‑ahead) Get Geocode Autocomplete
Geocodificação em lote Obter Conjunto de Endereços de Pesquisa Get Geocoding Batch
Geocodificação reversa Obter o endereço de busca reversa Obter geocodificação reversa
Reversão de lote Get Search Address Reverse Batch Obter Lote de Geocodificação Reversa
Boundaries Obter Polígono de Pesquisa Obter Polígono

Diferenças notáveis

As APIs Search 2026-01-01 introduzem pontos de extremidade específicos de intenção, semântica de solicitação mais clara e comportamento de resultado mais rigoroso em comparação com a Search v1. A tabela a seguir resume as diferenças mais importantes a serem observadas ao migrar.

Area Search v1 Search 2026‑01‑01
Design de API Os pontos de extremidade de várias finalidades (por exemplo, Search Fuzzy usado para o preenchimento automático e pesquisa final) As APIs específicas de intenção (por exemplo, Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding)
Comportamento de preenchimento automático Implementado usando o Search Fuzzy com typeahead=true API dedicada de preenchimento automático Get Geocode
Geocodificação final Muitas vezes dependia de correspondência difusa para retornar um "melhor palpite" "Get Geocoding prioriza a precisão e pode não retornar resultados"
Resultados vazios Muitas vezes retornava uma correspondência pouco confiável Pode retornar HTTP 200 com uma matriz de resultados vazia quando nenhuma correspondência for encontrada
Manejo da confiança dos resultados A confiança e a qualidade da correspondência eram frequentemente implícitas Confiança, códigos de correspondência e tipo de entidade são explícitos e devem ser avaliados
Manipulação da hierarquia de entidades Os resultados difusos podem retornar entidades vagamente relacionadas Os resultados podem ser acumulados para uma entidade de nível superior (por exemplo, condado ou região) e devem ser filtrados por tipo de entidade
Uso de lote APIs de Lote disponíveis, mas geralmente opcionais APIs em lote são recomendadas para fluxos de trabalho em larga escala e enriquecimento
Fluxos de trabalho de enriquecimento de dados Geralmente repetido com a pesquisa difusa Dá suporte explicitamente a padrões de enriquecimento com sinalização de 'não correspondência' de forma mais clara.
Estrutura de URL Versionado sob os pontos de extremidade /search/* Pontos de extremidade simplificados e específicos da tarefa (por exemplo, /geocode, ) /reverseGeocode
Extensibilidade futura Capacidade limitada de evoluir comportamentos individuais As APIs evoluem independentemente com base na intenção (preenchimento automático, geocodificação, reverso)

Diferenças de uso de transações

O recurso Search 2026-01-01 usa as APIs específicas de intenção, que podem alterar a forma como as transações são processadas em comparação com a versão Search v1.

No recurso Search v1, um único ponto de extremidade de várias finalidades era frequentemente usado tanto para o preenchimento automático quanto para a geocodificação final. Na Pesquisa 2026-01-01, esses cenários são separados em APIs distintas, o que ajuda a alinhar o uso da transação mais de perto com a intenção do usuário.

Principais considerações ao migrar:

  • Use Get Geocode Autocomplete somente para as interações do usuário de preenchimento automático.
  • Use Obter Geocodificação somente quando um endereço ou local final for necessário.
  • Evite chamar as APIs de geocodificação final repetidamente durante cenários interativos de digitação.
  • Prefira APIs em lotes para fluxos de trabalho de geocodificação em grande escala ou em segundo plano.

Para obter detalhes sobre como as transações do Azure Mapas são calculadas e cobradas, consulte Noções básicas sobre transações do Azure Mapas.

Alterações de tratamento de resultados

A Pesquisa 2026-01-01 coloca maior ênfase na precisão dos resultados e na sinalização explícita de correspondência do que a Pesquisa v1.

Ao migrar, examine como seu aplicativo interpreta as respostas de pesquisa:

  • Uma solicitação bem-sucedida pode não retornar resultados quando nenhuma correspondência adequada for encontrada. Para obter mais informações, consulte Compreendendo os resultados vazios de geocodificação.
  • Correspondências de baixa confiança ou que são vagamente relacionadas são menos propensas a serem retornadas automaticamente.
  • Os aplicativos devem avaliar valores de confiança, códigos de correspondência e tipos de entidade ao determinar se um resultado é aceitável. Para obter mais informações, consulte Aprimorar a qualidade do resultado para geocodificação baseada em consulta.
  • Se uma entidade solicitada não for encontrada, o serviço poderá retornar uma entidade de nível superior na hierarquia de endereços (por exemplo, uma região em vez de uma cidade). Para obter mais informações sobre como avaliar a qualidade dos resultados e validar que os tipos de entidade retornados correspondem ao cenário de pesquisa pretendido, consulte As práticas recomendadas para a geocodificação avançada nas práticas recomendadas para o serviço Azure Mapas Search.

Não suponha que cada solicitação bem-sucedida retorne um resultado utilizável. A avaliação explícita de resultados é necessária para manter a qualidade dos dados.

Comparação de exemplo de solicitação e resposta

Os exemplos a seguir mostram como as solicitações comuns do Azure Mapas Search v1 são mapeadas para seus equivalentes na API de Pesquisa 2026-01-01. Cada exemplo se concentra na mesma intenção do usuário, destacando a mudança de pontos de extremidade v1 de várias finalidades para APIs específicas da intenção.

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

Na API de Pesquisa v1, a geocodificação direta era normalmente executada usando o Endereço de Pesquisa ou os endpoints de Pesquisa Fuzzy. Na API de Pesquisa 2026-01-01, essa funcionalidade é fornecida pela API Get Geocoding, que transforma a entrada de endereços estruturados ou não estruturados em coordenadas geográficas, usando um ponto de extremidade dedicado e específico para essa finalidade.

Pesquisar v1 – Endereço de Pesquisa

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

Search 2026‑01‑01 – Get Geocoding

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

Endereço difuso ou pesquisa de local (resultado final)

A API Search v1 expôs a resolução de endereço e localização aproximada por meio de um único ponto de extremidade Search Fuzzy. Na API de Pesquisa 2026-01-01, esse comportamento é substituído por Get Geocoding, que lida com consultas de endereço e locais em formato livre, enquanto separa os cenários de preenchimento automático e sugestão em APIs distintas.

Search v1 – Search Fuzzy

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

Search 2026‑01‑01 – Get Geocoding

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

Preenchimento automático e sugestões enquanto digita

Na API Search v1, o comportamento de preenchimento automático foi habilitado por meio da configuração typeahead=true no ponto de extremidade [Search Fuzzy]. Na API de Pesquisa 2026-01-01, os cenários de preenchimento automático são tratados explicitamente pela API Get Geocode de Preenchimento Automático, que é otimizada para entrada interativa do usuário e sugestões em tempo real.

Search v1 – Search Fuzzy (uso de preenchimento automático)

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

Search 2026‑01‑01 – Get Geocode Autocomplete

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

Para obter mais informações, consulte Introdução à API de Preenchimento Automático do Geocode do Azure Mapas.

Geocodificação direta de lote

A API Search v1 oferecia suporte para resolução de endereços em lote através do ponto de extremidade de Lote de pesquisa de endereços. Na API de Pesquisa 2026-01-01, essa funcionalidade é fornecida pelo Get Geocoding Batch, permitindo que várias consultas de endereço sejam enviadas e processadas em uma única solicitação para cargas de trabalho em grande escala ou em segundo plano.

Search v1 – Search Address Batch

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

Search 2026‑01‑01 – Get Geocoding Batch

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

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

A geocodificação inversa na API de Pesquisa v1 foi executada usando o endpoint de geocodificação inversa de endereço. Na API de Pesquisa 2026-01-01, essa funcionalidade está disponível por meio da Obtenção de Geocodificação Reversa, que converte coordenadas de longitude e latitude em um endereço legível por humanos usando uma API de pesquisa reversa dedicada.

Search v1 – Search Address Reverse

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

Search 2026‑01‑01 – Get Reverse Geocoding

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

Geocodificação reversa em lote

A API Search v1 habilitou pesquisas reversas em lote através de Get Search Address Reverse Batch. Na API Search 2026‑01‑01, esse cenário é suportado por Get Reverse Geocoding Batch, permitindo que vários pares de coordenadas sejam resolvidos para endereços em uma única solicitação para pipelines de telemetria, acompanhamento ou enriquecimento.

Search v1 – Search Address Reverse Batch

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

Search 2026‑01‑01 – Get Reverse Geocoding Batch

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

Recuperação de limite administrativo

Na API de Pesquisa v1, a geometria de limite administrativo foi recuperada usando Get Search Polygon. Na API de Pesquisa 2026-01-01, essa funcionalidade é fornecida pela API Get Polygon , que retorna geometria de limite para entidades administrativas com suporte, como países/regiões e cidades.

Search v1 – Get Search Polygon

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

Search 2026‑01‑01 – Get 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 pontos de extremidade de Search v1 em uso
  • Identificar a intenção (preenchimento automático versus código geográfico final)
  • Substituir os pontos de extremidade v1 por equivalentes 2026-01-01
  • Atualizar parâmetros de consulta
  • Validar interpretação de resposta
  • Introduzir APIs em lote quando aplicável
  • Atualizar documentação e exemplos

Próximas Etapas