Índice de actualización (API REST de Azure AI Search)

  • Artículo

La modificación de un índice existente normalmente requiere una eliminación y recompilación de índices, excepto los siguientes cambios de esquema:

  • Agregar nuevos campos a una colección fields

  • Agregar campos recién creados a un proveedor de sugerencias

  • Agregar o cambiar perfiles de puntuación

  • Adición o cambio de claves de cifrado

  • Incorporación de nuevos analizadores personalizados

  • Cambiar las opciones de CORS

  • Cambie los campos existentes con cualquiera de estas tres modificaciones:

    • Cambiar retrievable (los valores son true o false)
    • Cambiar searchAnalyzer (se usa en el momento de la consulta)
    • Agregar o cambiar synonymMaps (se usa en el momento de la consulta)

Para agregar estas actualizaciones, coloque el nombre del índice en el URI de solicitud. En el cuerpo de la solicitud, incluya una definición de índice totalmente especificada con las modificaciones.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

Los campos existentes y la mayoría de los atributos de campo no se pueden eliminar ni cambiar, ni se pueden agregar campos a los proveedores de sugerencias. Solo se pueden agregar campos recién creados a .suggester

Cuando se agrega un nuevo campo, todos los documentos existentes obtienen automáticamente un valor NULL para ese campo. No se consume ningún otro espacio de almacenamiento hasta que se produce una de estas dos cosas: se proporciona un valor para el nuevo campo (mediante combinación) o se agregan nuevos documentos.

Los analizadores, los tokenizadores, los filtros de token y los filtros char existentes no se pueden modificar. Agregar nuevos a un índice ya existente solo es posible cuando la allowIndexDowntime marca está activada en la solicitud de actualización de índice. La misma regla se aplica al agregar un campo vectorial inicial a un índice preexistente que se estableció mediante una API que no admitía la búsqueda de vectores, específicamente antes de la versión 2023-07-01 de la API REST.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Esta operación desconecta el índice durante unos segundos. Se produce un error en la indexación y las solicitudes de consulta mientras el índice está sin conexión. Las operaciones de rendimiento y escritura pueden verse afectadas temporalmente durante varios minutos después de que el índice vuelva a estar en línea.

Parámetros de identificador URI

Parámetro Descripción
nombre del servicio Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda.
nombre de índice Necesario. El URI de solicitud especifica el nombre del índice que se va a actualizar.
api-version Necesario. Consulte Versiones de API para obtener una lista de las versiones admitidas.
allowIndexDowntime Opcional. El valor predeterminado es false. Se establece en true para determinadas actualizaciones, como agregar o modificar un analizador, tokenizador, filtro de token, filtro char o propiedad de similitud. El índice se desconecta durante la actualización, normalmente no más de varios segundos.

Encabezados de solicitud

En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.

Campos Descripción
Content-Type Necesario. Establézcalo en application/json
api-key Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Las solicitudes de actualización deben incluir un api-key encabezado establecido en la clave de administrador (en lugar de una clave de consulta). Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información.

Cuerpo de la solicitud

La sintaxis del cuerpo de la solicitud es la misma que para Create Index.

Al actualizar un índice existente, el cuerpo debe incluir la definición de esquema completa, incluidas las definiciones originales que quiera conservar. En general, el mejor patrón para las actualizaciones es recuperar la definición de índice con get, modificarla y, a continuación, actualizarla con PUT.

Response

Para una solicitud correcta, debe ver "204 No Content".

De forma predeterminada, el cuerpo de la respuesta está vacío. Sin embargo, si el encabezado de Prefer solicitud se establece return=representationen , el cuerpo de la respuesta contiene el JSON del índice actualizado. En este caso, el código de estado correcto es "200 OK".

Consulte también