Atualize para a mais recente API REST 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 Gestão de Pesquisa para operações de plano de dados e plano de controlo .

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

As instruções de atualização focam-se em alterações de código que te ajudam a quebrar alterações em versões anteriores para que o código existente corra igual ao anterior, mas na versão mais recente da API. Quando o seu código estiver a funcionar, pode decidir se adota funcionalidades mais recentes. Para saber mais sobre novas funcionalidades, consulte O que há de novo em 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 utilize esta versão da API. Agora está descontinuado e deve migrar o mais rapidamente possível para APIs REST estáveis ou para as prévias mais recentes.

Quando atualizar

O Pesquisa de IA do Azure quebra a compatibilidade retroativa como último recurso. A atualização é necessária quando:

• O seu código faz referência a uma versão da API retirada ou não suportada e está sujeito a uma ou mais alterações graves.

• O seu código falha quando propriedades não reconhecidas são devolvidas numa resposta da API. Como boa prática, a sua aplicação deve ignorar as propriedades que não entende.

• O seu código persiste nos pedidos da API e tenta reenviá-los para a nova versão da API. Por exemplo, isto pode acontecer se a sua aplicação persistir tokens de continuação devolvidos pela API de Pesquisa (para mais informações, procure @search.nextPageParameters na Referência da API de Pesquisa).

Como atualizar

1. Se estiveres a atualizar a versão de um plano de dados, vê o que foi lançado na nova versão da API.

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

   No código da sua aplicação que faz chamadas diretas às APIs REST, procure todas as instâncias da versão existente e depois substitua-a pela nova versão. Para mais informações sobre como estruturar uma chamada REST, veja Quickstart: Pesquisa em texto completo usando REST.

   Se estiveres a usar um SDK do Azure, cada pacote tem como alvo uma versão específica da API REST. Para determinar qual a versão da API REST que o seu pacote suporta, consulte o seu registo de alterações. Atualize para a versão mais recente do pacote para aceder às funcionalidades mais recentes e melhorias na API.

3. Se estiver a atualizar a versão de um plano de dados, reveja as alterações urgentes documentadas neste artigo e implemente as soluções alternativas. Começa pela versão usada pelo teu código e resolve qualquer alteração quebrada para cada versão mais recente da API até chegares à versão mais recente estável ou de pré-visualização.

Alterações de grande impacto

As seguintes alterações de última hora aplicam-se às operações de dados.

Alterações de grande impacto para a recuperação de agente

2026-04-01 é a primeira versão estável da API REST para recuperação agêntica. Introduz as seguintes alterações disruptivas de:2025-11-01-preview

• A síntese de respostas, o planeamento de consultas e o esforço de raciocínio configurável são removidos. A recuperação só devolve conteúdo extrativo e fundamentado.

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

• A filtragem de permissões ao nível do documento para fontes de conhecimento blob e OneLake não é suportada.

Para a lista completa de alterações ao nível da propriedade e passos de migração, consulte Migrar o seu código de recuperação agente.

Alterações incompatíveis para agentes de conhecimento

Os agentes do conhecimento foram introduzidos em 2025-05-01-preview. Em 2025-08-01-preview, targetIndexes foi substituído por um novo objeto fonte de conhecimento, e defaultMaxDocsForReranker foi substituído por outras APIs. Foram introduzidas alterações mais disruptivas em 2025-11-01-preview.

Para a lista completa de alterações ao nível da propriedade e os passos de migração, consulte Migrar o seu código de recuperação agêntico.

Alterações disruptivas para o código do cliente que lê informação de conexão

Com efeito a partir de 29 de março de 2024 e aplicável a todas as APIs REST suportadas:

• O conjunto de habilidades GET, o índice GET e o indexador GET já não retornam chaves ou propriedades de ligação numa resposta. Isto é uma mudança decisiva se tiveres código a jusante que lê chaves ou ligações (dados sensíveis) de uma resposta GET.

• Se precisar de recuperar chaves de API de administração ou de consulta para o seu serviço de pesquisa, utilize as APIs REST de Gestão de Pesquisa.

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

Alterações recentes para o ranker semântico

O ranker semântico tornou-se disponível de forma geral em 2023-11-01. Estas são as mudanças marcantes em relação aos lançamentos anteriores:

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

• Para todas as versões da API, as atualizações de 14 de julho de 2023 aos modelos semânticos alojados pela Microsoft tornaram o ranker semântico agnóstico em relação à língua, desativando efetivamente a propriedade queryLanguage. Não há nenhuma "alteração disruptiva" no código, mas a propriedade é ignorada.

Veja Migrar da versão de pré-visualização para fazer a transição do seu código para usar semanticConfiguration.

Atualizações do plano de dados

A orientação de atualização assume a atualização a partir da última versão anterior. Se o seu código for baseado numa versão antiga da API, recomendamos que atualize por cada versão sucessiva para chegar à versão mais recente.

Atualização para 2026-04-01

2026-04-01 é a versão estável mais recente da API REST. Promove a recuperação agentiva, fontes de conhecimento selecionadas e várias competências e funcionalidades para disponibilidade geral.

Antes de atualizar, verifique se alguma das seguintes 2026-04-01 alterações disruptivas se aplica ao seu código.

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

• A recuperação agential requer agora o seu próprio consentimento de faturação. Se tens semanticSearch=standardatualmente , tens de definir knowledgeRetrieval=standard explicitamente antes de atualizares. Para mais informações, consulte Ativar ou desativar a faturação de recuperação agente.

• Se o seu código de recuperação agentical visar o 2025-11-01-preview, 2026-04-01 remove várias capacidades de pré-visualização e padroniza a recuperação em torno da entrada das intenções, saída extrativa e raciocínio mínimo. Para mais informações, consulte Migrar o seu código de recuperação agente.

Para todas as outras APIs existentes, não há alterações de comportamento. Podes trocar a nova versão da API, e o teu código corre da mesma forma que antes.

Atualizar para 2025-11-01-preview

2025-11-01-preview introduz as seguintes alterações significativas na recuperação agentica, conforme implementadas no 2025-08-01-preview:

• Substitui agents por knowledgebases. Várias propriedades relacionadas com fontes de conhecimento foram movimentadas 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 objeto novo ingestionParameters para fontes de conhecimento que criam um pipeline de indexação.

Para a lista completa de alterações a nível de propriedade e etapas de migração, consulte Migrar o seu código de recuperação agêntica.

Para todas as outras APIs existentes, não há alterações de comportamento. Podes trocar a nova versão da API, e o teu código corre da mesma forma que antes.

Atualização para 2025-09-01

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

Não há alterações interruptivas se estiver a atualizar de 2024-07-01 e não usar nenhuma funcionalidade de pré-visualização. Para usar a nova versão estável, altera a versão da API e testa o teu código.

Atualização para pré-visualização de 2025-08-01

2025-08-01-preview Introduz as seguintes alterações críticas aos agentes de conhecimento criados usando 2025-05-01-preview:

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

Caso contrário, não há alterações de comportamento nas APIs existentes. Podes trocar a nova versão da API, e o teu código corre da mesma forma que antes.

Atualização para a versão preview de 2025-05-01

2025-05-01-preview fornece novas funcionalidades, mas não há alterações de comportamento nas APIs existentes. Podes trocar a nova versão da API, e o teu código corre da mesma forma que antes.

Atualizar para versão de pré-visualização 2025-03-01

2025-03-01-preview fornece novas funcionalidades, mas não há alterações de comportamento nas APIs existentes. Podes trocar a nova versão da API, e o teu código corre da mesma forma que antes.

Atualizar para a versão de pré-visualização 2024-11-01

2024-11-01-preview reescrita de consultas, habilidade de Layout de Documentos, faturação sem utilização de chaves para processamento de competências, modo de interpretação Markdown e opções de reavaliação para vetores comprimidos.

Se estiveres a atualizar a partir de 2024-09-01-preview, podes trocar para a nova versão da API, e o teu código corre como antes.

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

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

A retrocompatibilidade é preservada devido a um mapeamento interno da API, mas recomendamos alterar a sintaxe se adotar a nova versão de pré-visualização. Para uma comparação da sintaxe, veja Vetores de compressão usando quantização escalar ou binária.

Atualização para pré-visualização de 2024-09-01

2024-09-01-preview adiciona compressão de Matryoshka Representation Learning (MRL) para modelos de incorporação de texto-3, filtragem vetorial direcionada para consultas híbridas, detalhes de subescore vetorial para depuração e fragmentação de tokens para a habilidade Text Split.

Se estiveres a atualizar a partir de 2024-05-01-preview, podes trocar para a nova versão da API, e o teu código corre como antes.

Atualização para 2024-07-01

2024-07-01 é uma versão geral. As funcionalidades anteriores de pré-visualização estão agora geralmente disponíveis: segmentação integrada e vetorização (Text Split skill, AzureOpenAIEmbedding skill), vetorizador de consulta baseado em AzureOpenAIEmbedding, compressão vetorial (quantização escalar, quantização binária, propriedades armazenadas, tipos de dados restritos).

Não há alterações disruptivas se fizer um upgrade de 2024-05-01-preview para a versão estável. Para usar a nova versão estável, altera a versão da API e testa o teu código.

Há alterações de grande impacto se fizer um upgrade direto a partir de 2023-11-01. Siga os passos indicados para cada pré-visualização mais recente para migrar de 2023-11-01 para 2024-07-01.

Atualizar para a versão de pré-visualização de 2024-05-01

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

Se estiver a atualizar a partir de 2024-03-01-preview, a funcionalidade AzureOpenAIEmbedding agora requer um nome de modelo e uma propriedade de dimensões.

1. Procure referências AzureOpenAIEmbedding no seu código.

2. Definir modelName para "text-embedding-ada-002" e definir dimensions para "1536".

Atualizar para versão preliminar 2024-03-01

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

Se estiveres a fazer um upgrade a partir de 2023-10-01-preview, não há alterações disruptivas. No entanto, há uma diferença de comportamento: para 2023-11-01 e versões de pré-visualização mais recentes, o padrão do vectorFilterMode mudou de pós-filtro para pré-filtro para expressões de filtro.

1. Procura referências na tua base vectorFilterMode de código.

2. Se a propriedade estiver explicitamente definida, não é necessária qualquer ação. Se dependeu do valor predefinido, o novo comportamento predefinido é filtrar antes da execução da consulta. Se quiser filtragem pós-consulta, defina vectorFilterMode explicitamente como postfilter para manter o comportamento antigo.

Atualização para 2023-11-01

2023-11-01 é um lançamento geral. Os antigos recursos de pré-visualização estão agora geralmente disponíveis: ranker semântico e suporte a vetores.

Não existem alterações que quebram a compatibilidade de 2023-10-01-preview, mas existem múltiplas alterações que quebram a compatibilidade de 2023-07-01-preview para 2023-11-01. Para mais informações, consulte Atualização da pré-visualização de 2023-07-01.

Para usar a nova versão estável, altera a versão da API e testa o teu código.

Atualizar para a versão preliminar de 2023-10-01

2023-10-01-preview foi a primeira versão de pré-visualização a adicionar fragmentação de dados incorporada e vetorização durante a indexação e vetorização de consultas incorporadas. Também suporta indexação vetorial e consultas da versão anterior.

Se estiveres a atualizar a partir da versão anterior, a secção seguinte tem os passos.

Atualização a partir da pré-visualização de 2023-07-01

Não uses esta versão da API. Implementa uma sintaxe de consulta vetorial que é incompatível com qualquer versão mais recente da API.

2023-07-01-preview está agora obsoleto, por isso não deve basear novo código nesta versão, nem deve atualizar para esta versão em circunstância alguma. Esta secção explica o caminho de migração de 2023-07-01-preview para qualquer versão mais recente da API.

Atualização do portal para índices vetoriais

Azure portal suporta um caminho de atualização com um clique para índices 2023-07-01-preview. Deteta campos vetoriais e fornece um botão de Migrar .

• A rota de migração é de 2023-07-01-preview para 2024-05-01-preview.
• As atualizações limitam-se a definições de campos vetoriais e configurações de algoritmos de pesquisa vetorial.
• As atualizações são unidirecionais. Não podes reverter a atualização. Uma vez que o índice é atualizado, deve usar 2024-05-01-preview ou posteriormente para consultar o índice.

Não existe migração de portal para atualizar a sintaxe de consultas vetoriais. Consulte atualizações de código para alterações na sintaxe das consultas.

Antes de selecionar Migrar, selecione Editar JSON para rever primeiro o esquema atualizado. Deverias encontrar um esquema que cumpra as alterações descritas na secção de atualização de código . A migração de portais apenas gere índices com uma configuração de algoritmo de pesquisa vetorial. Cria um perfil padrão que corresponde ao 2023-07-01-preview algoritmo de pesquisa vetorial. Índices com múltiplas configurações de pesquisa vetorial requerem migração manual.

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

O suporte à pesquisa vetorial foi introduzido no Create or Update Index (pré-visualização de 2023-07-01).

Atualizar de 2023-07-01-preview para qualquer versão estável ou de pré-visualização mais recente requer:

• Renomear e reorganizar a configuração de vetor no índice
• Reescrever as suas consultas vetoriais

Use as instruções desta secção para migrar campos vetoriais, configuração e consultas a partir de 2023-07-01-preview.

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

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

   • Renomear algorithmConfigurations para algorithms. Isto é apenas uma renomeação do array. O conteúdo é retrocompatível. Isto significa que os seus parâmetros de configuração HNSW existentes podem ser utilizados.

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

   Antes da migração (pré-visualização de 2023-07-01):

     "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 campos vetoriais, substituindo vectorSearchConfiguration por vectorSearchProfile. Certifique-se de que o nome do perfil seja associado a uma nova definição de perfil vetorial, e não ao nome da configuração do algoritmo. Outras propriedades do campo vetorial mantêm-se inalteradas. Por exemplo, não podem ser filtráveis, ordenáveis ou categorizáveis, nem utilizar analisadores, normalizadores ou mapas de sinónimos.

   Antes (pré-visualização de 2023-07-01):

     {
         "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 aplicar as alterações.

5. Modificar o Search POST para alterar a sintaxe da consulta. Esta alteração na API permite o suporte para tipos de consulta vetorial polimórfica.

   • Renomear vectors para vectorQueries.
   • Para cada consulta vetorial, adicione kind, definindo para vector.
   • Para cada consulta vetorial, renomeia value para vector.
   • Opcionalmente, adiciona vectorFilterMode se estiveres a usar expressões de filtro. O predefinido é pré-filtro para índices criados após 2023-10-01. Índices criados antes dessa data só suportam o postfilter, independentemente de como definas o modo de filtro.

   Antes (pré-visualização de 2023-07-01):

   {
       "search": (this parameter is ignored in vector search),
       "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": "(this parameter is ignored in vector search)",
     "vectorQueries": [
       {
         "kind": "vector",
         "vector": [
           0.103,
           0.0712,
           0.0852,
           0.1547,
           0.1183
         ],
         "fields": "contentVector",
         "k": 5
       }
     ],
     "vectorFilterMode": "preFilter",
     "select": "title, content, category"
   }
   

Estes passos completam a migração para 2023-11-01 uma versão estável da API ou versões mais recentes da API de pré-visualização.

Atualização para 2020-06-30

Nesta versão, há uma mudança que se rompe e várias diferenças comportamentais. As funcionalidades geralmente disponíveis incluem:

• Armazenamento de conhecimento, armazenamento persistente de conteúdo enriquecido criado através de conjuntos de competências, criado para análise e processamento a jusante através de outras aplicações. Um knowledge store é criado através das APIs REST do Pesquisa de IA do Azure, mas reside no Armazenamento do Azure.

Mudança de última hora

O código escrito para versões anteriores da API deixa de funcionar em 2020-06-30 e depois se o código contiver a seguinte funcionalidade:

• Quaisquer Edm.Date literais (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. Esta alteração foi necessária para lidar com resultados erróneos ou inesperados de consultas devido a diferenças de fuso horário.

Alterações comportamentais

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

• Os resultados ordenados para valores nulos mudaram nesta versão, com valores nulos a aparecerem primeiro se a ordenação for asc e em último se a ordenação for desc. Se escreveste código para lidar com a forma como os valores nulos são ordenados, fica atento a esta alteração.

Atualização para 2019-05-06

As funcionalidades que se tornaram geralmente disponíveis nesta versão da API incluem:

• O autopreenchimento é uma funcionalidade de typeahead que completa uma entrada de termo parcialmente especificada.
• Os tipos complexos fornecem suporte nativo para dados estruturados de objetos no índice de pesquisa.
• JsonLines parsing modes, parte da indexação do Azure Blob, cria um documento de pesquisa para cada entidade JSON que são separadas por uma nova linha.
• O enriquecimento de IA fornece indexação que utiliza os motores de enriquecimento de IA da Foundry Tools.

Alterações de grande impacto

O código escrito para uma versão anterior da API falha em 2019-05-06 e versões posteriores se contiver a seguinte funcionalidade:

1. Propriedade de tipo para Azure Cosmos DB. Para os indexadores que visam um Azure Cosmos DB para NoSQL fonte de dados API, alterem "type": "documentdb" para "type": "cosmosdb".

2. Se a gestão de erros do indexador incluir referências à propriedade status, deve removê-las. Removemos o estado da resposta de erro porque não fornecia informação útil.

3. As cadeias de ligação à fonte de dados já não são devolvidas na resposta. A partir das versões 2019-05-062019-05-06-Preview da API, a API da fonte de dados deixa de devolver cadeias de ligação em resposta a qualquer operação REST. Em versões anteriores da API, para fontes de dados criadas usando POST, Pesquisa de IA do Azure retornava 201 seguido da resposta OData, que continha a cadeia de ligação em texto simples.

4. A competência cognitiva de Reconhecimento de Entidade Nomeada foi descontinuada. Se chamar a habilidade Reconhecimento de Nomes de Entidades no seu código, a chamada irá falhar. A funcionalidade de substituição é a Habilidade de Reconhecimento de Entidades (V3). Siga as recomendações em Competências Obsoletas para migrar para uma competência suportada.

Modernização dos tipos de complexos

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

• Os limites de profundidade dos subcampos e o número de coleções complexas por índice foram reduzidos. Se criou índices que excedam estes limites usando as versões de pré-visualização da API, qualquer tentativa de os atualizar ou recriar usando a versão 2019-05-06 da API falha. Se se encontrar nesta situação, precisa de redesenhar o seu esquema para se encaixar nos novos limites e depois reconstruir o seu índice.

• Há um novo limite a partir da versão 2019-05-06 API para o número de elementos de coleções complexas por documento. Se criou índices com documentos que excedem estes limites usando as versões de pré-visualização da API, qualquer tentativa de reindexar esses dados usando a versão 2019-05-06 da API falha. Se se encontrar nesta situação, precisa de reduzir o número de elementos complexos de coleção por documento antes de reindexar os seus dados.

Para mais informações, consulte limites de serviço para Pesquisa de IA do Azure.

Como atualizar uma estrutura complexa antiga

Se o seu código estiver a usar tipos complexos com uma das versões anteriores da API de pré-visualização, pode estar a usar um formato de definição de índice que se assemelha 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 a uma á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 onde os seus subcampos são definidos. Na versão API 2019-05-06, este novo formato é usado exclusivamente e tentar criar ou atualizar um índice usando o formato antigo falhará. Se tiver índices criados com o formato antigo, terá de usar a versão 2017-11-11-Preview da API para os atualizar para o novo formato antes de poderem ser geridos com a versão API 2019-05-06.

Pode atualizar índices planos para o novo formato com os seguintes passos usando a versão 2017-11-11-Previewda API:

1. Faça um pedido GET para recuperar o seu índice. Se já estiver no novo formato, já está concluído.

2. Traduz o índice do formato plano para o novo formato. Tens de escrever código para esta tarefa, pois não há código de exemplo disponível à data desta escrita.

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

Atualizações no plano de controlo

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

O listQueryKeys pedido GET nas versões antigas da API de Gestão de Pesquisa está agora obsoleto. Recomendamos migrar para a versão mais recente e estável da API do plano de controlo para usar o listQueryKeys pedido POST.

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

2. Reformule o pedido 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 estiveres a usar um SDK do Azure, recomenda-se que atualizes para a versão mais recente.

Próximos passos

Consulte a documentação de referência da Search REST API. Se encontrar problemas, peça-nos ajuda no Stack Overflow ou contacte o suporte.