Referencia de la API REST de Azure AI Search

Azure AI Search (anteriormente conocido como Azure Cognitive Search) es un servicio de búsqueda en la nube totalmente administrado que proporciona recuperación de información sobre contenido propiedad del usuario.

Las API REST del plano de datos se usan para indexar y consultar flujos de trabajo.

Se accede a las operaciones del plano de control a través de una API REST de administración independiente.

Documentación de api con versiones

Los documentos de la API REST ahora tienen versiones. Al abrir una página de referencia de API, aparece un selector de versiones encima de la tabla de contenido. Asegúrese de que la referencia de API procede de la carpeta Plano de datos de referencia>.

Captura de pantalla del selector de versiones.

Conceptos clave

Azure AI Search tiene los conceptos de servicios de búsqueda, índices, documentos, indexadores, orígenes de datos, conjuntos de aptitudes y mapas de sinónimos.

  • Un servicio de búsqueda hospeda índices, indexadores, orígenes de datos, conjuntos de aptitudes y asignaciones de sinónimos como objetos de nivel superior.
  • Un índice de búsqueda proporciona almacenamiento persistente de documentos de búsqueda. Los documentos de búsqueda son los datos, articulados como una colección de campos, cargados desde orígenes externos e insertados en un índice para que se puedan realizar búsquedas.
  • Un indexador de búsqueda agrega automatización, lectura de datos en formatos nativos y serialización en JSON.
  • Un indexador tiene un origen de datos y apunta a un índice.
  • Un indexador también puede tener un conjunto de aptitudes que agregue enriquecimiento con IA y vectorización integrada a la canalización de indexación. Los conjuntos de aptitudes siempre se adjuntan a un indexador. Invocan el aprendizaje automático para extraer o fragmentar texto, vectorizar contenido, deducir características o agregar estructura al contenido para que un servicio de búsqueda pueda indizarlo.

Por completo, puede crear los siguientes objetos en un servicio de búsqueda:

Objetos Descripción
Orígenes de datos Una conexión de origen de datos utilizada por un indexador para recuperar y actualizar documentos para la indexación. Los orígenes de datos tienen .type Puede usar las conexiones proporcionadas por Microsoft para Azure o conectores de terceros a través de asociados. Consulte Galería de orígenes de datos para obtener la lista completa.
Documentos Conceptualmente, un documento es una entidad del índice. Asignar este concepto a equivalentes de base de datos más conocidos: un índice de búsqueda equivale a una tabla y los documentos son aproximadamente equivalentes a las filas de una tabla. Los documentos solo existen en un índice y solo se recuperan a través de consultas destinadas a la colección de documentos (/docs) de un índice. Todas las operaciones realizadas en la colección, como la carga, la combinación, la eliminación o la consulta de documentos tienen lugar en el contexto de un único índice, por lo que las operaciones del documento de formato URL siempre se incluirán /indexes/[index name]/docs para un nombre de índice determinado.
Índices Un índice se almacena en el servicio de búsqueda y se rellena con documentos JSON indexados y tokenizados para la recuperación de información. La colección fields de un índice define la estructura del documento de búsqueda. Los campos tienen un nombre, tipos de datos y atributos que determinan cómo se usa. Por ejemplo, los campos se usan en la búsqueda de texto completo y, por tanto, searchable se tokenizan durante la indexación. Un índice también define otras construcciones, como perfiles de puntuación para el ajuste de relevancia, los proveedores de sugerencias, las configuraciones semánticas y los analizadores personalizados.
Indexadores Los indexadores proporcionan automatización de la indexación. Un indexador se conecta a un origen de datos, lee los datos y lo pasa a un motor de búsqueda para la indexación en un índice de búsqueda de destino. Los indizadores leen desde un origen externo mediante información de conexión en un origen de datos y serializan los datos entrantes en documentos de búsqueda JSON. Además de un origen de datos, un indexador también requiere un índice. El índice especifica los campos y atributos de los documentos de búsqueda.
Conjuntos de aptitudes Un conjunto de aptitudes agrega pasos de procesamiento externos a la ejecución del indexador y normalmente se usa para agregar modelos de inteligencia artificial o aprendizaje profundo para analizar o transformar contenido para que se pueda buscar en un índice. El contenido de un conjunto de aptitudes es una o varias aptitudes, que pueden ser aptitudes integradas creadas por Microsoft, aptitudes personalizadas o una combinación de ambas. Existen aptitudes integradas para el análisis de imágenes, incluido OCR y procesamiento de lenguaje natural. Otros ejemplos de aptitudes integradas incluyen reconocimiento de entidades, extracción de frases clave, fragmentación de texto en páginas lógicas, entre otros. Un conjunto de aptitudes es un objeto independiente de alto nivel que existe en un nivel equivalente a índices, indexadores y orígenes de datos, pero solo está operativo dentro del procesamiento del indexador. Como objeto de alto nivel, puede diseñar un conjunto de aptitudes una vez y, a continuación, hacer referencia a él en varios indexadores.
Mapas de sinónimos Un mapa de sinónimos es un objeto de nivel de servicio que contiene sinónimos definidos por el usuario. Este objeto se mantiene independientemente de los índices de búsqueda. Una vez cargado, puede apuntar cualquier campo que se pueda buscar al mapa de sinónimos (uno por campo).

Permisos y control de acceso

Puede usar la autenticación basada en claves o basada en roles a través de Microsoft Entra ID.

  • La autenticación basada en claves se basa en las claves de API que se generan para el servicio de búsqueda. Tener una clave válida genera la confianza, solicitud a solicitud, entre la aplicación que envía la solicitud y el servicio que se encarga de ella. Puede usar una clave de API de Administración para operaciones de lectura y escritura o una clave de API de consulta para el acceso de lectura a la colección de documentos de un índice de búsqueda.

  • Microsoft Entra ID autenticación y control de acceso basado en roles requiere que tenga un inquilino establecido en Microsoft Entra ID, con entidades de seguridad y asignaciones de roles. Los miembros de los siguientes roles tienen acceso al plano de datos. Puede crear roles personalizados si los roles integrados no son suficientes.

    Rol Access
    Colaborador del servicio de búsqueda Acceso a objetos, pero sin acceso al contenido del índice. Este rol no puede consultar un índice de búsqueda ni agregar, quitar o actualizar documentos en un índice de búsqueda. Este rol es para los administradores que necesitan administrar objetos, pero sin la capacidad de ver o acceder a los datos de objetos.
    Colaborador del índice de datos de búsqueda Acceso de lectura y escritura al contenido del índice. Este rol está pensado para desarrolladores o propietarios de índices que necesitan importar, actualizar o consultar la colección de documentos de un índice.
    Lector de índice de datos de búsqueda Acceso de lectura al contenido del índice. Este rol está pensado para aplicaciones y usuarios que ejecutan consultas.

Al usar roles en la conexión, la aplicación cliente presenta un token de portador en el encabezado de autorización. Consulte Autorización del acceso a una aplicación de búsqueda mediante Microsoft Entra ID para obtener ayuda con la configuración de esta opción.

Puede deshabilitar la autenticación basada en claves o la autenticación basada en roles. Si deshabilita la autenticación basada en roles, algunos roles integrados seguirán teniendo acceso. Consulte Microsoft Entra ID autenticación y control de acceso basado en roles para Azure AI Search para más información.

Llamar a las API

Las API documentadas en esta sección proporcionan acceso a operaciones en los datos de búsqueda, como la creación y rellenado de índices, la carga de documentos y las consultas. Al llamar a las API, tenga en cuenta los siguientes puntos:

  • Las solicitudes se deben emitir a través de HTTPS (en el puerto predeterminado 443).

  • Los URI de solicitud deben incluir la versión de api. El valor debe establecerse en una versión compatible, con el formato que se muestra en este ejemplo: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Los encabezados de solicitud deben incluir una clave de API o un token de portador para las conexiones autenticadas. Opcionalmente, puede establecer el encabezado Accept HTTP (Aceptar HTTP). Si no se establece el encabezado de tipo de contenido, se supone que el valor predeterminado es application/json.

Consulte también