REST del servicio Azure Cognitive Search

Azure Cognitive Search es un servicio de búsqueda en la nube totalmente administrado que proporciona una experiencia de búsqueda enriquecida sobre el contenido propiedad del usuario. Una manera de agregar la funcionalidad de búsqueda es a través de las API REST de búsqueda, con operaciones que crean y administran índices, cargan datos, implementan características de búsqueda, ejecutan consultas y controlan los resultados.

Se puede usar una API REST de administración independiente para crear o modificar el propio servicio. Como alternativa, puede usar el portal para muchas tareas de administración de servicios y contenido. Para empezar, consulte Creación de un servicio de búsqueda en Azure Portal.

Conceptos clave

Cognitive Search tiene los conceptos de los servicios de búsqueda y los índices y documentos:

  • Un servicio de búsqueda contiene uno o varios índices.
  • Un índice proporciona almacenamiento persistente de documentos de búsqueda.
  • Los documentos de búsqueda se cargan desde orígenes externos en forma de documentos JSON y se insertan en un índice para que se puedan buscar.

También puede crear un indexador para automatizar la indexación. Un indexador tiene un origen de datos y apunta a un índice. Opcionalmente, también puede tener un conjunto de aptitudes que agregue inteligencia artificial a la canalización del indexador.

El enriquecimiento con IA es una extensión de indexadores que agrega transformaciones de aprendizaje automático que extraen o generan texto, o agregan estructura al contenido para que un servicio de búsqueda pueda indexarla. La construcción que impulsa el enriquecimiento con IA se denomina conjunto de aptitudes. Durante la ingesta de datos, define una secuencia de pasos que detectan, estructuran o transforman contenido que, de lo contrario, no se puede buscar (por ejemplo, contenido de imagen).

Todos juntos, hay cinco tipos de operaciones que se pueden ejecutar en el servicio:

Operación Descripción
Index Cree, elimine, actualice o configure un índice de búsqueda.
Documento Agregue, actualice o elimine documentos en el índice, consulte el índice o busque documentos específicos por identificador.
Indizador Automatice los aspectos de una operación de indexación mediante la configuración de un origen de datos y un indexador que puede programar o ejecutar a petición. Esta característica es compatible con un número limitado de tipos de origen de datos en Azure.
Conjunto de aptitudes Parte de una carga de trabajo de enriquecimiento con IA , un conjunto de aptitudes define una serie de procesamiento de enriquecimiento que extrae o crea texto que permite búsquedas a partir de texto no estructurado, archivos de aplicación o archivos de imagen. Un indexador invoca un conjunto de aptitudes.
Mapa de sinónimos Un mapa de sinónimos es un recurso de nivel de servicio que contiene sinónimos definidos por el usuario. Este recurso 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).

Llamada 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).

  • Las solicitudes deben incluir la versión de api en el URI. 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 que se generó para el servicio de búsqueda que ha aprovisionado. 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. Opcionalmente, puede establecer el encabezado Accept HTTP . Si no se establece el encabezado, se supone que el valor predeterminado es application/json.

Autenticación de clave

Cada solicitud HTTP al servicio de búsqueda se autentica en función de dos partes de información: una dirección URL del servicio de búsqueda y una clave de API que proporciona una prueba de que la solicitud procede de una entidad de confianza. Hay dos tipos de claves de API para distintos niveles de operación.

Clave Descripción límites
Administración Las claves de administrador conceden derechos completos a todas las operaciones, incluida la capacidad de administrar el servicio, obtener el estado y las definiciones de objetos, y crear y eliminar índices, indexadores y orígenes de datos.

Dos claves de API de administrador, conocidas como claves principales y secundarias en el portal, se generan automáticamente cuando se crea el servicio y se pueden regenerar individualmente a petición. Tener dos claves le permite la rotación de una clave mientras se usa la segunda clave para un acceso continuado al servicio.

Las claves de administración solo se especifican en los encabezados de la solicitud HTTP. No se puede colocar una clave de API de administrador en una dirección URL.
Máximo 2 por servicio
Consultar Las claves de consulta conceden acceso de solo lectura al contenido dentro de un índice (documentos) y normalmente se distribuyen a las aplicaciones cliente que emiten solicitudes de búsqueda.

Las claves de consulta se crean bajo petición. Puede crearlas manualmente en el portal o mediante programación con la API de REST de administración.

Las claves de consulta se pueden especificar en un encabezado de solicitud HTTP para operaciones de búsqueda y sugerencias. Como alternativa, puede pasar una clave de consulta como un parámetro en una dirección URL. En función de cómo formule la solicitud la aplicación cliente, puede resultar más fácil pasar la clave como un parámetro de consulta:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 por servicio

Visualmente, no hay distinción entre las claves de administración y de consulta. Ambas claves son cadenas formadas por 32 caracteres alfanuméricos generados aleatoriamente. Si pierde el seguimiento de qué tipo de clave se especifica en la aplicación, puede comprobar los valores de clave en el portal o usar la API rest de administración para devolver el valor y el tipo de clave.

Nota

Se considera una práctica poco segura pasar datos confidenciales, como una api-key en el identificador URI de la solicitud. Por este motivo, Azure Cognitive Search solo aceptará una clave de consulta como en api-key la cadena de consulta y debe evitar hacerlo a menos que el contenido del índice esté disponible públicamente. Como regla general, se recomienda pasar la api-key como un encabezado de solicitud.

Autorización

Cognitive Search admite el control de acceso basado en rol de Azure (RBAC de Azure) para la administración del servicio de búsqueda, a través de los roles Propietario, Colaborador y Lector.

Opcionalmente, para las soluciones de búsqueda que pueden usar características en versión preliminar, puede usar RBAC de Azure para controlar el acceso a índices y otros objetos en un servicio de búsqueda. Este enfoque requiere un servicio de búsqueda configurado para RBAC de Azure en el plano de datos y un encabezado de autorización en las llamadas API REST que se autentican mediante Azure Active Directory.

Consulte también