Actualización a la API REST más reciente en Búsqueda de Azure AI

Nota

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Use este artículo para migrar a versiones más recientes de las API REST del servicio de búsqueda y las API REST de administración de búsqueda para las operaciones del plano de datos y del plano de control .

Estas son las versiones más recientes de las API REST:

Operaciones dirigidas	REST API	Estado
Plano de datos	2026-04-01	Estable
Plano de datos	2026-05-01-preview	Vista previa
Plano de control	2025-05-01	Estable
Plano de control	2026-03-01-preview	Vista previa

Las instrucciones de actualización se centran en los cambios de código que le permiten realizar cambios importantes de versiones anteriores para que el código existente se ejecute igual que antes, pero en la versión más reciente de la API. Una vez que el código está en orden de trabajo, puede decidir si adoptar características más recientes. Para obtener más información sobre las nuevas características, consulte Novedades de Búsqueda de Azure AI.

Se recomienda actualizar las versiones de API sucesivamente, trabajando en cada versión hasta que llegue a la más reciente.

2023-07-01-preview fue la primera API REST para la compatibilidad con vectores. No use esta versión de API. Ahora se encuentra en desuso y debe migrar inmediatamente a las API REST estables o a las versiones preliminares más recientes.

Nota

Los documentos de referencia de la API REST ahora están versionados. Para el contenido específico de la versión, abra una página de referencia y, a continuación, use el selector situado encima de la tabla de contenido para elegir la versión.

Cuándo actualizar

Búsqueda de Azure AI rompe la compatibilidad con versiones anteriores como último recurso. La actualización es necesaria cuando:

• El código hace referencia a una versión de API retirada o no compatible y está sujeta a uno o varios cambios importantes.

• Se produce un error en el código cuando se devuelven propiedades no reconocidas en una respuesta de API. Como procedimiento recomendado, la aplicación debe omitir las propiedades que no entiende.

• El código conserva las solicitudes de API e intenta volver a enviarlos a la nueva versión de API. Por ejemplo, esto puede ocurrir si la aplicación conserva los tokens de continuación devueltos desde Search API (para obtener más información, busque @search.nextPageParameters en la referencia de Search API).

Cómo actualizar

1. Si va a actualizar una versión del plano de datos, revise lo que se ha publicado en la nueva versión de api.

2. Actualice el api-version parámetro, especificado en el encabezado de solicitud, a una versión más reciente.

   En el código de la aplicación que realiza llamadas directas a las API REST, busque todas las instancias de la versión existente y, a continuación, reemplácela por la nueva versión. Para obtener más información sobre cómo estructurar una llamada REST, consulte Inicio rápido: Búsqueda de texto completo mediante REST.

   Si usa un SDK de Azure, cada paquete tiene como destino una versión específica de la API REST. Para determinar qué versión de la API REST admite el paquete, revise su registro de cambios. Actualice a la versión más reciente del paquete para acceder a las características y mejoras de API más recientes.

3. Si va a actualizar una versión del plano de datos, revise los cambios importantes documentados en este artículo e implemente las soluciones alternativas. Comience con la versión usada por el código y resuelva cualquier cambio importante para cada versión de API más reciente hasta que llegue a la versión estable o preliminar más reciente.

Cambios disruptivos

Los siguientes cambios importantes se aplican a las operaciones de datos.

Cambios importantes para la recuperación agente

2026-04-01 es la primera versión estable de la API REST para la recuperación agente. Presenta los siguientes cambios disruptivos de 2025-11-01-preview:

• Se quitan la síntesis de respuestas, el planeamiento de consultas y el esfuerzo de razonamiento configurable. La recuperación de datos solo devuelve contenido extractivo y fundamentado.

• La forma de solicitud de recuperación cambia: messages se reemplaza por intentsy se cambia el nombre o se quitan varios parámetros.

• No se admite el filtrado de permisos a nivel de documento para las fuentes de conocimiento de Blob y OneLake.

Para obtener la lista completa de cambios a nivel de propiedad y pasos de migración, consulte Migración del código de recuperación de agentes.

Cambios importantes para agentes de conocimiento

Los agentes de conocimiento se introdujeron en 2025-05-01-preview. En 2025-08-01-preview, targetIndexes se reemplazó por un nuevo objeto de origen de conocimiento y defaultMaxDocsForReranker se reemplazó por otras API. Se introdujeron más cambios disruptivos en 2025-11-01-preview.

Para obtener la lista completa de cambios a nivel de propiedad y pasos de migración, consulte Migración del código de recuperación de agentes.

Cambios importantes en el código de cliente que lee la información de conexión

A partir del 29 de marzo de 2024 y aplicable a todas las API REST admitidas:

• GET Skillset, GET Index y GET Indexer ya no devuelven claves ni propiedades de conexión en una respuesta. Se trata de un cambio disruptivo si tiene código posterior que lee claves o conexiones (datos confidenciales) de una respuesta GET.

• Si necesita recuperar claves de API de administrador o consulta para el servicio de búsqueda, use las API REST de administración de búsqueda.

• Si necesita recuperar cadenas de conexión de otro recurso de Azure como Azure Storage o Azure Cosmos DB, use las API de ese recurso y las instrucciones publicadas para obtener la información.

Cambios importantes para el clasificador semántico

El clasificador semántico se puso a disposición con carácter general en 2023-11-01. Estos son los cambios importantes de las versiones anteriores:

• En todas las versiones después de 2020-06-01-preview: semanticConfiguration reemplaza searchFields como el mecanismo para especificar los campos que se utilizarán para la clasificación L2.

• En todas las versiones de la API, las actualizaciones realizadas el 14 de julio de 2023 en los modelos semánticos alojados por Microsoft hicieron que el clasificador semántico fuera independiente del lenguaje, lo que supuso, en la práctica, la retirada de la propiedad queryLanguage. No hay ningún "cambio importante" en el código, pero se omite la propiedad.

Vea Migrar desde la versión preliminar para transicionar su código a usar semanticConfiguration.

Actualizaciones del plano de datos

Las instrucciones de actualización se basan en la premisa de que se realiza la actualización desde la versión anterior más reciente. Si el código se basa en una versión anterior de la API, se recomienda actualizar a través de cada versión sucesiva para llegar a la versión más reciente.

Actualizar a 2026-05-01-preview

2026-05-01-preview agrega nuevos tipos de origen de conocimiento, nuevos parámetros en la acción de recuperación, nuevos tipos de contenido SharePoint indexador y opciones de ACL, y otras funcionalidades.

No hay ningún cambio importante en el nivel de conexión de 2025-11-01-preview. Sin embargo, si usa la Python o el SDK de JavaScript para la recuperación agente, se cambia el nombre del cliente de recuperación a KnowledgeBaseRetrievalClient y se reemplaza retrieveKnowledge(...) por retrieve(...). Para obtener instrucciones sobre la migración del SDK, consulte Migración del código de recuperación agente.

Para todas las demás API existentes, no hay ningún cambio de comportamiento. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualización a 2026-04-01

2026-04-01 es la versión más reciente de la API REST estable. Promueve la recuperación de agentes, selecciona orígenes de conocimientos y varias aptitudes y características de disponibilidad general.

Antes de actualizar, compruebe si alguno de los siguientes 2026-04-01 cambios importantes se aplica al código:

• Se quitan seis propiedades de la definición de habilidad de solicitudes GenAI: httpMethod, timeout, batchSize, degreeOfParallelism, httpHeaders y authResourceId. Quite estas propiedades antes de actualizar. Las definiciones que todavía incluyen estas propiedades devuelven un 400 Bad Request error.

• La recuperación de agentes ahora requiere su propio consentimiento de facturación. Si actualmente tiene semanticSearch=standard, debe establecer knowledgeRetrieval=standard explícitamente antes de actualizar. Para obtener más información, consulte Habilitar o deshabilitar la facturación de recuperación de agentes.

• Si su código de recuperación de agentes se centra en 2025-11-01-preview, 2026-04-01 elimina varias funciones en versión preliminar y estandariza la recuperación en torno a la entrada de intenciones, la salida extractiva y el razonamiento mínimo. Para obtener más información, consulte Migración del código de recuperación de agentes.

Para todas las demás API existentes, no hay ningún cambio de comportamiento. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualización a la versión preliminar de 2025-11-01

2025-11-01-preview presenta los siguientes cambios importantes en la recuperación de agentes, tal como se implementa en 2025-08-01-preview:

• agents Reemplaza por knowledgebases. Varias propiedades relacionadas con los orígenes de conocimiento se han movido fuera de la definición de la base de conocimiento y a la acción de recuperación.

• Las propiedades del origen de conocimiento se refactorizan, implementando un nuevo ingestionParameters objeto para los orígenes de conocimiento que generan una canalización de indexador.

Para obtener la lista completa de cambios a nivel de propiedad y pasos de migración, consulte Migración del código de recuperación de agentes.

Para todas las demás API existentes, no hay ningún cambio de comportamiento. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualización a 2025-09-01

2025-09-01 es una versión estable de la API REST que ofrece disponibilidad general para el indexador de OneLake, la aptitud de diseño de documentos y otras API.

No hay cambios importantes si actualiza desde 2024-07-01 y no utiliza ninguna función preliminar. Para usar la nueva versión estable, cambie la versión de la API y pruebe el código.

Actualización a 2025-08-01-preview

2025-08-01-preview presenta los siguientes cambios importantes en los agentes de conocimiento creados mediante 2025-05-01-preview:

• targetIndexes Reemplaza por knowledgeSources.
• Elimina defaultMaxDocsForReranker sin reemplazo alguno.

De lo contrario, no hay ningún cambio de comportamiento en las API existentes. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualización a vista previa de 01-05-2025

2025-05-01-preview proporciona nuevas características, pero no hay ningún cambio de comportamiento en las API existentes. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualización a la versión preliminar de 2025-03-01

2025-03-01-preview proporciona nuevas características, pero no hay ningún cambio de comportamiento en las API existentes. Puede intercambiar a la nueva versión de la API y su código se ejecutará de la misma manera que antes.

Actualizar a la versión pre-release del 2024-11-01

2024-11-01-preview para la reescritura de consultas, la aptitud Diseño de documento, la facturación sin claves para el procesamiento de aptitudes, el modo de análisis de Markdown y las opciones de revisión para vectores comprimidos.

Si va a actualizar desde 2024-09-01-preview, puede cambiarlo por la nueva versión de la API y el código se ejecuta igual que antes.

Sin embargo, la nueva versión presenta cambios de sintaxis en vectorSearch.compressions:

• rerankWithOriginalVectors Reemplaza porenableRescoring
• Mueve defaultOversampling a un nuevo objeto de propiedad rescoringOptions

La compatibilidad con versiones anteriores se conserva debido a una asignación de API interna, pero se recomienda cambiar la sintaxis si adopta la nueva versión preliminar. Para obtener una comparación de la sintaxis, vea Comprimir vectores mediante cuantificación escalar o binaria.

Mejora a 2024-09-01-preview

2024-09-01-preview agrega compresión de Matryoshka Representation Learning (MRL) para modelos de text-embedding-3, filtrado de vectores dirigidos para consultas híbridas, detalles de subpuntuación de vectores para depuración y fragmentación de tokens para la aptitud División de texto.

Si va a actualizar desde 2024-05-01-preview, puede cambiarlo por la nueva versión de la API y el código se ejecuta igual que antes.

Actualización a 2024-07-01

2024-07-01 es una versión general. Las características de versión preliminar anteriores ahora están disponibles con carácter general: fragmentación integrada y vectorización (aptitud División de texto, aptitud AzureOpenAIEmbedding), vectorizador de consultas basado en AzureOpenAIEmbedding, compresión vectorial (cuantificación escalar, cuantificación binaria, propiedad almacenada, tipos de datos estrechos).

No hay cambios importantes si actualiza de 2024-05-01-preview a la versión estable. Para usar la nueva versión estable, cambie la versión de la API y pruebe el código.

Hay cambios importantes si actualiza directamente desde 2023-11-01. Siga los pasos descritos para cada versión preliminar más reciente para migrar de 2023-11-01 a 2024-07-01.

Actualización a la versión de prueba 2024-05-01-preview

2024-05-01-preview agrega un indexador para Microsoft OneLake, vectores binarios y más modelos de inserción.

Si va a actualizar desde 2024-03-01-preview, la aptitud AzureOpenAIEmbedding ahora requiere un nombre de modelo y una propiedad de dimensiones.

1. Busque en su código fuente referencias a AzureOpenAIEmbedding.

2. Establezca modelName en "text-embeding-ada-002" y establezca dimensions en "1536".

Mejora a 2024-03-01-preview

2024-03-01-preview agrega tipos de datos estrechos, cuantificación escalar y opciones de almacenamiento de vectores.

Si va a actualizar desde 2023-10-01-preview, no hay cambios importantes. Sin embargo, hay una diferencia de comportamiento: para 2023-11-01 y versiones preliminares más recientes, el vectorFilterMode valor predeterminado ha cambiado de postfilter a prefiltro para expresiones de filtro.

1. Busque referencias en el código base vectorFilterMode .

2. Si la propiedad se establece explícitamente, no se requiere ninguna acción. Si se basa en el valor predeterminado, el nuevo comportamiento predeterminado es filtrar antes de la ejecución de la consulta. Si desea filtrar después de la consulta, establezca vectorFilterMode explícitamente en postfilter para conservar el comportamiento anterior.

Actualización a 2023-11-01

2023-11-01 es una versión general. Las características de versión preliminar anteriores ahora están disponibles con carácter general: clasificación semántica y compatibilidad con vectores.

No hay cambios importantes de 2023-10-01-preview, pero hay varios cambios importantes de 2023-07-01-preview a 2023-11-01. Para obtener más información, consulte Actualización de 2023-07-01-preview.

Para usar la nueva versión estable, cambie la versión de la API y pruebe el código.

Actualizar a 2023-10-01-preview

2023-10-01-preview fue la primera versión preliminar para agregar fragmentación y vectorización de datos integrados durante la indexación y la vectorización de consulta integrada. También admite la indexación de vectores y las consultas de la versión anterior.

Si va a actualizar desde la versión anterior, la sección siguiente tiene los pasos.

Actualización desde la versión preliminar 2023-07-01

No use esta versión de API. Implementa una sintaxis de consulta vectorial incompatible con cualquier versión de API más reciente.

2023-07-01-preview ahora está en desuso, por lo que no debe basar el nuevo código en esta versión, ni debe actualizar a esta versión en ninguna circunstancia. En esta sección se explica la ruta de migración de 2023-07-01-preview a cualquier versión de API más reciente.

Actualización del portal para índices vectoriales

Azure portal admite una ruta de actualización con un solo clic para 2023-07-01-preview índices. Detecta campos vectoriales y proporciona un botón Migrar .

• La ruta de migración es de 2023-07-01-preview a 2024-05-01-preview.
• Las actualizaciones se limitan a las definiciones de campos vectoriales y a las configuraciones del algoritmo de búsqueda vectorial.
• Las actualizaciones son unidireccionales. No se puede revertir la actualización. Una vez actualizado el índice, deberá usar 2024-05-01-preview o posterior para consultar el índice.

No hay ninguna migración del portal para actualizar la sintaxis de consulta vectorial. Consulte actualizaciones de código para ver los cambios en la sintaxis de consulta.

Antes de seleccionar Migrar, seleccione Editar JSON para revisar primero el esquema actualizado. Debe encontrar un esquema que se ajuste a los cambios descritos en la sección actualización de código . La migración del portal solo gestiona los índices con una única configuración de algoritmo de búsqueda vectorial. Crea un perfil predeterminado que se vincula al algoritmo de 2023-07-01-preview búsqueda vectorial. Los índices con varias configuraciones de búsqueda vectorial requieren una migración manual.

Actualización de código para índices y consultas vectoriales

La compatibilidad con la búsqueda vectorial se introdujo en Create or Update Index (2023-07-01-preview).

La actualización de 2023-07-01-preview a cualquier versión estable o preliminar más reciente requiere:

• Cambio de nombre y reestructuración de la configuración de vectores en el índice
• Reescritura de las consultas vectoriales

Siga las instrucciones de esta sección para migrar campos vectoriales, configuración y consultas desde 2023-07-01-preview.

1. Llame a Get Index para recuperar la definición existente.

2. Modifique la configuración de búsqueda vectorial. 2023-11-01 y versiones posteriores presentan el concepto de perfiles vectoriales que agrupan configuraciones relacionadas con vectores con un nombre. Las versiones más recientes también cambian de nombre algorithmConfigurations a algorithms.

   • Cambie el nombre algorithmConfigurations a algorithms. Solo se trata de un cambio de nombre de la matriz. El contenido es compatible con versiones anteriores. Esto significa que se pueden usar los parámetros de configuración de HNSW existentes.

   • Agregue profiles, asignando un nombre y una configuración de algoritmo para cada uno.

   Antes de la migración (2023-07-01-preview):

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

   Después de la migración (2023-11-01):

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

3. Modifique las definiciones de campo vectorial, reemplazando vectorSearchConfiguration con vectorSearchProfile. Asegúrese de que el nombre del perfil se resuelve en una nueva definición de perfil vectorial y no en el nombre de configuración del algoritmo. Otras propiedades de campo vectorial permanecen sin cambios. Por ejemplo, no pueden ser filtrables, ordenables o facetables, ni usar analizadores ni normalizadores ni 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"
     }
   

   Después (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. Llame a Crear o actualizar índice para publicar los cambios.

5. Modifique Search POST para cambiar la sintaxis de la consulta. Este cambio de API permite admitir tipos de consulta de vector polimórficos.

   • Cambie el nombre vectors a vectorQueries.
   • Para cada consulta vectorial, agregue kind, estando establecida en vector.
   • Para cada consulta vectorial, cambie el nombre value a vector.
   • Opcionalmente, agregue vectorFilterMode si usa expresiones de filtro. El valor predeterminado es pre-filtrado para los índices creados después de 2023-10-01. Los índices creados antes de esa fecha solo admiten postfiltro, independientemente de cómo establezca el 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"
   }
   

   Después (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"
   }
   

Estos pasos completan la migración a 2023-11-01 una versión estable de la API o versiones más recientes de la API en versión preliminar.

Actualización a 2020-06-30

En esta versión, hay un cambio importante y varias diferencias de comportamiento. Entre las características disponibles con carácter general se incluyen:

• Almacén de conocimiento, almacenamiento persistente de contenido enriquecido creado a través de conjuntos de habilidades, creado para el análisis y procesamiento posterior a través de otras aplicaciones. Un almacén de conocimiento se crea a través de Búsqueda de Azure AI API REST, pero reside en Azure Storage.

Cambio disruptivo

El código escrito en versiones anteriores de la API se interrumpe en 2020-06-30 y versiones posteriores si el código contiene la siguiente funcionalidad:

• Los literales de Edm.Date (una fecha que consta de año-mes-día, como 2020-12-12) en expresiones de filtro deben seguir el formato Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Este cambio era necesario para controlar los resultados erróneos o inesperados de la consulta debido a las diferencias de zona horaria.

Cambios de comportamiento

• El algoritmo de clasificación BM25 reemplaza el algoritmo de clasificación anterior por una tecnología más reciente. Los servicios creados después de 2019 usan este algoritmo automáticamente. Para los servicios anteriores, debe establecer parámetros para usar el nuevo algoritmo.

• Los resultados ordenados para los valores NULL han cambiado en esta versión, con valores NULL que aparecen en primer lugar si la ordenación es asc y último si la ordenación es desc. Si escribió código para controlar cómo se ordenan los valores NULL, tenga en cuenta este cambio.

Actualización a 2019-05-06

Entre las características que están disponibles con carácter general en esta versión de API se incluyen las siguientes:

• Autocomplete es una característica de escritura anticipada que completa la entrada de un término especificado de forma parcial.
• Los tipos complejos proporcionan compatibilidad nativa con los datos de objetos estructurados en el índice de búsqueda.
• Los modos de análisis de JsonLines, que forman parte de la indexación de Azure Blob, crean un documento de búsqueda por entidad JSON que está separado por una línea nueva.
• El enriquecimiento con IA proporciona indexación que usa los motores de enriquecimiento de IA de Foundry Tools.

Cambios disruptivos

El código escrito en una versión anterior de la API se interrumpe en 2019-05-06 y versiones posteriores si contiene la siguiente funcionalidad:

1. Propiedad Type de Azure Cosmos DB. Para los indexadores que tienen como destino un origen de datos de Azure Cosmos DB para NoSQL API, cambie "type": "documentdb" a "type": "cosmosdb".

2. Si el control de errores del indexador incluye referencias a la status propiedad , debe quitarla. Hemos quitado el estado de la respuesta de error, ya que no proporcionaba información útil.

3. Las cadenas de conexión del origen de datos ya no se devuelven en la respuesta. A partir de las versiones 2019-05-06 y 2019-05-06-Preview de la API, la API de origen de datos ya no devuelve cadenas de conexión en la respuesta de ninguna operación REST. En versiones anteriores de la API, para los orígenes de datos creados mediante POST, Búsqueda de Azure AI devolvió 201 seguido de la respuesta de OData, que contenía la cadena de conexión en texto sin formato.

4. Se retira la aptitud cognitiva de Reconocimiento de entidades con nombre. Si ha llamado a la capacidad Reconocimiento de entidades de nombre en el código, se producirá un error en la llamada. La funcionalidad de reemplazo es la aptitud de reconocimiento de entidades (V3). Siga las recomendaciones de Aptitudes en desuso para migrar a una aptitud admitida.

Actualización de tipos complejos

La versión 2019-05-06 de API agregó compatibilidad formal con tipos complejos. Si el código implementó recomendaciones anteriores para la equivalencia de tipos complejos en 2017-11-11-Preview o 2016-09-01-Preview, hay algunos límites nuevos y modificados a partir de la versión 2019-05-06 de la que debe tener en cuenta:

• Se han reducido los límites en la profundidad de los subcampos y el número de colecciones complejas por índice. Si ha creado índices que superan estos límites mediante las versiones preliminares de api, se produce un error en cualquier intento de actualizarlos o volver a crearlos mediante la versión 2019-05-06 de la API. Si se encuentra en esta situación, debe rediseñar el esquema para ajustarse a los nuevos límites y, a continuación, volver a generar el índice.

• Hay un nuevo límite a partir de la versión 2019-05-06 de api en el número de elementos de colecciones complejas por documento. Si ha creado índices con documentos que superan estos límites mediante la versión preliminar de api-versions, se produce un error en cualquier intento de volver a indexar esos datos mediante api-version 2019-05-06 . Si se encuentra en esta situación, debe reducir el número de elementos de colección complejos por documento antes de volver a indexar los datos.

Para obtener más información, consulte los límites de servicio para Búsqueda de Azure AI.

Cómo actualizar una estructura de tipo complejo antigua

Si el código usa tipos complejos con una de las versiones anteriores de la API de versión preliminar, podría usar un formato de definición de índice similar al siguiente:

{
  "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" }
  ]
}  

Se introdujo un formato más reciente en forma de árbol para definir campos de índice en la versión 2017-11-11-Preview de la API. En el nuevo formato, cada campo complejo tiene una colección fields donde se definen sus subcampos. En la versión de API 2019-05-06, este nuevo formato se usa exclusivamente y se producirá un error al intentar crear o actualizar un índice con el formato anterior. Si tiene índices creados con el formato anterior, deberá usar la versión 2017-11-11-Preview de API para actualizarlos al nuevo formato antes de que se puedan administrar mediante la versión de API 2019-05-06.

Puede actualizar índices planos al nuevo formato con los pasos siguientes mediante la versión 2017-11-11-Previewde API :

1. Realice una solicitud GET para recuperar el índice. Si ya está en el formato nuevo, ya ha terminado.

2. Traduzca el índice del formato plano al nuevo formato. Tiene que escribir código para esta tarea, ya que no hay ningún código de ejemplo disponible en el momento de escribirlo.

3. Realice una solicitud PUT para actualizar el índice al nuevo formato. Evite cambiar cualquier otro detalle del índice, como la capacidad de búsqueda o filtrado de campos, ya que la API update index no permite los cambios que afectan a la expresión física del índice existente.

Nota

No es posible administrar índices creados con el formato "plano" antiguo desde el portal de Azure. Actualice los índices de la representación "plana" a la representación de "árbol" lo antes posible.

Actualizaciones del plano de control

Se aplica a:2014-07-31-Preview, 2015-02-28, y 2015-08-19

La listQueryKeys solicitud GET en versiones anteriores de Search Management API ya está en desuso. Se recomienda migrar a la versión de API del plano de control estable más reciente para usar la listQueryKeys solicitud POST.

1. En el código existente, cambie el api-version parámetro a la versión más reciente (2025-05-01).

2. Vuelva a enmarcar la solicitud de GET a 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. Si usa un SDK de Azure, se recomienda actualizar a la versión más reciente.

Pasos siguientes

Revise la documentación de referencia de la API REST de búsqueda. Si tiene problemas, pida ayuda en Stack Overflow o póngase en contacto con el soporte técnico.

Referencia de la API REST del servicio de búsqueda