Atualizar para a API REST mais recente no Pesquisa de IA do Azure 

Use este artigo para migrar para versões mais recentes das APIs REST do Serviço de Pesquisa e das APIs REST de Gerenciamento de Pesquisa para operações do plano de dados e do plano de controle .

Aqui estão as versões mais recentes das APIs REST:

As instruções de atualização se concentram nas alterações de código que ajudam a superar mudanças radicais de versões anteriores, garantindo que o código existente funcione da mesma maneira que antes, mas na versão mais recente da API. Depois que o código estiver em ordem de trabalho, você poderá decidir se deve adotar recursos mais recentes. Para saber mais sobre novos recursos, consulte O que há de novo no Pesquisa de IA do Azure .

Recomendamos atualizar as versões da API sucessivamente, trabalhando em cada versão até chegar à mais recente.

2023-07-01-preview foi a primeira API REST para suporte a vetores. Não use esta versão da API. Agora ele está obsoleto e você deve migrar para as APIs REST estáveis ou mais recentes imediatamente.

Quando atualizar

Pesquisa de IA do Azure  quebra a compatibilidade com versões anteriores como último recurso. A atualização é necessária quando:

• Seu código faz referência a uma versão de API desativada ou sem suporte e está sujeito a uma ou mais alterações interruptivas.

• Seu código falha quando propriedades não reconhecidas são retornadas em uma resposta de API. Como prática recomendada, seu aplicativo deve ignorar as propriedades que ele não entende.

• Seu código persiste solicitações de API e tenta reenvia-las para a nova versão da API. Por exemplo, isso poderá acontecer se o aplicativo persistir tokens de continuação retornados da API de Pesquisa (para obter mais informações, procure @search.nextPageParameters na Referência de API de Pesquisa).

Como atualizar

1. Se você estiver atualizando uma versão do plano de dados, examine o que foi lançado na nova versão da API.

2. Atualize o api-version parâmetro, especificado no cabeçalho da solicitação, para uma versão mais recente.

   No código do aplicativo que faz chamadas diretas para as APIs REST, pesquise todas as instâncias da versão existente e substitua-a pela nova versão. Para obter mais informações sobre como estruturar uma chamada REST, consulte Início Rápido: Pesquisa de texto completo usando REST.

   Se você estiver usando um SDK do Azure, cada pacote será direcionado a uma versão específica da API REST. Para determinar qual versão da API REST o pacote dá suporte, examine o log de alterações. Atualize para a versão mais recente do pacote para acessar os recursos mais recentes e melhorias de API.

3. Se você estiver atualizando uma versão do plano de dados, examine as alterações interruptivas documentadas neste artigo e implemente as soluções alternativas. Comece com a versão usada pelo código e resolva qualquer alteração significativa para cada versão mais recente da API até chegar à versão mais recente estável ou de versão prévia.

Alterações de quebra

As alterações interruptivas a seguir se aplicam às operações de dados.

Alterações significativas para recuperação de agente

2026-04-01 é a primeira versão estável da API REST para recuperação agente. Apresenta as seguintes mudanças disruptivas direto de 2025-11-01-preview:

• A síntese de resposta, o planejamento de consultas e o esforço de raciocínio configurável são removidos. A recuperação retorna apenas conteúdo extrativo e fundamentado.

• A forma de recuperação de solicitação muda: messages é substituída por intents, e vários parâmetros são renomeados ou removidos.

• Não há suporte para filtragem de permissões no nível de documento para fontes de conhecimento do Blob e do OneLake.

Para obter a lista completa de alterações no nível da propriedade e as etapas de migração, consulte Migrar o código de recuperação por meio de agentes.

Alterações interruptivas para agentes de conhecimento

Agentes de conhecimento foram introduzidos em 2025-05-01-preview. In 2025-08-01-preview, targetIndexes foi substituído por um novo objeto de origem de conhecimento e defaultMaxDocsForReranker foi substituído por outras APIs. Mais mudanças disruptivas foram introduzidas em 2025-11-01-preview.

Para obter a lista completa de alterações no nível da propriedade e as etapas de migração, consulte Migrar o código de recuperação por meio de agentes.

Alterações significativas no código do cliente que lê as informações de conexão

A partir de 29 de março de 2024 e aplicável a todas as APIs REST com suporte:

• Get Skillset, GET Index e GET Indexer não retornam mais chaves ou propriedades de conexão em uma resposta. Essa será uma alteração significativa se você tiver um código downstream que lê chaves ou conexões (dados confidenciais) de uma resposta GET.

• Se você precisar recuperar chaves de API de administração ou consulta para seu serviço de pesquisa, use as APIs REST do Gerenciamento de Pesquisa.

• Se você precisar recuperar cadeias de conexão de outro recurso de Azure, como Armazenamento do Azure ou Azure Cosmos DB, use as APIs desse recurso e as diretrizes publicadas para obter as informações.

Alterações interruptivas para o classificador semântico

O classificador semântico tornou-se geralmente disponível em 2023-11-01. Estas são as alterações interruptivas das versões anteriores:

• Em todas as versões após 2020-06-01-preview: semanticConfiguration substitui searchFields como o mecanismo para especificar quais campos usar para a classificação L2.

• Para todas as versões de API, as atualizações de 14 de julho de 2023 para os modelos semânticos hospedados pela Microsoft tornaram o classificador semântico agnóstico ao idioma, desativando efetivamente a propriedade queryLanguage. Não há nenhuma "alteração interruptiva" no código, mas a propriedade é ignorada.

Consulte Migrar da versão prévia para fazer a transição do código para usar semanticConfiguration.

Atualizações do plano de dados

As diretrizes de atualização pressupõem a atualização da versão anterior mais recente. Se o código for baseado em uma versão antiga da API, recomendamos atualizar cada versão sucessiva para chegar à versão mais recente.

Atualizar para 2026-05-01-preview

2026-05-01-preview adiciona novos tipos de fonte de conhecimento, novos parâmetros na ação de recuperação, novos tipos de conteúdo do indexador SharePoint e opções de ACL e outros recursos.

Não há alterações interruptivas conectadas de 2025-11-01-preview. No entanto, se você usar o Python ou o SDK do JavaScript para recuperação agente, o cliente de recuperação será renomeado para KnowledgeBaseRetrievalClient e retrieveKnowledge(...) será substituído por retrieve(...). Para obter orientações sobre migração do SDK, consulte Migrar seu código de recuperação agêntica.

Para todas as outras APIs existentes, não há alterações de comportamento. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualizar para 2026-04-01

2026-04-01 é a versão mais recente da API REST estável. Promove a recuperação por meio de agentes, seleciona fontes de conhecimento e várias habilidades e recursos para disponibilidade geral.

Antes de atualizar, verifique se alguma das seguintes 2026-04-01 alterações significativas se aplicam ao seu código:

• Seis propriedades são removidas da definição de habilidade do Prompt do GenAI: httpMethod, timeout, batchSize, degreeOfParallelism, httpHeaders, e authResourceId. Remova essas propriedades antes de atualizar. Definições que ainda incluem essas propriedades retornam um 400 Bad Request erro.

• A recuperação por meio de agentes agora requer um consentimento de cobrança próprio. Se você tiver semanticSearch=standard, deverá definir knowledgeRetrieval=standard explicitamente antes de atualizar. Para obter mais informações, consulte Habilitar ou desabilitar a cobrança de recuperação por meio de agentes.

• Se o código de recuperação por meio de agentes tiver como alvo 2025-11-01-preview, 2026-04-01 removerá vários recursos de versão prévia e padronizará a recuperação em torno da entrada relacionada às intenções, da saída extrativa e do raciocínio mínimo. Para obter mais informações, consulte Migrar o código de recuperação por meio de agentes.

Para todas as outras APIs existentes, não há alterações de comportamento. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualizar para 2025-11-01-preview

2025-11-01-preview apresenta as seguintes alterações significativas na recuperação por meio de agentes conforme implementado em 2025-08-01-preview:

• agents Substitui por knowledgebases. Várias propriedades relacionadas a fontes de conhecimento foram transferidas da definição da base de conhecimento para a ação de recuperação.

• As propriedades da fonte de conhecimento são refatoradas, implementando um novo objeto ingestionParameters para fontes de conhecimento que geram um pipeline de indexador.

Para obter a lista completa de alterações no nível da propriedade e as etapas de migração, consulte Migrar o código de recuperação por meio de agentes.

Para todas as outras APIs existentes, não há alterações de comportamento. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualizar para 2025-09-01

2025-09-01 é uma versão estável da API REST que adiciona disponibilidade geral para o indexador OneLake, a habilidade de Layout de Documento e outras APIs.

Não haverá alterações significativas se você estiver atualizando a partir de 2024-07-01 e não estiver utilizando nenhum recurso de visualização. Para usar a nova versão estável, altere a versão da API e teste seu código.

Atualize para 2025-08-01-preview

2025-08-01-preview introduz as seguintes mudanças disruptivas em agentes de conhecimento criados usando 2025-05-01-preview:

• targetIndexes Substitui por knowledgeSources.
• Remove defaultMaxDocsForReranker sem substituição.

Caso contrário, não haverá alterações de comportamento nas APIs existentes. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualizar para 2025-05-01-preview

2025-05-01-preview fornece novos recursos, mas não há alterações de comportamento nas APIs existentes. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualize para 2025-03-01-preview

2025-03-01-preview fornece novos recursos, mas não há alterações de comportamento nas APIs existentes. Você pode trocar na nova versão da API e seu código é executado da mesma forma que antes.

Atualização para 2024-11-01-preview

Reescrita de consulta de 2024-11-01-preview, habilidade de Layout de Documento, cobrança sem chave para processamento de habilidades, modo de análise Markdown e opções de nova pontuação para vetores compactados.

Se você estiver atualizando de 2024-09-01-preview, poderá trocar pela nova versão da API, e o código será executado da mesma forma que antes.

No entanto, a nova versão apresenta alterações de sintaxe em vectorSearch.compressions:

• rerankWithOriginalVectors Substitui porenableRescoring
• Move defaultOversampling para um novo objeto de propriedade rescoringOptions

A compatibilidade com versões anteriores é preservada devido a um mapeamento de API interno, mas recomendamos alterar a sintaxe se você adotar a nova versão de visualização. Para obter uma comparação da sintaxe, consulte Compactar vetores usando quantização escalar ou binária.

Atualização para 2024-09-01-preview

2024-09-01-preview adiciona a compactação MRL (Matryoshka Representation Learning) para modelos text-embedding-3, filtragem de vetor direcionada para consultas híbridas, detalhes de subestação de vetor para depuração e agrupamento de token para a habilidade de Divisão de Texto.

Se você estiver atualizando de 2024-05-01-preview, poderá trocar pela nova versão da API, e o código será executado da mesma forma que antes.

Atualizar para 2024-07-01

2024-07-01 é uma versão geral. Os recursos de visualização anteriores agora estão disponíveis em geral: agrupamento integrado e vetorização (habilidade de Divisão de Texto, habilidade AzureOpenAIEmbedding), vetorizador de consulta com base no AzureOpenAIEmbedding, compactação de vetor (quantização escalar, quantização binária, propriedade armazenada, tipos de dados estreitos).

Não haverá alterações significativas se você atualizar de 2024-05-01-preview para estável. Para usar a nova versão estável, altere a versão da API e teste seu código.

Haverá alterações significativas se você atualizar diretamente de 2023-11-01. Siga as etapas descritas para cada versão prévia mais recente para migrar de 2023-11-01 para 2024-07-01.

Atualize para 2024-05-01-preview

2024-05-01-preview adiciona um indexador para Microsoft OneLake, vetores binários e mais modelos de inserção.

Se você estiver atualizando da 2024-03-01-preview, a habilidade AzureOpenAIEmbedding agora exigirá uma propriedade nome do modelo e uma propriedade dimensões.

1. Pesquise em sua base de código por referências de AzureOpenAIEmbedding.

2. Defina modelName como "text-embedding-ada-002" e defina dimensions como "1536".

Atualize para 2024-03-01-preview

2024-03-01-preview adiciona tipos de dados estreitos, quantização escalar e opções de armazenamento de vetor.

Se você estiver atualizando da 2023-10-01-preview, não haverá alterações interruptivas. No entanto, há uma diferença de comportamento: para 2023-11-01 e versões prévias mais recentes, o vectorFilterMode padrão foi alterado de pós-filtro para pré-filtro para expressões de filtro.

1. Pesquise sua base de código para referências vectorFilterMode.

2. Se a propriedade estiver definida explicitamente, nenhuma ação será necessária. Se você se baseou no valor padrão, o novo comportamento padrão será filtrar antes da execução da consulta. Se você quiser filtragem pós-consulta, defina vectorFilterMode explicitamente como postfilter para manter o comportamento antigo.

Atualizar para 2023-11-01

2023-11-01 é uma versão geral. As versões prévias do recurso anteriores agora estão em disponibilidade geral: classificador semântico, índice de vetor e suporte à consulta.

Não há alterações significativas de 2023-10-01-preview, mas há várias alterações significativas de 2023-07-01-preview para 2023-11-01. Para obter mais informações, consulte Atualizar de 2023-07-01-preview.

Para usar a nova versão estável, altere a versão da API e teste seu código.

Atualizar para 2023-10-01-preview

2023-10-01-preview foi a primeira versão de pré-visualização a adicionar agrupamento e vetorização embutida de dados durante a indexação e a vetorização embutida de consulta. Ele também dá suporte à indexação de vetor e consultas da versão anterior.

Se você estiver atualizando da versão anterior, a próxima seção terá as etapas.

Atualização de 2023-07-01-preview

Não use essa versão da API. Ele implementa uma sintaxe de consulta vetor incompatível com qualquer versão mais recente da API.

2023-07-01-preview agora está preterido, portanto, você não deve basear o novo código nesta versão, nem deve atualizar para essa versão em nenhuma circunstância. Esta seção explica o caminho de migração para qualquer versão mais recente da 2023-07-01-preview API.

Atualização do portal para índices de vetor

O portal do Azure dá suporte a um caminho de atualização de um clique para índices da 2023-07-01-preview. Ele detecta campos de vetor e fornece um botão Migrar .

• O caminho de migração é de 2023-07-01-preview para 2024-05-01-preview.
• As atualizações são limitadas a definições de campo de vetor e configurações de algoritmo de pesquisa de vetor.
• As atualizações são unidirecionais. Não é possível reverter a atualização. Depois que o índice for atualizado, você deverá usar 2024-05-01-preview ou posterior para consultar o índice.

Não há nenhuma migração de portal para atualizar a sintaxe da consulta vetor. Consulte atualizações de código para alterações de sintaxe de consulta.

Antes de selecionar Migrar, selecioneEditar JSON para examinar o esquema atualizado primeiro. Você deve encontrar um esquema que esteja em conformidade com as alterações descritas na seção de atualização de código . A migração do portal lida apenas com índices que têm uma única configuração de algoritmo de pesquisa vetorial. Ele cria um perfil padrão que se mapeia ao algoritmo de busca vetorial 2023-07-01-preview. Índices com várias configurações de pesquisa de vetor exigem migração manual.

Atualização de código para índices vetoriais e consultas

O suporte à pesquisa de vetor foi introduzido no Create or Update Index (2023-07-01-preview).

Para atualizar de 2023-07-01-preview para qualquer versão posterior, estável ou de prévia, é necessário:

• Renomeando e reestruturando a configuração de vetor no índice
• Reescrever suas consultas de vetor

Use as instruções nesta seção para migrar campos de vetor, configuração e consultas de 2023-07-01-preview.

1. Chame Get Index para recuperar a definição existente.

2. Modifique a configuração de pesquisa de vetor. 2023-11-01 e versões posteriores introduzem o conceito de perfis de vetor que agrupam configurações relacionadas a vetores em um único nome. Versões mais recentes também renomeam algorithmConfigurations para algorithms.

   • Renomear algorithmConfigurations para algorithms. Isso refere-se apenas a uma renomeação da matriz. O conteúdo é retrocompatível. Isso significa que os parâmetros de configuração HNSW existentes podem ser usados.

   • Adicione profiles, dando um nome e uma configuração de algoritmo para cada um deles.

   Antes da migração (2023-07-01-preview):

     "vectorSearch": {
       "algorithmConfigurations": [
           {
               "name": "myHnswConfig",
               "kind": "hnsw",
               "hnswParameters": {
                   "m": 4,
                   "efConstruction": 400,
                   "efSearch": 500,
                   "metric": "cosine"
               }
           }
       ]}
   

   Após a migração (2023-11-01):

     "vectorSearch": {
       "algorithms": [
         {
           "name": "myHnswConfig",
           "kind": "hnsw",
           "hnswParameters": {
             "m": 4,
             "efConstruction": 400,
             "efSearch": 500,
             "metric": "cosine"
           }
         }
       ],
       "profiles": [
         {
           "name": "myHnswProfile",
           "algorithm": "myHnswConfig"
         }
       ]
     }
   

3. Modificar definições de campo de vetor, substituindo vectorSearchConfiguration por vectorSearchProfile. Verifique se o nome do perfil aponta para uma nova definição de perfil vetorial e não para o nome de configuração do algoritmo. Outras propriedades de campo de vetor permanecem inalteradas. Por exemplo, eles não podem ser filtrados, classificáveis ou facetáveis, nem usar analisadores ou normalizadores ou mapas de sinônimos.

   Antes (2023-07-01-preview):

     {
         "name": "contentVector",
         "type": "Collection(Edm.Single)",
         "key": false,
         "searchable": true,
         "retrievable": true,
         "filterable": false,  
         "sortable": false,  
         "facetable": false,
         "analyzer": "",
         "searchAnalyzer": "",
         "indexAnalyzer": "",
         "normalizer": "",
         "synonymMaps": "", 
         "dimensions": 1536,
         "vectorSearchConfiguration": "myHnswConfig"
     }
   

   Depois (2023-11-01):

     {
       "name": "contentVector",
       "type": "Collection(Edm.Single)",
       "searchable": true,
       "retrievable": true,
       "filterable": false,  
       "sortable": false,  
       "facetable": false,
       "analyzer": "",
       "searchAnalyzer": "",
       "indexAnalyzer": "",
       "normalizer": "",
       "synonymMaps": "", 
       "dimensions": 1536,
       "vectorSearchProfile": "myHnswProfile"
     }
   

4. Chame Criar ou Atualizar Índice para postar as alterações.

5. Modifique Search POST para alterar a sintaxe da consulta. Essa alteração de API permite suporte para tipos de consulta de vetor polimórfico.

   • Renomear vectors para vectorQueries.
   • Para cada consulta de vetor, adicione kind, definindo-a como vector.
   • Para cada consulta de vetor, renomeie value para vector.
   • Opcionalmente, adicione vectorFilterMode se você estiver usando expressões de filtro. O padrão é o pré-filtro para índices criados após 2023-10-01. Os índices criados antes dessa data só dão suporte ao pós-filtro, independentemente de como você define o modo de filtro.

   Antes (2023-07-01-preview):

   {
       "search": "*", //Required by the API but ignored for ranking in vector-only queries
       "vectors": [
         {
           "value": [
               0.103,
               0.0712,
               0.0852,
               0.1547,
               0.1183
           ],
           "fields": "contentVector",
           "k": 5
         }
       ],
       "select": "title, content, category"
   }
   

   Depois (2023-11-01):

   {
     "search": "*", //Required by the API but ignored for ranking in vector-only queries
     "vectorQueries": [
       {
         "kind": "vector",
         "vector": [
           0.103,
           0.0712,
           0.0852,
           0.1547,
           0.1183
         ],
         "fields": "contentVector",
         "k": 5
       }
     ],
     "vectorFilterMode": "preFilter",
     "select": "title, content, category"
   }
   

Essas etapas concluem a migração para a 2023-11-01 versão de API estável ou versões mais recentes da API de versão prévia.

Atualizar para 2020-06-30

Nesta versão, há uma alteração significativa e várias diferenças comportamentais. Os recursos disponíveis em geral incluem:

• Repositório de conhecimento, armazenamento persistente de conteúdo enriquecido criado por meio de conjuntos de habilidades, criado para análise downstream e processamento por meio de outros aplicativos. Um repositório de conhecimento é criado por meio Pesquisa de IA do Azure  APIs REST, mas reside em Armazenamento do Azure.

Alteração significativa

O código escrito para versões anteriores da API falhará em versões 2020-06-30 e posteriores se contiver a seguinte funcionalidade:

• Todos os literais Edm.Date (uma data composta por ano-mês-dia, como 2020-12-12) em expressões de filtro devem seguir o formato Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Essa alteração foi necessária para lidar com resultados de consulta errôneos ou inesperados devido a diferenças de fuso horário.

Alterações de comportamento

• O algoritmo de classificação BM25 substitui o algoritmo de classificação anterior por uma tecnologia mais recente. Os serviços criados após 2019 usam esse algoritmo automaticamente. Para serviços mais antigos, você deve definir parâmetros para usar o novo algoritmo.

• A ordem dos resultados de valores nulos foi alterada nesta versão, com esses valores aparecendo primeiro quando a classificação é asc e por último quando ela é desc. Se você escreveu código para lidar com a classificação de valores nulos, lembre-se dessa alteração.

Atualizar para 06/05/2019

Os recursos que se tornaram geralmente disponíveis nesta versão da API incluem:

• O Preenchimento automático é um recurso de digitação antecipada que completa uma entrada de termo parcialmente especificada.
• Tipos complexos fornecem suporte nativo para dados de objeto estruturados no índice de pesquisa.
• Modos de análise de JsonLines, parte da indexação do Azure Blob, criam um documento de pesquisa para cada entidade JSON, separada por uma nova linha.
• O enriquecimento de IA fornece indexação que usa os mecanismos de enriquecimento de IA das Foundry Tools.

Alterações de quebra

O código gravado em uma versão da API anterior será interrompido em 2019-05-06 e posteriormente se ele contiver a seguinte funcionalidade:

1. Propriedade Type para Azure Cosmos DB. Para os indexadores direcionados a uma fonte de dados da API do Azure Cosmos DB for NoSQL, altere "type": "documentdb" para "type": "cosmosdb".

2. Se o tratamento de erros do indexador incluir referências à propriedade status, você deverá removê-las. Removemos o status da resposta de erro porque ela não estava fornecendo informações úteis.

3. As cadeias de conexão da fonte de dados não são mais retornadas na resposta. De versões 2019-05-06 de API e 2019-05-06-Preview em diante, a API da fonte de dados não retorna mais cadeias de conexão na resposta de qualquer operação REST. Nas versões anteriores da API, para fontes de dados criadas usando POST, Pesquisa de IA do Azure  retornava 201, seguido pela resposta OData, que continha a string de conexão em texto simples.

4. A habilidade cognitiva de Reconhecimento de Entidades Nomeadas foi desativada. Se você chamou o recurso Reconhecimento de Entidades Nomeadas em seu código, a chamada falhará. A funcionalidade de substituição é a Habilidade de Reconhecimento de Entidade (V3). Siga as recomendações em habilidades preteridas para migrar para uma habilidade com suporte.

Atualizando tipos complexos

A versão 2019-05-06 da API adicionou suporte formal para tipos complexos. Se o código implementou recomendações anteriores para equivalência de tipo complexo em 2017-11-11-Preview ou 2016-09-01-Preview, há alguns limites novos e alterados a partir da versão 2019-05-06 da qual você precisa estar ciente:

• Os limites da profundidade dos subcampos e o número de coleções complexas por índice foram reduzidos. Se você criou índices que excedem esses limites usando as versões prévias da API, qualquer tentativa de atualizá-los ou recriá-los usando a versão 2019-05-06 da API falhará. Se você se encontrar nessa situação, precisará reprojetar seu esquema para se ajustar aos novos limites e, em seguida, recompilar o índice.

• Há um novo limite começando na versão 2019-05-06 de API no número de elementos de coleções complexas por documento. Se você criou índices com documentos que excedem esses limites usando as versões de api de visualização, qualquer tentativa de reindexar esses dados usando a versão 2019-05-06 da API falhará. Se você se encontrar nessa situação, precisará reduzir o número de elementos de coleção complexos por documento antes de reexer seus dados.

Para obter mais informações, consulte Limites do Serviço para Pesquisa de IA do Azure .

Como atualizar uma estrutura de tipo complexa antiga

Se o código estiver usando tipos complexos com uma das versões mais antigas da API de visualização, você pode estar usando um formato de definição de índice semelhante a este:

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}  

Um formato mais recente semelhante à árvore para definir campos de índice foi introduzido na versão 2017-11-11-Previewda API. No novo formato, cada campo complexo tem uma coleção de campos em que seus subcampos são definidos. Na API versão 2019-05-06, esse novo formato é usado exclusivamente e a tentativa de criar ou atualizar um índice usando o formato antigo falhará. Se você tiver índices criados usando o formato antigo, precisará usar a versão 2017-11-11-Preview da API para atualizá-los para o novo formato antes que eles possam ser gerenciados usando a API versão 2019-05-06.

Você pode atualizar índices simples para o novo formato com as seguintes etapas usando a versão 2017-11-11-Previewda API:

1. Execute uma solicitação GET para recuperar o índice. Caso ele já esteja no novo formato, tudo pronto.

2. Traduza o índice do formato simples para o novo formato. Você precisa escrever código para essa tarefa, pois não há nenhum código de exemplo disponível no momento desta gravação.

3. Execute uma solicitação PUT para atualizar o índice para o novo formato. Evite alterar outros detalhes do índice, como a pesquisa/filtrabilidade de campos, porque as alterações que afetam a expressão física do índice existente não são permitidas pela API de Índice de Atualização.

Atualizações do plano de controle

Aplica-se a:2014-07-31-Preview, 2015-02-28e 2015-08-19

A listQueryKeys solicitação GET em versões mais antigas da API de Gerenciamento de Pesquisa foi preterida. Recomendamos migrar para a versão mais recente da API do plano de controle estável para usar a requisição POSTlistQueryKeys.

1. No código existente, altere o api-version parâmetro para a versão mais recente (2025-05-01).

2. Reenquadrar a solicitação de GET para POST

   POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
   Authorization: Bearer {{token}}
   

3. Se você estiver usando um SDK do Azure, é recomendável que você atualize para a versão mais recente.

Próximas etapas

Examine a documentação de referência da API REST de Pesquisa. Se você encontrar problemas, peça ajuda no Stack Overflow ou entre em contato com o suporte.