Usar parámetros de consulta para personalizar respuestasUse query parameters to customize responses

Microsoft Graph admite parámetros de consulta opcionales que puede usar para especificar y controlar la cantidad de datos devueltos en una respuesta.Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response. La compatibilidad con los parámetros de consulta exactos varía de una operación API a otra y, en función de la API, puede diferir entre los puntos de conexión de las versiones 1.0 y beta.The support for the exact query parameters varies from one API operation to another, and depending on the API, can differ between the v1.0 and beta endpoints.

Sugerencia

En el punto de conexión beta, el prefijo $ es opcional.On the beta endpoint, the $ prefix is optional. Por ejemplo, en lugar de $filter, puede usar filter.For example, instead of $filter, you can use filter. En el punto de conexión v1, el prefijo $ es opcional solo para un subconjunto de las API.On the v1 endpoint, the $ prefix is optional for only a subset of APIs. Para simplificar, incluya $ siempre si usa el punto de conexión v1.For simplicity, always include $ if using the v1 endpoint.

Los parámetros de consulta pueden ser opciones de consulta de sistema de OData u otros parámetros de consulta.Query parameters can be OData system query options or other query parameters.

Opciones de consulta de sistema de ODataOData system query options

Una operación de API de Microsoft Graph podría admitir una o varias de las siguientes opciones de consulta de sistema de OData.A Microsoft Graph API operation might support one or more of the following OData system query options. Estas opciones de consulta son compatibles con el lenguaje de consulta de OData V4.These query options are compatible with the OData V4 query language.

Nota: OData 4,0 es compatible con las opciones de consulta de sistema solo en operaciones GET.Note: OData 4.0 supports system query options in only GET operations.

Haga clic en los ejemplos para probarlos en Probador de Graph.Click the examples to try them in Graph Explorer.

NombreName DescripciónDescription EjemploExample
$count$count Recupera el número total de recursos coincidentes.Retrieves the total count of matching resources. /me/messages?$top=2&$count=true
$expand$expand Recupera los recursos relacionados.Retrieves related resources. /groups?$expand=members
$filter$filter Filtra los resultados (filas).Filters results (rows). /users?$filter=startswith(givenName,'J')
$format$format Devuelve los resultados en el formato de medio especificado.Returns the results in the specified media format. /users?$format=json
$orderby$orderby Ordena los resultados.Orders results. /users?$orderby=displayName desc
$search$search Devuelve los resultados en función de criterios de búsqueda.Returns results based on search criteria. /me/messages?$search=pizza
$select$select Filtra las propiedades (columnas).Filters properties (columns). /users?$select=givenName,surname
$skip$skip Indexa en un conjunto de resultados. También se usa en algunas API para implementar la paginación y se puede usar junto a $top para paginar manualmente los resultados.Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. /me/messages?$skip=11
$top$top Establece el tamaño de la página de resultados.Sets the page size of results. /users?$top=2

Otros parámetros de consultaOther query parameters

NombreName DescripciónDescription EjemploExample
$skipToken$skipToken Recupera la siguiente página de resultados de conjuntos de resultados que abarcan varias páginas. (Algunas API usan $skip en su lugar).Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.) /users?$skiptoken=X%274453707402000100000017...

Otras funciones URL de ODataOther OData URL capabilities

Las siguientes funciones de OData 4,0 son segmentos URL, no parámetros de consulta.The following OData 4.0 capabilities are URL segments, not query parameters.

NombreName DescripciónDescription EjemploExample
$ref$ref Actualice la pertenencia a entidades en una colección.Updates entities membership to a collection. POST /groups/{id}/members/$ref
$value$value Recupere o actualice el valor binario de un elemento.Retrieves or updates the binary value of an item. GET /me/photo/$value

Codificación de parámetros de consultaEncoding query parameters

Los valores de los parámetros de consulta deben ser codificados por porcentaje.The values of query parameters should be percent-encoded. Muchos clientes HTTP, exploradores y herramientas (como el Probador de Graph) le servirán de ayuda.Many HTTP clients, browsers, and tools (such as the Graph Explorer) will help you with this. Si una consulta produce un error, puede deberse a que los valores de los parámetros de consulta no se han codificado correctamente.If a query is failing, one possible cause is failure to encode the query parameter values appropriately.

Una dirección URL sin codificar tiene el siguiente aspecto:An unencoded URL looks like this:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

Una dirección URL codificada correctamente tiene el siguiente aspecto:A properly encoded URL looks like this:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

Escape para las comillas simplesEscaping single quotes

En las solicitudes que usen comillas simples, si algún parámetro tiene valores que contengan también comillas simples, estas deben tener doble escape. De lo contrario, se producirá un error en la solicitud porque la sintaxis no es válida.For requests that use single quotes, if any parameter values also contain single quotes, those must be double escaped; otherwise, the request will fail due to invalid syntax. En el ejemplo, el valor de cadena let''s meet for lunch? tiene el escape de comillas simples.In the example, the string value let''s meet for lunch? has the single quote escaped.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

parámetro de recuentocount parameter

Use el parámetro de consulta $count para incluir un recuento del número total de elementos de una colección junto con la página de valores de datos que se devuelve desde Microsoft Graph.Use the $count query parameter to include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph.

Por ejemplo, la siguiente solicitud devuelve tanto la colección de contactos del usuario actual como el número de elementos de la colección de contactos en la propiedad @odata.count.For example, the following request returns both the contact collection of the current user, and the number of items in the contact collection in the @odata.count property.

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Probar en el Explorador de GraphTry in Graph Explorer

El $count parámetro de consulta es compatible con estas colecciones de recursos y con sus relaciones derivadas de directoryObject:The $count query parameter is supported for these collections of resources and their relationships that derive from directoryObject:

parámetro de expansiónexpand parameter

Muchos de los recursos de Microsoft Graph exponen ambas propiedades declaradas de los recursos, así como sus relaciones con otros recursos.Many Microsoft Graph resources expose both declared properties of the resource as well as its relationships with other resources. Estas relaciones también se denominan propiedades de referencia o propiedades de navegación, y pueden hacer referencia a un único recurso o a una colección de recursos.These relationships are also called reference properties or navigation properties, and they can reference either a single resource or a collection of resources. Por ejemplo, las carpetas de correo, el administrador y los informes directos de un usuario se exponen como relaciones.For example, the mail folders, manager, and direct reports of a user are all exposed as relationships.

Normalmente, se pueden consultar las propiedades de un recurso o una de sus relaciones en una sola solicitud, pero no ambas. Puede usar el parámetro de cadena de consulta $expand para incluir en los resultados de la consulta el recurso expandido o la colección a la que se hace referencia con una única relación (propiedad de navegación).Normally, you can query either the properties of a resource or one of its relationships in a single request, but not both. You can use the $expand query string parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results.

En el ejemplo siguiente se obtiene la información de la unidad raíz junto con los elementos secundarios de nivel superior de una unidad:The following example gets root drive information along with the top-level child items in a drive:

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Probar en el Probador de GraphTry in Graph Explorer

Con algunas colecciones de recursos, también se pueden especificar las propiedades que se van a devolver en los recursos expandidos si se agrega un parámetro $select. En el ejemplo siguiente se realiza la misma consulta que en el anterior, pero se usa una instrucción $select para limitar las propiedades devueltas para los elementos secundarios expandidos a las propiedades id y name.With some resource collections, you can also specify the properties to be returned in the expanded resources by adding a $select parameter. The following example performs the same query as the previous example but uses a $select statement to limit the properties returned for the expanded child items to the id and name properties.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Probar en el Probador de GraphTry in Graph Explorer

Nota: No todas las relaciones y recursos admiten el parámetro de consulta $expand. Por ejemplo, se pueden expandir las relaciones directReports, manager y memberOf de un usuario, pero no se pueden expandir sus relaciones events, messages o photo. No todos los recursos o relaciones admiten el uso de $select en elementos expandidos.Note: Not all relationships and resources support the $expand query parameter. For example, you can expand the directReports, manager, and memberOf relationships on a user, but you cannot expand its events, messages, or photo relationships. Not all resources or relationships support using $select on expanded items.

Con recursos de Azure AD que se derivan de directoryObject, como user y group, solo se admite $expand para beta y normalmente devuelve un máximo de 20 elementos para la relación expandida.With Azure AD resources that derive from directoryObject, like user and group, $expand is only supported for beta and typically returns a maximum of 20 items for the expanded relationship.

parámetro de filtradofilter parameter

Use el parámetro de consulta $filter para recuperar solo un subconjunto de una colección.Use the $filter query parameter to retrieve just a subset of a collection. El $filter parámetro de consulta también se puede usar para recuperar relaciones como members, memberOf, transitiveMembers y transitiveMemberOf.The $filter query parameter can also be used to retrieve relationships like members, memberOf, transitiveMembers, and transitiveMemberOf. Por ejemplo, puede usar el parámetro para buscar todos los grupos de seguridad a los que usted pertenece.For example, get all the security groups I'm a member of.

Por ejemplo, para buscar usuarios cuyos nombres para mostrar comiencen por la letra "J", utilice el ejemplo siguiente: startswith.The following example can be used to find users whose display name starts with the letter 'J', use startswith.

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'J')

Probar en el Probador de GraphTry in Graph Explorer

La compatibilidad con los operadores $filter varía en función de la API de Microsoft Graph.Support for $filter operators varies across Microsoft Graph APIs. Generalmente, se admiten los siguientes operadores lógicos:The following logical operators are generally supported:

  • igual a (eq)equals (eq)
  • en (in)in (in)
  • no es igual a (ne)not equals (ne)
  • mayor que (gt)greater than (gt)
  • mayor o igual que (ge)greater than or equals (ge)
  • menor que (lt), menor o igual que (le)less than (lt), less than or equals (le)
  • y (and)and (and)
  • o (or)or (or)
  • no (not)not (not)

El operador de cadena startswith se suele admitir.The startswith string operator is often supported. El operador lambda any se admite con algunas API.The any lambda operator is supported for some APIs.

Nota: debe especificar propiedades de algunas formas al usar $filter y $orderby en la misma consulta para recibir mensajes.Note: You must specify properties in certain ways when using both $filter and $orderby in the same query to get messages.

Para obtener algunos ejemplos de uso, consulte la tabla siguiente:For some usage examples, see the following table. Para obtener detalles adicionales sobre la sintaxis de $filter, vea el protocolo OData.For more details about $filter syntax, see the OData protocol.

En la tabla siguiente se muestran algunos ejemplos de uso del parámetro de consulta $filter.The following table shows some examples that use the $filter query parameter.

Nota: Haga clic en los ejemplos para probarlos en Probador de Graph.Note: Click the examples to try them in Graph Explorer.

DescripciónDescription EjemploExample
Buscar usuarios con el nombre Mary en varias propiedades.Search for users with the name Mary across multiple properties. https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Obtener todos los eventos del usuario que inició sesión que comiencen después del 1/7/2017.Get all the signed-in user's events that start after 7/1/2017. https://graph.microsoft.com/v1.0/me/events?$filter=start/dateTime ge '2017-07-01T08:00'
Obtener todos los correos electrónicos de una dirección específica recibidos por el usuario que inició sesión.Get all emails from a specific address received by the signed-in user. https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Obtener todos los correos electrónicos recibidos en abril de 2017 por el usuario que inició sesión.Get all emails received by the signed-in user in April 2017. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Obtener todos los correos electrónicos no leídos en la Bandeja de entrada del usuario que inició sesión.Get all unread mail in the signed-in user's Inbox. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=isRead eq false
Enumerar todos los grupos de Office 365 de una organización.List all Microsoft 365 groups in an organization. https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')
Emplee la transmisión de OData para obtener la pertenencia transitiva en grupos con un nombre para mostrar que comience por "a", incluido un recuento de objetos devueltos.Use OData cast to get transitive membership in groups with a display name that starts with 'a' including a count of returned objects. https://graph.microsoft.com/beta/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')

Nota: consulte la documentación de los objetos de directorio específicos (recursos de Azure AD) para obtener más información sobre $filter la compatibilidad con los operadores.Note: Please read the documentation for the specific directory objects (Azure AD resources) to learn more about $filter operator support. El contains operador de cadena actualmente no se admite en ninguno de los recursos de Microsoft Graph.The contains string operator is currently not supported on any Microsoft Graph resources.

parámetro de formatoformat parameter

Use el parámetro de consulta $format para especificar el formato de medio de los elementos devueltos desde Microsoft GraphUse the $format query parameter to specify the media format of the items returned from Microsoft Graph.

Por ejemplo, la solicitud siguiente devuelve los usuarios de la organización en formato JSON:For example, the following request returns the users in the organization in the json format:

GET https://graph.microsoft.com/v1.0/users?$format=json

Probar en el Probador de GraphTry in Graph Explorer

Nota: El parámetro de consulta $format admite varios formatos, como atom, xml y json, pero puede que no todos los formatos devuelvan resultados.Note: The $format query parameter supports a number of formats (for example, atom, xml, and json) but results may not be returned in all formats.

parámetro orderbyorderby parameter

Use el parámetro de consulta $orderby para especificar el criterio de ordenación de los elementos devueltos desde Microsoft GraphUse the $orderby query parameter to specify the sort order of the items returned from Microsoft Graph.

Por ejemplo, la solicitud siguiente devuelve los usuarios de la organización ordenados por su nombre para mostrar:For example, the following request returns the users in the organization ordered by their display name:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Probar en el Probador de GraphTry in Graph Explorer

También puede ordenar por entidades de tipo complejo. La solicitud siguiente obtiene los mensajes y los ordena por el campo address de la propiedad from, que es del tipo complejo emailAddress:You can also sort by complex type entities. The following request gets messages and sorts them by the address field of the from property, which is of the complex type emailAddress:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Probar en el Probador de GraphTry in Graph Explorer

Para ordenar los resultados en orden ascendente o descendente, anexe asc o desc al nombre del campo, separado por un espacio. Por ejemplo, ?$orderby=name%20desc.To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space; for example, ?$orderby=name%20desc.

Con algunas API se pueden ordenar los resultados por varias propiedades.With some APIs, you can order results on multiple properties. Por ejemplo, en la siguiente solicitud se ordenan los mensajes en la Bandeja de entrada del usuario; primero por el nombre de la persona que lo envió en orden descendente (de la Z a la A) y, después, por asunto en orden ascendente (el valor predeterminado).For example, the following request orders the messages in the user's Inbox, first by the name of the person who sent it in descending order (Z to A), and then by subject in ascending order (default).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Probar en el Probador de GraphTry in Graph Explorer

Nota: si especifica $filter, el servidor deducirá un criterio de ordenación para los resultados.Note: When you specify $filter the server will infer a sort order for the results. Si usa $orderby y $filter para obtener mensajes, como el servidor siempre deduce un criterio de ordenación para los resultados de un $filter, debe especificar las propiedades de algunas formas.If you use both $orderby and $filter to get messages, because the server always infers a sort order for the results of a $filter, you must specify properties in certain ways.

En el siguiente ejemplo, se muestra una consulta filtrada por las propiedades subject y importance, y después ordenada por las propiedades subject, importance y receivedDateTime en orden descendente.The following example shows a query filtered by the subject and importance properties, and then sorted by the subject, importance, and receivedDateTime properties in descending order.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Probar en el Explorador de GraphTry in Graph Explorer

Nota: combinar los parámetros de consulta $orderby y $filter es compatible en el extremo beta para los siguientes recursos AD y las relaciones que derivan de directoryObject:Note: Combining $orderby and $filter query parameters is supported on the beta endpoint for the following AD resources and their relationships that derive from directoryObject:

Para usar $orderby y $filter conjuntamente, tiene que:To use $orderby and $filter together, you need to:

  • Agregar $count=true a los parámetros de consulta.Add $count=true to the query parameters
  • Agregar ConsistencyLevel: eventual al encabezado de solicitud.Add ConsistencyLevel: eventual request header

Para obtener más información, vea Parámetros de consulta de usuario opcionales.See optional user query parameters for more information.

parámetro de búsquedasearch parameter

Use el parámetro de consulta $search para restringir los resultados de una solicitud para que coincidan con un criterio de búsquedaUse the $search query parameter to restrict the results of a request to match a search criterion.

Uso de $search en colecciones de mensajesUsing $search on message collections

Puede buscar mensajes con un valor en las propiedades de los mensajes específicos.You can search messages based on a value in specific message properties. Los resultados de la búsqueda se ordenan por la fecha y la hora en que se ha enviado el mensaje.The results of the search are sorted by the date and time that the message was sent. Una solicitud $search devuelve hasta 250 resultados.A $search request returns up to 250 results.

Si realiza una búsqueda en mensajes y especifica solo un valor sin las propiedades de mensaje específicas, la búsqueda se lleva a cabo con las propiedades de búsqueda predeterminadas de from, subject y body.If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.

En el ejemplo siguiente, se devuelven todos los mensajes del buzón del usuario que ha iniciado sesión que contienen la palabra "pizza" en cualquiera de las tres propiedades de búsqueda predeterminadas:The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Probar en el Probador de GraphTry in Graph Explorer

Como alternativa, puede buscar mensajes especificando los nombres de propiedades de mensaje en la tabla siguiente, que se reconocen por la sintaxis de la consulta de palabras clave (KQL).Alternatively, you can search messages by specifying message property names in the following table, that are recognized by the Keyword Query Language (KQL) syntax. Estos nombres de propiedad corresponden a las propiedades que se definen en la entidad de mensaje de Microsoft Graph.These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook y otras aplicaciones de Microsoft 365, como SharePoint, admiten la sintaxis KQL, proporciona la comodidad de un dominio de detección común para los almacenes de datos.Outlook and other Microsoft 365 applications such as SharePoint support KQL syntax, providing the convenience of a common discovery domain for their data stores.

Propiedades del correo electrónico que permiten búsquedasSearchable email property DescripciónDescription EjemploExample
attachmentattachment Los nombres de los archivos adjuntos a un mensaje de correo electrónico.The names of files attached to an email message. me/messages?$search="attachment:api-catalog.md"
bccbcc El campo bcc de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar.The bcc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
bodybody El cuerpo de un mensaje de correo electrónico.The body of an email message. me/messages?$search="body:excitement"
cccc El campo cc de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar.The cc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="cc:danas"&$select=subject,ccRecipients
fromfrom El remitente de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar.The sender of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="from:randiw"&$select=subject,from
hasAttachmenthasAttachment Verdadero si un mensaje contiene datos adjuntos que no son un archivo adjunto en línea, falso en caso contrario.True if an email message contains an attachment that is not an inline attachment, false otherwise. me/messages?$search="hasAttachments:true"
importanceimportance La importancia de un mensaje de correo electrónico, que un remitente puede especificar al enviar un mensaje.The importance of an email message, which a sender can specify when sending a message. Los valores posibles sonlow, medium o high.The possible values are low, medium, or high. me/messages?$search="importance:high"&$select=subject,importance
kindkind El tipo de mensaje.The type of message. Los valores posibles son contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks o voicemail.The possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail. me/messages?$search="kind:voicemail"
participantsparticipants Los campos from, to, cc y bcc de un mensaje de correo electrónico, especificados como una dirección SMTP, alias o nombre para mostrar.The from, to, cc, and bcc fields of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="participants:danas"
receivedreceived La fecha en la que un destinatario recibió un mensaje de correo electrónico.The date that an email message was received by a recipient. me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsrecipients Los camposto, cc y bcc especificados como una dirección SMTP, alias o nombre para mostrar.The to, cc, and bcc fields of an email meesage, specified as an SMTP address, display name, or alias. me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sentsent La fecha en la que un remitente envió un mensaje de correo electrónico.The date that an email message was sent by the sender. me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizesize El tamaño de un elemento, en bytes.The size of an item in bytes. me/messages?$search="size:1..500000"
subjectsubject El texto en la línea de asunto de un mensaje de correo electrónico.The text in the subject line of an email message. .. me/messages?$search="subject:has"&$select=subject
toto El campo to de un mensaje de correo electrónico, especificado como una dirección SMTP, alias o nombre para mostrar.The to field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="to:randiw"&$select=subject,toRecipients

Para obtener más información sobre las propiedades de correo electrónico que permiten búsquedas, la sintaxis KQL, los operadores compatibles y las sugerencias de búsqueda, vea los artículos siguientes:For more information about searchable email properties, KQL syntax, supported operators, and tips on searching, see the following articles:

Uso de $search en colecciones de usuariosUsing $search on person collections

Puede usar la API de contactos de Microsoft Graph para recuperar los contactos más relevantes para un usuario.You can use the Microsoft Graph People API to retrieve the people who are most relevant to a user. La relevancia viene determinada por las relaciones empresariales y los patrones de comunicación y colaboración del usuario.Relevance is determined by the user’s communication and collaboration patterns and business relationships. La API de contactos admite el parámetro de consulta $search.The People API supports the $search query parameter. Una solicitud $search devuelve hasta 250 resultados.A $search request returns up to 250 results.

Las búsquedas de contactos se realizan en las propiedades displayName y emailAddress del recurso person.Searches on people occur on both the displayName and emailAddress properties of the person resource.

La solicitud siguiente busca una persona llamada "Irene McGowen" en las propiedades displayName y emailAddress de todos los miembros de la colección people del usuario que ha iniciado sesión.The following request does a search for a person named "Irene McGowen" in the displayName and emailAddress properties in each person in the people collection of the signed-in user. Dado que existe una persona llamada "Irene McGowan" relevante para el usuario que ha iniciado sesión, se devuelve la información de "Irene McGowan".Because a person named "Irene McGowan" is relevant to the signed-in user, the information for "Irene McGowan" is returned.

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"

En el ejemplo siguiente se muestra la respuesta.The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.onmicrosoft.com",
           "imAddress": "sip:irenem@contoso.onmicrosoft.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.onmicrosoft.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Para más información sobre la API de contactos, vea Obtener información sobre contactos relevantes.To learn more about the People API, see Get information about relevant people.

Usar $search en colecciones de objetos de directorioUsing $search on directory object collections

Puede usar un parámetro de consulta $search para filtrar resultados por medio de tokens.You can use a $search query parameter to filter results using tokenization. La búsqueda con tokens se aplica extrayendo palabras de la cadena de entrada y salida, con espacios, números, mayúsculas o minúsculas, y símbolos diferentes para separar las palabras, como se muestra a continuación:Tokenized search works by extracting words from your input and output string, using spaces, numbers, different casing, and symbols to separate the words, as follow:

  • Espacioshello world => helloworldSpaceshello world => helloworld
  • Cambios de mayúscula y minúscula⁽¹⁾: HelloWorld o helloWORLD => hello worldDifferent casing⁽¹⁾: HelloWorld or helloWORLD => helloworld
  • Símbolos⁽²⁾: hello.world => hello., world, helloworldSymbols⁽²⁾: hello.world => hello., world, helloworld
  • Númeroshello123world => hello123, worldNumbershello123world => hello123, world

⁽¹⁾ Actualmente, la tokenización solo funciona cuando los caracteres cambian de minúsculas a mayúsculas, por lo que HELLOworld se considera un único token: helloworld, y HelloWORld son dos tokens: hello, world.⁽¹⁾ Currently, tokenization only works when the casing is changing from lowercase to uppercase, so HELLOworld is considered a single token: helloworld, and HelloWORld is two tokens: hello, world. ⁽²⁾ La lógica de tokenización también combina palabras que se separan mediante símbolos; por ejemplo, la búsqueda de helloworld encontrará hello-world y hello.world.⁽²⁾ Tokenization logic also combines words that are separated only by symbols; for example, searching for helloworld will find hello-world and hello.world.

Nota: después de la tokenización, los tokens se hacen coincidir independientemente de la grafía original y se hacen coincidir en cualquier orden.Note: after tokenization, the tokens are matched independently of the original casing, and they are matched in any order. El parámetro de consulta $search en colecciones de objetos de directorio requiere un encabezado de solicitud especial: ConsistencyLevel: eventual.$search query parameter on directory objects collections requires a special request header: ConsistencyLevel: eventual.

La compatibilidad con la búsqueda por tokens solo funciona en los campos displayName y description.The tokenized search support works only on the displayName and description fields. Se puede colocar cualquier campo en $search, los campos que no sean displayName y description tienen de forma predeterminada el comportamiento de startswith de $filter.Any field can be put in $search; fields other than displayName and description default to $filter startswith behavior. Por ejemplo:For example:

https://graph.microsoft.com/beta/groups/?$search="displayName:OneVideo"

Busca todos los grupos con nombres para mostrar que sean similares a "OneVideo".This looks for all groups with display names that look like "OneVideo". $search también puede usarse conjuntamente con $filter.$search can be used together with $filter as well. Por ejemplo:For example:

https://graph.microsoft.com/beta/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"

Busca todos los grupos con correo habilitado con nombres para mostrar que sean similares a "OneVideo".This looks for all mail-enabled groups with display names that look like "OneVideo". Los resultados se restringen en función de una conjunción lógica ("Y") de $filter y la consulta completa en $search.The results are restricted based on a logical conjunction (an "AND") of the $filter and the entire query in the $search. El texto de búsqueda se ajusta por token en función de las mayúsculas y minúsculas, pero las coincidencias se ejecutan sin distinguir entre mayúsculas y minúsculas.The search text is tokenized based on casing, but matches are performed in a case-insensitive manner. Por ejemplo, "OneVideo" se divide en dos tokens de entrada ("uno" y "vídeo"), pero coincide con propiedades que no distinguen entre mayúsculas y minúsculas.For example, "OneVideo" would be split into two input tokens "one" and "video", but matches properties insensitive to case.

La sintaxis de la búsqueda sigue estas reglas:The syntax of search follows these rules:

  • Formato genérico: $search="clause1" [Y | O] "[clauseX]".Generic format: $search="clause1" [AND | OR] "[clauseX]".
  • Se admite cualquier número de cláusulas.Any number of clauses is supported. También se admite paréntesis para la prioridad.Parentheses for precedence is also supported.
  • La sintaxis para cada cláusula es "<property>:<text to search>".The syntax for each clause is: "<property>:<text to search>".
  • El nombre de la propiedad debe especificarse en la cláusula.The property name must be specified in clause. Las propiedades que se pueden usar en $filter también se pueden usar dentro de $search.Any property that can be used in $filter can also be used inside $search. Dependiendo de la propiedad, el comportamiento de búsqueda es "Buscar" o "StartsWith", si la búsqueda no es compatible con la propiedad.Depending on the property, the search behavior is either "search" or "startswith" if search is not supported on the property.
  • La parte completa de la cláusula debe incluirse entre comillas dobles.The whole clause part must be put inside double quotes.
  • El operador lógico "Y" o "O" debe escribirse fuera de las comillas dobles.Logical operator 'AND' 'OR' must be put outside double quotes. Deben escribirse en mayúsculas.They must be in upper case.
  • Dado que la parte completa de la cláusula tiene que incluirse entre comillas dobles, si contiene comillas dobles y barras diagonales inversas, se debe anteponer una barra diagonal inversa.Given that the whole clause part needs to be put inside double quotes, if it contains double quote and backslash, it needs to be escaped with a backslash. No es necesario utilizar un carácter de escape con otros caracteres.No other characters need to be escaped.

En la tabla siguiente se muestran algunos ejemplos.The following table shows some examples.

Clase de objetoObject class DescriptionDescription EjemploExample
UsuarioUser Nombre del usuario para mostrar de la libreta de direcciones.Address book display name of the user. https://graph.microsoft.com/beta/users?$search="displayName:Guthr"
UsuarioUser Nombre o correo del usuario para mostrar de la libreta de direcciones.Address book display name or mail of the user. https://graph.microsoft.com/beta/users?$search="displayName:Guthr" OR "mail:Guthr"
GrupoGroup Nombre o descripción del grupo para mostrar de la libreta de direcciones.Address book display name or description of the group. https://graph.microsoft.com/beta/groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")
GrupoGroup Nombre de la libreta de direcciones para mostrar en un grupo con correo habilitado.Address book display name on a mail-enabled group. https://graph.microsoft.com/beta/groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"

Tanto las entradas de cadena que se proporcionan en $search, como las propiedades que se pueden buscar, se dividen en partes por espacios, uso diferente de mayúsculas y minúsculas y tipos de caracteres (números y caracteres especiales).Both the string inputs you provide in $search, as well as the searchable properties, are split up into parts by spaces, different casing, and character types (numbers and special characters).

parámetro de selecciónselect parameter

Use el parámetro de consulta $select para devolver un conjunto de propiedades diferente al predeterminado para un recurso individual o una colección de recursos.Use the $select query parameter to return a set of properties that are different than the default set for an individual resource or a collection of resources. Con $select, puede especificar un subconjunto o un superconjunto de las propiedades predeterminadas.With $select, you can specify a subset or a superset of the default properties.

Por ejemplo, al recuperar los mensajes del usuario que ha iniciado sesión, puede especificar que solo se devuelvan las propiedades from y subject:For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Probar en el Probador de GraphTry in Graph Explorer

Importante: En general, se recomienda usar $select para limitar las propiedades devueltas por una consulta a las necesarias para la aplicación.Important: In general, we recommend that you use $select to limit the properties returned by a query to those needed by your app. Esto es especialmente cierto para las consultas que potencialmente pueden devolver un conjunto de resultados grande.This is especially true of queries that might potentially return a large result set. Limitar las propiedades devueltas en cada fila reducirá la carga en la red y ayudará a mejorar el rendimiento de la aplicación.Limiting the properties returned in each row will reduce network load and help improve your app's performance.

En v1.0, algunos recursos de Azure AD que se derivan de directoryObject, como user y group, devuelven un subconjunto predeterminado limitado de propiedades en las operaciones de lectura. Para estos recursos, debe usar $select para devolver propiedades fuera el conjunto predeterminado.In v1.0, some Azure AD resources that derive from directoryObject, like user and group, return a limited, default subset of properties on reads. For these resources, you must use $select to return properties outside of the default set.

parámetros de omisiónskip parameter

Use el parámetro de consulta $skip para establecer el número de elementos que se omitirán al inicio de una colección. Por ejemplo, la solicitud siguiente devuelve eventos para el usuario ordenados por fecha de creación, empezando por el evento 21 de la colección:Use the $skip query parameter to set the number of items to skip at the start of a collection. For example, the following request returns events for the user sorted by date created, starting with the 21st event in the collection:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Probar en el Probador de GraphTry in Graph Explorer

Nota: En algunas API de Microsoft Graph, como Correo y Calendario de Outlook (message, event y calendar), se usa $skip para implementar la paginación.Note: Some Microsoft Graph APIs, like Outlook Mail and Calendars (message, event, and calendar), use $skip to implement paging. Cuando los resultados de una consulta ocupen varias páginas, estas API devolverán una propiedad @odata:nextLink con una dirección URL que contendrá un parámetro $skip.When results of a query span multiple pages, these APIs will return an @odata:nextLink property with a URL that contains a $skip parameter. Puede usar esta dirección URL para devolver la siguiente página de resultados.You can use this URL to return the next page of results. Para obtener más información, vea Paginación.To learn more, see Paging.

parámetro skipTokenskipToken parameter

Algunas consultas devuelven varias páginas de datos debido a la paginación del servidor o al uso del parámetro $top para limitar el tamaño de página de la respuesta.Some requests return multiple pages of data, either due to server-side paging or due to the use of the $top parameter to limit the page size of the response. Muchas API de Microsoft Graph usan el parámetro de consulta skipToken para hacer referencia a las páginas siguientes del resultado.Many Microsoft Graph APIs use the skipToken query parameter to reference subsequent pages of the result.
El parámetro $skiptoken contiene un token opaco que hace referencia a la siguiente página de resultados y se devuelve en la dirección URL proporcionada en la propiedad @odata.nextLink en la respuesta.The $skiptoken parameter contains an opaque token that references the next page of results and is returned in the URL provided in the @odata.nextLink property in the response. Para más información, vea Paginación.To learn more, see Paging.

Nota: si usa el recuento OData (agregando $count=true en la cadena de referencia), la propiedad @odata.count estará presente solo en la primera página.Note: if you're using OData Count (adding $count=true in the querystring), the @odata.count property will be present only in the first page.

parámetro superiortop parameter

Use el parámetro de consulta $top para especificar el tamaño de página del conjunto de resultados.Use the $top query parameter to specify the page size of the result set.

Si quedan más elementos en el conjunto de resultados, el cuerpo de la respuesta contendrá un parámetro @odata.nextLink.If more items remain in the result set, the response body will contain an @odata.nextLink parameter. Este parámetro contiene una dirección URL que se puede usar para obtener la siguiente página de resultados.This parameter contains a URL that you can use to get the next page of results. Para obtener más información, vea Paginación.To learn more, see Paging.

$top acepta un valor mínimo de 1 y un valor máximo de 999 (inclusive).$top accepts a minimum value of 1 and a maximum value of 999 (inclusive).

Por ejemplo, la solicitud siguiente devuelve los cinco primeros mensajes en el buzón del usuario:For example, the following request returns the first five messages in the user's mailbox:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

Probar en el Probador de GraphTry in Graph Explorer

Control de errores para parámetros de consultaError handling for query parameters

Algunas solicitudes devolverán un mensaje de error si no se admite un parámetro de consulta especificado. Por ejemplo, no se puede usar $expand en la relación user/photo.Some requests will return an error message if a specified query parameter is not supported. For example, you cannot use $expand on the user/photo relationship.

https://graph.microsoft.com/beta/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

Pero es importante tener en cuenta que los parámetros de consulta especificados en una solicitud pueden devolver un error silenciosamente.However, it is important to note that query parameters specified in a request might fail silently. Esto puede suceder con parámetros de consulta no admitidos, así como con combinaciones no compatibles de parámetros de consulta.This can be true for unsupported query parameters as well as for unsupported combinations of query parameters. En estos casos, debe examinar los datos devueltos por la solicitud para determinar si los parámetros de consulta especificados tuvieron el efecto previsto.In these cases, you should examine the data returned by the request to determine whether the query parameters you specified had the desired effect.

Vea tambiénSee also