Empleo de la API Búsqueda de Microsoft para consultar datosUse the Microsoft Search API to query data

Puede usar la API de Búsqueda de Microsoft para consultar datos de Microsoft 365 en sus aplicaciones.You can use the Microsoft Search API to query Microsoft 365 data in your apps.

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.Search requests run in the context of the signed-in user, identified using an access token with delegated permissions.

Casos de uso comúnCommon use cases

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.The Microsoft Search API provides a query method to search across your data in Microsoft Search, where you pass a searchRequest in the request body, defining the specifics of your search.

En esta sección, se muestran los casos de uso comunes del método de consulta, que se basan en las propiedades que se establecen en el cuerpo de la consulta searchRequest.This section lists the common use cases of the query method, based on the properties and parameters you set in the query searchRequest body.

Las solicitudes de búsqueda se ejecutan en nombre del usuario.Search requests run on behalf of the user. Los resultados de la búsqueda tienen un ámbito para hacer cumplir cualquier control de acceso aplicado a los elementos.Search results are scoped to enforce any access control applied to the items. Por ejemplo, en el contexto de los archivos, los permisos de los archivos se evalúan como parte de la solicitud de búsqueda.For example, in the context of files, permissions on the files are evaluated as part of the search request. 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.Users cannot access more items in a search than they can otherwise obtain from a corresponding GET operation with the same permissions and access control.

Casos de usoUse cases Propiedades para definir en el cuerpo de la solicitud de consultaProperties to define in the query request body
Resultados de búsqueda de ámbito basada en tipos de entidadScope search results based on entity types entityTypesentityTypes
Resultados de páginaPage results from y sizefrom and size
Obtención de los correos electrónicos más relevantesGet the most relevant emails enableTopResultsenableTopResults
Obtención de las propiedades seleccionadasGet selected properties fieldsfields
Uso de KQL en términos de consultaUse KQL in query terms queryquery

Búsqueda de ámbito basada en tipos de entidadScope search based on entity types

Defina el ámbito de la solicitud de búsqueda con la propiedad entityTypes en la carga de solicitud de consulta.Define the scope of the search request using the entityTypes property in the query request payload. En la siguiente tabla, se describen los tipos disponibles para realizar consultas, y los permisos compatibles para tener acceso a los datos.The following table describes the types available to query and the supported permissions to access the data.

EntityTypeEntityType Ámbito de permisos requerido para tener acceso a los elementosPermission scope required to access the items OrigenSource ComentarioComment
messagemessage Mail.Read, Mail.ReadWriteMail.Read, Mail.ReadWrite Exchange en líneaExchange Online Mensajes de correo electrónicoEmail messages.
eventevent Calendars.Read, Calendars.ReadWriteCalendars.Read, Calendars.ReadWrite Exchange en líneaExchange Online Eventos del calendarioCalendar events.
drivedrive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePointSharePoint Bibliotecas de documentosDocument libraries.
driveItemdriveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint y OneDriveSharePoint and OneDrive Archivos, carpetas, páginas y noticias.Files, folders, pages, and news.
listalist Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePoint y OneDriveSharePoint and OneDrive Listas.Lists. Tenga en cuenta que las bibliotecas de documentos también se devuelven como listas.Note that document libraries are also returned as lists.
listItemlistItem Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePoint y OneDriveSharePoint and OneDrive Elementos de lista.List items. Tenga en cuenta que los archivos y carpetas también se devuelven como elementos de lista. listItem es la súperclase del driveItem.Note that files and folders are also returned as list items; listItem is the super class of driveItem.
sitesite Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePointSharePoint Sitios en SharePointSites in SharePoint.

Resultados de búsqueda de páginaPage search results

Controle la paginación de los resultados de la búsqueda, especificando las dos propiedades siguientes en el cuerpo de la solicitud query:Control pagination of the search results by specifying the following two properties in the query request body:

  • from, un entero que indica el punto inicial basado en 0 para enumerar los resultados de la búsqueda en la página.from - An integer that indicates the 0-based starting point to list search results on the page. El valor predeterminado es 0.The default value is 0.

  • size, un entero que indica el número de resultados que se devolverán para una página.size - An integer that indicates the number of results to be returned for a page. El valor predeterminado es 25.The default value is 25.

Tenga en cuenta los siguientes límites si está buscando en la entidad event o message:Note the following limits if you're searching the event or message entity:

  • 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.from must start at zero in the first page request; otherwise, the request results in an HTTP 400 Bad request.
  • El número máximo de resultados por página (size) es 25 para message y event.The maximum results per page (size) is 25 for message and event.

No existe ningún límite superior para los elementos de SharePoint o OneDrive.There is no upper limit for SharePoint or OneDrive items. Un tamaño de página razonable es 200.A reasonable page size is 200. Un tamaño de página mayor generalmente provoca una latencia mayor.A larger page size generally incurs higher latency.

Procedimientos recomendados:Best practices:

  • Especificar una primera página más pequeña en la solicitud inicial.Specify a smaller first page in the initial request. Por ejemplo, especificar from como 0, size como 25.For example, specify from as 0, size as 25.

  • Paginar las páginas siguientes actualizando las propiedades from y size.Paginate subsequent pages by updating the from and size properties. Puede aumentar el tamaño de la página en cada solicitud posterior.You can increase the page size in each subsequent request. La siguiente tabla muestra un ejemplo.The following table shows an example.

    PáginaPage fromfrom sizesize
    11 00 2525
    22 2525 5050
    33 7575 7575
    44 150150 100100

Obtención de los correos electrónicos más relevantesGet the most relevant emails

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.When searching the message entity, specifying enableTopResults as true returns a hybrid list of messages: the first three messages in the response are sorted by relevance; the remaining messages are sorted by date/time.

Obtención de las propiedades seleccionadasGet selected properties

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.When searching an entity type, such as message, event, drive, driveItem, list, listItem, site, externalItem, you can include in the fields property specific entity properties to return in the search results. Esto es similar al uso de la opción consulta del sistema OData en las solicitudes REST.This is similar to using the OData system query option, $select in REST requests. 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.The search API does not technically support these query options because the behavior is expressed in the POST body.

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.For all these entity types, specifying the fields property reduces the number of properties returned in the response, optimizing the payload over the wire.

Las entidades listItem y externalItem son las únicas entidades compatibles que permiten obtener campos extendidos configurados en el esquema.The listItem and externalItem entities are the only supported entities that allow getting extended fields configured in the schema. No se pueden recuperar las propiedades extendidas de todas las demás entidades.You cannot retrieve extended properties from all the other entities. 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.For example, if you created a field for externalItem in the search schema, or if you have a custom column on a listItem, you can retrieve these properties from search. Para recuperar una propiedad extendida en un archivo, especifique el tipo listItem en la solicitud.To retrieve an extended property on a file, specify the listItem type in the request.

Si los fields especificados en la solicitud no se encuentran en el esquema, no se devolverán en la respuesta.If the fields specified in the request are not present in the schema, they will not be returned in the response. Los campos no válidos de la solicitud se omiten de forma silenciosa.Invalid fields in the request are silently ignored.

Si no especifica campos en la solicitud, obtendrá el conjunto predeterminado de propiedades para todos los tipos.If you do not specify any fields in the request, you will get the default set of properties for all types. Para las propiedades extendidas, listItem y externalItem se comportan de forma diferente cuando no se pasan campos en la solicitud:For extended properties, listItem and externalItem behave differently when no fields are passed in the request:

  • listItem no devuelve ningún campo personalizado.listItem will not return any custom field.
  • externalItem devuelve todos los campos marcados con el atributo retrievable en el esquema del conector de Microsoft Graph para esa conexión en particular.externalItem will return all the fields marked with the retrievable attribute in the Microsoft Graph connector schema for that particular connection.

Compatibilidad con Lenguaje de consultas de palabras clave (KQL)Keyword Query Language (KQL) support

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).Specify free text keywords, operators (such as AND, OR), and property restrictions in KQL syntax in the actual search query string (query property of the query request body). 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.The syntax and command depend on the entity types (in the entityTypes property) you target in the same query request body.

Según el tipo de entidad, las propiedades que se pueden buscar pueden variar.Depending on the entity type, the searchable properties vary. Para más información, vea:For details, see:

Control de erroresError handling

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.The search API returns error responses as defined by OData error object definition, each of which is a JSON object containing a code and a message.

Limitaciones conocidasKnown limitations

Esta API de búsqueda tiene las limitaciones siguientes:The search API has the following limitations:

  • El método query se define para permitir pasar una colección de una o más instancias de searchRequest a la vez.The query method is defined to allow passing a collection of one or more searchRequest instances at once. Sin embargo, actualmente el servicio solo admite un único recurso searchRequest a la vez.However, the service currently supports only a single searchRequest at a time.

  • El recurso searchRequest admite pasar varios tipos de entidades a la vez.The searchRequest resource supports passing multiple types of entities at a time. Sin embargo, actualmente la única combinación admitida es para entityTypes de SharePoint y OneDrive: driveItem, unidad de disco, sitio, lista, listItem.However, currently the only supported combination is for SharePoint and OneDrive entityTypes: driveItem, drive, site, list, listItem. Actualmente, no se admiten las combinaciones que impliquen mensaje, evento, tipos de SharePoint y OneDrive, o externalItem.Any combinations involving message, event, SharePoint and OneDrive types , or externalItem are currently not supported.

  • La propiedad contentSource, que define la conexión que se usará, solo se puede aplicar cuando entityType se especifica como externalItem.The contentSource property, which defines the connection to use, is only applicable when entityType is specified as externalItem.

  • La API de búsqueda no es compatible con la ordenación personalizada para message, event o externalItem.The search API does not support custom sort for message, event or externalItem.

  • La API de búsqueda no es compatible con agregaciones para message, event, site o drive.The search API does not support aggregations for message, event, site or drive.

  • Las personalizaciones en la búsqueda de SharePoint, como un esquema de búsqueda personalizado o fuentes de resultados, pueden interferir con el funcionamiento de la API de Búsqueda de Microsoft.Customizations in SharePoint search, such as a custom search schema or result sources, can interfere with the operation of the Microsoft Search API.

Consulte tambiénSee also