Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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