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

  • Artículo

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

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.

Precaución

Se han cambiado o eliminado, o están en desuso, los nombres de algunas de las propiedades del recurso que se usa para la solicitud y respuesta de la API de Búsqueda de Microsoft. Obtenga más información sobre el desuso. Actualice las consultas de las API de búsqueda en las aplicaciones anteriores correspondientes.

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 acceder a más elementos de una búsqueda de los que pueden obtener de una operación GET correspondiente con los mismos permisos y control 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
Buscar tipos personalizados importados con conectores contentSources
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
Siglas Acronym.Read.All Búsqueda de Microsoft Acrónimos de Microsoft Búsqueda en su organización.
bookmark Bookmark.Read.All Búsqueda de Microsoft Marcadores de Microsoft Búsqueda 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. Las bibliotecas de documentos también se devuelven como listas.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint y OneDrive Elementos de lista. Los archivos y carpetas también se devuelven como elementos de lista; listItem es la superclase de driveItem.
externalItem ExternalItem.Read.All Conectores de Microsoft Graph Todo el contenido integrado con la API de conectores de Microsoft Graph.
person People.Read Exchange Online Contactos personales y contactos u objetos de su organización a los que se pueda dirigir.
Qna QnA.Read.All Búsqueda de Microsoft Preguntas y respuestas en Microsoft Búsqueda 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 o person que 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 admite técnicamente 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, driveItem y externalItem son las únicas entidades admitidas que permiten obtener campos recuperables 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 recuperable para externalItem en el esquema de búsqueda, o si tiene una columna personalizada recuperable en un listItem o driveItem, puede recuperar estas propiedades de la búsqueda. Para recuperar una propiedad extendida en un archivo, especifique el tipo listItem o driveItem en la solicitud.

Si los campos especificados en la solicitud no están presentes en el esquema o no están marcados 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, driveItem y externalItem se comportan de forma diferente cuando no se pasa ningún campo en la solicitud:

  • listItem no devolverá ningún campo personalizado.
  • driveItem devolverá un elemento listItem interno con un campo vacío.
  • 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, que se usan para contraer los resultados en un cuerpo de respuesta. El uso de collapseProperties solo afecta a la recuperación, pero no a la clasificación o 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.

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

Las propiedades en las que se aplica la cláusula collapse deben ser consultables y ordenables o refinables. Para contraer varios niveles, cada tamaño de límite de propiedad posterior especificado en una solicitud de varios niveles debe ser menor o igual que el anterior; De lo contrario, la respuesta devuelve un HTTP 400 Bad Request error.

Para obtener ejemplos que muestran cómo contraer resultados, consulte contraer los resultados de búsqueda.

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.

Los resultados de ordenación solo se admiten actualmente en los siguientes tipos de SharePoint y OneDrive: driveItem, listItem, list, site.

Las propiedades a las que se aplica la cláusula de ordenación deben ser ordenables en el esquema de búsqueda de SharePoint. Si la propiedad especificada en la solicitud no se puede ordenar o no existe, la respuesta devuelve un error, HTTP 400 Bad Request. No se puede especificar para ordenar documentos por relevancia mediante 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 manera popular de mejorar una 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 refinable 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 refinar la solicitud de búsqueda solo a los elementos coincidentes contenidos en 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.

Cosnsulte restringir los resultados de búsqueda para ver ejemplos que muestran cómo usar la agregación para mejorar y restringir los resultados de la 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 del searchResponse.

En searchRequest, especifique las queryAlterationOptions que se deben aplicar a la consulta para correcciones ortográficas. Para más información sobre la propiedad queryAlterationOptions, vea searchAlterationOptions.

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 búsqueda de conectorescon un diseño de pantalla o 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 como true la propiedad enableResultTemplate, definida en 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.

Consulte Usar diseño de visualización de búsqueda para obtener ejemplos.

La API de Búsqueda permite a los usuarios invitados buscar elementos en SharePoint o OneDrive que se han compartido con ellos. Para acceder a la lista de usuarios invitados, vaya a la Centro de administración de Microsoft 365 y, en el panel de navegación izquierdo, elija Usuarios y seleccione Usuarios invitados.

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 API de Microsoft Búsqueda.

  • 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.

Advertencia de degradación de cambio de esquema

A partir del 31 de agosto de 2023, la versión beta del recurso externalItem en el espacio de nombres de Microsoft Graph quedará en desuso. En el futuro, use la versión del recurso en el espacio de nombres Microsoft.Graph.ExternalConnectors . Asegúrese de actualizar las dependencias de espacio de nombres antes de la fecha especificada. Como alternativa, considere la posibilidad de realizar la transición a la versión v1.0 de la API.

En la versión beta, las propiedades que se usan en una solicitud de búsqueda y una respuesta se han cambiado de nombre o se han quitado. En la mayoría de los casos, las propiedades originales están quedando en desuso y se reemplazarán por las propiedades actuales, tal como se muestra en la tabla siguiente.

Se recomienda actualizar las aplicaciones existentes para usar los nombres de propiedad y tipo actuales, y para obtener los nombres de propiedad actuales en la respuesta. Por compatibilidad con versiones anteriores, las propiedades y tipos originales son accesibles y funcionales hasta el 30 de septiembre de 2023, después de lo cual se quitarán.

Recurso Tipo de cambio Propiedad original Propiedad actual
searchRequest Cambiar el nombre de la propiedad stored_fields fields
searchQuery Cambiar el nombre de la propiedad query_string queryString
searchQueryString Descartar recurso No aplicable No aplicable
searchHit Cambiar el nombre de la propiedad _id hitId
searchHit Cambiar el nombre de la propiedad _score rank
searchHit Quitar propiedad _sortField No aplicable
searchHit Cambiar el nombre de la propiedad _source resource
searchHit Cambiar el nombre de la propiedad _summary summary
entityTypes Cambiar el nombre de un valor de enum unknownfuturevalue unknownFutureValue

Contenido relacionado