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, y se documentan en esta sección.
Las operaciones del plano de control para la administración del servicio se tratan en una API REST de administración de independiente.
Documentos 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 Referencia > plano de datos.
Conceptos clave
Azure AI Search tiene los conceptos de servicios de búsqueda, índices, documentos, indexadores, orígenes de datos, conjuntos de aptitudesy asignaciones 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 buscar.
- 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 agrega de enriquecimiento con IA y vectorización integrada a la canalización de indexación. Los conjuntos de aptitudes siempre están asociados a un indexador. Invocan el aprendizaje automático para extraer o fragmentar texto, vectorizar contenido, deducir características o agregar estructura al contenido para mejorar la indexación mediante un servicio de búsqueda.
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 un type. Puede usar las conexiones proporcionadas por Microsoft para Azure o conectores 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 de dirección URL siempre incluyen /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 el uso. Por ejemplo, searchable campos se usan en la búsqueda de texto completo y, por tanto, se tokenizan durante la indexación. Un índice también define otras construcciones, como perfiles de puntuación para el ajuste de relevancia, proveedores de sugerencias, configuraciones semánticas y analizadores personalizados. |
| Indizadores | 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 indexar en un índice de búsqueda de destino. Los indexadores leen desde un origen externo mediante la información de conexión de 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 se usa para aplicar modelos de inteligencia artificial o aprendizaje profundo para analizar o transformar contenido para mejorar la capacidad de búsqueda en un índice. El contenido de un conjunto de aptitudes es una o varias aptitudes, que se pueden aptitudes integradas creadas por Microsoft, aptitudes personalizadas o una combinación de ambas. Existen aptitudes integradas para el análisis de imágenes, incluidos OCR y procesamiento de lenguaje natural. Otros ejemplos de aptitudes integradas incluyen el reconocimiento de entidades, la extracción de frases clave, la 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 del id. de Microsoft Entra.
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 establece confianza, por solicitud, entre la aplicación que envía la solicitud y el servicio que lo controla. Puede usar una clave de API de administración de para operaciones de lectura y escritura o una clave de API de consulta de para obtener acceso de lectura a la colección de documentos de un índice de búsqueda.
autenticación de Microsoft Entra ID y control de acceso basado en rol requiere que tenga un inquilino establecido en el identificador de Microsoft Entra, con entidades de seguridad y asignaciones de roles. Los miembros de los roles siguientes tienen acceso al plano de datos. Puede crear roles personalizados si los roles integrados no son suficientes.
Rol Acceso Colaborador del servicio de búsqueda Acceso a objetos, pero sin acceso al contenido del índice. Este rol crea un índice de búsqueda y otros objetos de nivel superior, pero no puede consultar un índice de búsqueda ni agregar, quitar ni actualizar documentos en un índice de búsqueda. Este rol es para los desarrolladores que crean, actualizan y eliminan definiciones de objetos. También 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 es 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 es para aplicaciones y usuarios que ejecutan consultas.
Cuando se usan roles en la conexión, la aplicación cliente presenta un token de portador en el encabezado de autorización. Consulte Autorizar el acceso a una aplicación de búsqueda mediante el identificador de Entra de Microsoft para obtener ayuda para configurarlo.
Puede deshabilitar la autenticación basada en claves o la autenticación basada en roles. Si deshabilita la autenticación basada en roles, solo se aplica a las operaciones del plano de datos. Las operaciones del plano de control, como la administración de servicios, siempre usan la autenticación basada en roles. Consulte autenticación de Microsoft Entra ID y control de acceso basado en rol para azure AI Search para más información.
Llamada a las API
Las API documentadas en esta sección proporcionan acceso a las operaciones en los datos de búsqueda, como la creación y el rellenado de índices, la carga de documentos y las consultas. Al llamar a las API, tenga en cuenta los siguientes puntos:
Las solicitudes deben emitirse a través de HTTPS (en el puerto predeterminado 443).
Los URI de solicitud deben incluir elde
api-version . 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=2023-11-01Encabezados de solicitud deben incluir un de clave de APIo un token de portador para las conexiones autenticadas. Opcionalmente, puede establecer el encabezado ACCEPT HTTP. Si no se establece el encabezado de tipo de contenido, se supone que el valor predeterminado es application/json.