Compartir a través de

Empleo de la API Búsqueda de Microsoft para consultar datos

  • Artículo

Puede usar la API de Búsqueda de Microsoft para consultar datos de Microsoft 365 en sus aplicaciones.

Las solicitudes de búsqueda se ejecutan en el contexto del usuario que ha iniciado sesión, identificado mediante un token de acceso con permisos delegados.

Casos de uso común

La API de Búsqueda de Microsoft ofrece un método de consulta para buscar en los datos en Microsoft Search, donde se pasa un searchRequest en el cuerpo de la solicitud. Esto define las especificaciones de la búsqueda.

En esta sección se enumeran los casos de uso comunes del método de consulta, en función de las propiedades y los parámetros que establezca en el cuerpo de searchRequest de la consulta.

Las solicitudes de búsqueda se ejecutan en nombre del usuario. Los resultados de la búsqueda tienen un ámbito para hacer cumplir cualquier control de acceso aplicado a los elementos. Por ejemplo, en el contexto de los archivos, los permisos de los archivos se evalúan como parte de la solicitud de búsqueda. Los usuarios no pueden obtener acceso a más elementos en una búsqueda del que, de otra forma, pueden obtener de una operación GET correspondiente con los mismos permisos y controles de acceso.

Casos de uso Propiedades para definir en el cuerpo de la solicitud de consulta
Resultados de búsqueda de ámbito basada en tipos de entidad entityTypes
Resultados de página from y size
Obtención de los correos electrónicos más relevantes enableTopResults
Obtención de las propiedades seleccionadas fields
Uso de KQL en términos de consulta query
Contraer los resultados de la búsqueda collapseProperties
Ordenar los resultados de búsqueda sortProperties
Restricción de los resultados haciendo uso de las agregaciones agregaciones
Solicitar corrección ortográfica queryAlterationOptions
Diseño de pantalla de búsqueda (versión preliminar) resultTemplateOptions

Búsqueda de ámbito basada en tipos de entidad

Defina el ámbito de la solicitud de búsqueda con la propiedad entityTypes en la carga de solicitud de consulta. En la siguiente tabla, se describen los tipos disponibles para realizar consultas, y los permisos compatibles para tener acceso a los datos.

EntityType Ámbito de permisos requerido para tener acceso a los elementos Origen Comentario
acrónimo Acronym.Read.All Búsqueda de Microsoft Acrónimos en Microsoft Search en su organización.
bookmark Bookmark.Read.All Búsqueda de Microsoft Marcadores en Búsqueda de Microsoft en su organización.
chatMessage Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All Teams Mensajes de Teams.
message Mail.Read, Mail.ReadWrite Exchange en línea Mensajes de correo electrónico
event Calendars.Read, Calendars.ReadWrite Exchange en línea Eventos del calendario
drive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint Bibliotecas de documentos
driveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint y OneDrive Archivos, carpetas, páginas y noticias.
lista Sites.Read.All, Sites.ReadWrite.All SharePoint y OneDrive Listas. Tenga en cuenta que las bibliotecas de documentos también se devuelven como listas.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint y OneDrive Elementos de lista. Tenga en cuenta que los archivos y carpetas también se devuelven como elementos de lista. listItem es la súperclase del driveItem.
qna QnA.Read.All Búsqueda de Microsoft Preguntas y respuestas en Búsqueda de Microsoft en su organización.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Sitios en SharePoint

Resultados de búsqueda de página

Controle la paginación de los resultados de la búsqueda, especificando las dos propiedades siguientes en el cuerpo de la solicitud query:

  • from, un entero que indica el punto inicial basado en 0 para enumerar los resultados de la búsqueda en la página. El valor predeterminado es 0.

  • size, un entero que indica el número de resultados que se devolverán para una página. El valor predeterminado son 25 resultados. El tamaño de página máximo es 1000.

Tenga en cuenta los siguientes límites si está buscando en la entidad event o message:

  • from debe comenzar en cero en la primera solicitud de página; en caso contrario, la solicitud dará como resultado un error HTTP 400 Bad request.
  • El número máximo de resultados por página (size) es 25 para message y event.

El límite superior para los elementos de SharePoint o OneDrive es 1000. Un tamaño de página razonable es 200. Un tamaño de página mayor generalmente provoca una latencia mayor.

Procedimientos recomendados:

  • Especificar una primera página más pequeña en la solicitud inicial. Por ejemplo, especificar from como 0, size como 25.

  • Paginar las páginas siguientes actualizando las propiedades from y size. Puede aumentar el tamaño de la página en cada solicitud posterior. La siguiente tabla muestra un ejemplo.

    Página from size
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Obtención de los correos electrónicos más relevantes

Al buscar en la entidad message, especificar enableTopResults como true devuelve una lista híbrida de mensajes: los primeros tres mensajes de la respuesta se ordenan por relevancia y el resto de los mensajes se ordenan por fecha y hora.

Obtención de las propiedades seleccionadas

Al buscar un tipo de entidad, como por ejemplo, message, event, drive, driveItem, list, listItem, site, externalItem, puede incluir en la propiedad fields las propiedades de entidad específicas que desea que sean devueltas en los resultados de la búsqueda. Esto es similar al uso de la opción consulta del sistema OData en las solicitudes REST. La API de búsqueda no es compatible de manera técnica con estas opciones de consulta porque el comportamiento se expresa en el cuerpo POST.

Para todos estos tipos de entidades, al especificar la propiedad fields, se reduce el número de propiedades devueltas en la respuesta, lo que optimiza la carga durante la conexión.

Las entidades listItem y externalItem son las únicas entidades compatibles que permiten obtener campos extendidos configurados en el esquema. No se pueden recuperar propiedades extendidas de todas las demás entidades mediante la API de búsqueda. Por ejemplo, si ha creado un campo para externalItem en el esquema de búsqueda, o si tiene una columna personalizada en un listItem, sí puede recuperar estas propiedades de la búsqueda. Para recuperar una propiedad extendida en un archivo, especifique el tipo listItem en la solicitud.

Si los campos especificados en la solicitud no están presentes en el esquema o no se marcan como recuperables, no se devolverán en la respuesta. Los campos no válidos de la solicitud se omiten de forma silenciosa.

Si no especifica ningún campo en la solicitud, obtendrá el conjunto predeterminado de propiedades para todos los tipos. Para las propiedades extendidas, listItem y externalItem se comportan de forma diferente cuando no se pasan campos en la solicitud:

  • listItem no devuelve ningún campo personalizado.
  • externalItem devuelve todos los campos marcados con el atributo retrievable en el esquema del conector de Microsoft Graph para esa conexión en particular.

Compatibilidad con Lenguaje de consultas de palabras clave (KQL)

Especifique las palabras clave de texto sin formato, operadores (como AND, OR) y restricciones de propiedad en la sintaxis de KQL en la cadena de consulta de búsqueda real (propiedad query del cuerpo de solicitud de query). El operador XRANK aumenta la clasificación dinámica de los elementos en función de determinadas repeticiones de términos dentro de la expresión de coincidencia, sin cambiar qué elementos coinciden con la consulta. La sintaxis y el comando dependen de los tipos de entidad (en la propiedad entityTypes) a los que apuntas en el cuerpo de solicitud de la query.

Según el tipo de entidad, las propiedades que se pueden buscar pueden variar. Para más información, vea:

Contraer los resultados de la búsqueda

La propiedad collapseProperties contiene un conjunto de criterios, campos y tamaño límite utilizado para contraer los resultados en un cuerpo de respuesta. El uso de collapseProperties solo afecta a las acciones de recuperación, pero no de clasificación y ordenación.

El método de consulta permite personalizar la propiedad collapse especificando collapseProperties en el requests parámetro , que es una colección de objetos collapseProperty . Esto le permite especificar un conjunto de una o varias propiedades de contraer.

Tenga en cuenta que los resultados contraíble se admiten actualmente para los siguientes tipos de entidad: driveItem, listItem, drive, list, site, externalItem.

Para usar la cláusula de contracción de forma eficaz, las propiedades a las que se aplica deben ser consultables y se pueden ordenar o refinar. Cuando se usa la contracción de varios niveles, es importante tener en cuenta que el tamaño límite de cada propiedad subsiguiente especificado en una solicitud de varios niveles debe ser igual o menor que el anterior. Si el tamaño límite de una propiedad posterior supera el anterior, el servidor responderá con un HTTP 400 Bad Request error.

Consulte los resultados de la búsqueda de contraídos para obtener más ejemplos de resultados de contracción.

Ordenar resultados de búsqueda

Los resultados de la búsqueda en la respuesta se ordenan según el criterio de ordenación predeterminado:

  • message y event se ordenan por fecha.
  • Todos los tipos de conector, persona, OneDrive y SharePoint se ordenan por relevancia.

El método de consulta permite personalizar el orden de búsqueda especificando las sortProperties en el requests parámetro , que es una colección de objetos sortProperty . Esto permite especificar una lista de una o más propiedades que se pueden ordenar y el criterio para establecer dicho orden.

Tenga en cuenta que la ordenación de resultados solo es compatible actualmente con los siguientes tipos de SharePoint y OneDrive: driveItem, listItem, list, site.

Las propiedades en las que se aplica la cláusula de ordenación deben poder ordenarse en el esquema de búsqueda de SharePoint. Si la propiedad especificada en la solicitud no se puede ordenar o no existe, la respuesta devolverá un error, HTTP 400 Bad Request. Tenga en cuenta que no puede ordenar documentos por relevancia utilizando la sortProperty.

Al especificar el name de un objeto de sortProperty, puede utilizar el nombre de la propiedad del tipo de Microsoft Graph (por ejemplo, en driveItem), o el nombre de la propiedad administrada en el índice de búsqueda.

Consulte ordenar resultados de búsqueda para ver ejemplos que muestran cómo ordenar resultados.

Restricción de los resultados haciendo uso de las agregaciones

Las agregaciones (también conocidas como refinadores en SharePoint) son una forma muy común de mejorar la experiencia de búsqueda. Además de los resultados, proporcionan información adicional sobre el conjunto coincidente de los resultados de búsqueda. Por ejemplo, puede proporcionar información acerca de los autores más representados de los documentos que coinciden con la consulta, los tipos de archivo más representados, etc.

En la searchRequest, especifique las agregaciones que se deberán devolver además de los resultados de la búsqueda. La descripción de cada agregación se define en la aggregationOption, donde se especifica la propiedad en la que se debe calcular la agregación y el número de searchBucket que se debe devolver en la respuesta.

Las propiedades en las que se solicita la agregación deben poder restringirse en el esquema de búsqueda de SharePoint. Si la propiedad especificada no es restringible o no existe, la respuesta devuelve HTTP 400 Bad Request.

Una vez que se devuelve la respuesta que contiene la colección de objetos searchBucket, es posible restringir la solicitud de búsqueda solo para los elementos coincidentes que contengan un searchBucket. Para ello, se pasa el valor aggregationsFilterToken en la propiedad aggregationFilters de la searchRequest posterior.

Actualmente, se admiten las agregaciones para cualquier propiedad que pueda restringirse en los tipos de SharePoint y OneDrive: driveItem, listItem, list, site, y en los conectores externalItem de Microsoft Graph.

Para obtener ejemplos que muestran cómo usar la agregación para mejorar y restringir los resultados de búsqueda, vea Refinar resultados de búsqueda.

Solicitar corrección ortográfica

La corrección ortográfica es una forma popular de manejar las diferencias entre los errores tipográficos en la consulta de un usuario y las palabras correctas en el contenido coincidente. Cuando se detectan errores tipográficos en la consulta original de usuario, puede obtener el resultado de búsqueda para la consulta de usuario original o para la consulta alternativa corregida. También puede obtener la información de corrección ortográfica de los errores ortográficos en la propiedad queryAlterationResponse de searchResponse.

En el cuerpo de la solicitud del método de consulta, especifique el queryAlterationOptions que se debe aplicar a la consulta para las correcciones ortográficas. La descripción de queryAlterationOptions se define en elsearchRequest.

Para obtener ejemplos que muestren cómo usar las correcciones ortográficas, consulte Solicitar corrección ortográfica.

Diseño de pantalla de búsqueda

La API de búsqueda permite representar los resultados de la búsqueda de conectores mediante el diseño de pantalla o la plantilla de resultados configurada por el administrador de TI para cada conector. Las plantillas de resultado son Tarjetas adaptables, una combinación semánticamente significativa de diseño y datos.

Para obtener la plantilla de resultados en searchResponse, debe establecer la propiedad enableResultTemplate en true, que se define en el resultTemplateOptions en el searchRequest. La respuesta incluye un resultTemplateId para cada acierto de búsqueda, que se asigna a uno de los diseños de presentación incluidos en el diccionario resultTemplates en la respuesta.

Para ver ejemplos que muestran cómo representar resultados de búsqueda, vea Usar diseño para mostrar búsquedas.

Control de errores

La API de búsqueda devuelve respuestas de error definidas por definición de objeto de error de OData, cada una de las cuales es un objeto JSON que contiene un código y un mensaje.

Limitaciones conocidas

Esta API de búsqueda tiene las limitaciones siguientes:

  • El método query se define para permitir pasar una colección de una o más instancias de searchRequest a la vez. Sin embargo, actualmente el servicio solo admite un único recurso searchRequest a la vez.

  • El recurso searchRequest admite pasar varios tipos de entidades a la vez. En la tabla siguiente se enumeran las combinaciones que se admiten.

    Tipo de entidad acrónimo marcador mensaje chatMessage drive driveItem evento externalItem lista listItem persona qna sitio
    acrónimo True True - - - - - - - - - True -
    marcador True True - - - - - - - - - True -
    chatMessage - - - Verdadero - - - - - - - - -
    drive - - - - True True - True True True - - True
    driveItem - - - - True True - True True True - - True
    evento - - - - - - Verdadero - - - - - -
    externalItem - - - - True True - True True True - - True
    lista - - - - True True - True True True - - True
    listItem - - - - True True - True True True - - True
    mensaje - - Verdadero - - - - - - - - - -
    persona - - - - - - - - - - Verdadero - -
    qna True True - - - - - - - - - True -
    sitio - - - - True True - True True True - - True

  • La propiedad contentSource, que define la conexión que se usará, solo se puede aplicar cuando entityType se especifica como externalItem.

  • La API de búsqueda no admite la ordenación personalizada de acrónimos, marcadores, mensajes, chatMessage, eventos, personas, qna o externalItem.

  • La API de búsqueda no admite agregaciones para acrónimos, marcadores, mensajes, eventos, sitios, personas, qna o unidades.

  • La API de búsqueda no admite xrank para acrónimos, marcadores, mensajes, chatMessage, eventos, personas, qna o externalItem.

  • La búsqueda de invitados no admite búsquedas de acrónimos, marcadores, mensajes, chatMessage, eventos, personas, qna o externalItem.

  • Las personalizaciones de la búsqueda de SharePoint, como un esquema de búsqueda personalizado o orígenes de resultados, pueden interferir con las operaciones de Microsoft Search API.

  • La API de búsqueda no admite el esquema de búsqueda de nivel de sitio. Use el esquema de búsqueda predeterminado o de nivel de inquilino.

Contenido relacionado