Usar parámetros de consulta para personalizar respuestas
Artículo
Microsoft Graph admite parámetros de consulta opcionales que puede usar para especificar y controlar la cantidad de datos devueltos en una respuesta. 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.
Sugerencia
En el punto de conexión beta, el prefijo $ es opcional. Por ejemplo, en lugar de $filter, puede usar filter.
En el punto de conexión v1, el prefijo $ es opcional solo para un subconjunto de las API. Para simplificar, incluya $ siempre si usa el punto de conexión v1.
Una operación de API de Microsoft Graph podría admitir una o varias de las siguientes opciones de consulta de sistema de OData. Estas opciones de consulta son compatibles con el lenguaje de consulta OData V4 y solo se admiten en operaciones GET.
Indexa en un conjunto de resultados. También se usa en algunas API para implementar la paginación y se puede usar junto con $top para realizar manualmente los resultados de la página.
Para conocer las opciones de consulta del sistema OData que admite una API y sus propiedades, consulte la tabla Propiedades en la página de recursos y la sección Parámetros de consulta opcionales de las operaciones LIST y GET de la API.
Combine varias solicitudes HTTP en una solicitud por lotes.
POST /$batch
Codificación de parámetros de consulta
Los valores de los parámetros de consulta deben estar codificados por porcentaje según RFC 3986. Por ejemplo, todos los caracteres reservados de las cadenas de consulta deben estar codificados en porcentaje. Muchos clientes HTTP, exploradores y herramientas (como el Probador de Graph) le servirán de ayuda. Si una consulta produce un error, puede deberse a que los valores de los parámetros de consulta no se han codificado correctamente. En algunos casos, es posible que tenga que codificar dos veces los valores.
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
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. En el ejemplo, el valor de cadena let''s meet for lunch? tiene el escape de comillas simples.
GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFilter := "subject eq 'let''s meet for lunch?'"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "subject eq 'let''s meet for lunch?'"
Use el parámetro de consulta $count para recuperar el recuento del número total de elementos de una colección o para buscar coincidencias con una expresión.
$count puede realizarse de las siguientes maneras:
Como parámetro de cadena de consulta con la sintaxis $count=true para incluir un recuento del número total de elementos de una colección junto con la página de valores de datos devueltos por Microsoft Graph. Por ejemplo, users?$count=true.
Como segmento de dirección URL para recuperar el total entero de la colección. Por ejemplo, users/$count.
No se admite el uso de $count en inquilinos de Azure AD B2C.
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.
GET https://graph.microsoft.com/v1.0/me/contacts?$count=true
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestCount := true
requestParameters := &graphusers.ItemContactsRequestBuilderGetQueryParameters{
Count: &requestCount,
}
configuration := &graphusers.ItemContactsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
contacts, err := graphClient.Me().Contacts().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
});
El parámetro de consulta $count se admite para colecciones de los siguientes recursos usados con frecuencia y sus relaciones que derivan de directoryObject y solo en consultas avanzadas:
Muchos de los recursos de Microsoft Graph exponen ambas propiedades declaradas de los recursos, así como sus relaciones con otros recursos. 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. Por ejemplo, las carpetas de correo, el administrador y los informes directos de un usuario se exponen como relaciones.
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). Para algunas API, solo se puede expandir una relación en una sola solicitud.
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:
GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
Expand: [] string {"children"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children"};
});
Con algunas colecciones de recursos, también puede especificar las propiedades que se devolverán en los recursos expandidos agregando un $select parámetro. En el ejemplo siguiente se realiza la misma consulta que en el ejemplo anterior, pero se usa una $select instrucción para limitar las propiedades devueltas para los elementos secundarios expandidos a las propiedades id y name .
GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children($select=id,name)" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
Expand: [] string {"children($select=id,name)"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});
No todas las relaciones y recursos admiten el parámetro de consulta $expand. Por ejemplo, puede expandir las relaciones de directReports, managery memberOf en un usuario, pero no puede expandir sus relaciones deeventos, mensajeso fotos. No todos los recursos o relaciones admiten el uso de $select en elementos expandidos.
GET https://graph.microsoft.com/v1.0/users?$format=json
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Format = "json";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFormat := "json"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Format: &requestFormat,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.format = "json";
});
El parámetro de consulta $format admite varios formatos (como atom, xml y json), aunque puede que no todos los formatos devuelvan resultados.
parámetro orderby
Use el parámetro de consulta $orderby para especificar el criterio de ordenación de los elementos devueltos desde Microsoft Graph El orden predeterminado es ascendente.
Por ejemplo, la solicitud siguiente devuelve los usuarios de la organización ordenados por su nombre para mostrar:
GET https://graph.microsoft.com/v1.0/users?$orderby=displayName
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Orderby: [] string {"displayName"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
});
También puede ordenar por entidades de tipo complejo. La siguiente solicitud obtiene mensajes y los ordena por el campo de dirección de la propiedad from , que es del tipo complejo emailAddress:
GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/address"};
});
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. Si no se especifica el criterio de ordenación, se deduce el valor predeterminado (orden ascendente).
Con algunas API se pueden ordenar los resultados por varias propiedades. 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).
GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.ItemMailFolderItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphusers.ItemMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"
Al especificar $filter, el servidor deducirá un criterio de ordenación para los resultados. 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.
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.
GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestFilter := "Subject eq 'welcome' and importance eq 'normal'"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.queryParameters.orderby = new String []{"subject", "importance", "receivedDateTime desc"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "subject,importance,receivedDateTime desc"
Use el parámetro de consulta $search para restringir los resultados de una solicitud para que coincidan con un criterio de búsqueda Su sintaxis y comportamiento varían de una operación de API a otra. Para ver la sintaxis de $search en distintos recursos, consulte Usar el parámetro de consulta $search para que coincida con un criterio de búsqueda.
parámetro de selección
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. Con $select, puede especificar un subconjunto o un superconjunto de las propiedades predeterminadas.
Al realizar una solicitud GET sin usar $select para limitar la cantidad de datos de propiedades, Microsoft Graph incluye una propiedad @microsoft.graph.tips que proporciona una recomendación de procedimientos recomendados para usar $select de forma similar al siguiente mensaje:
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",
Por ejemplo, al recuperar los mensajes del usuario que ha iniciado sesión, puede especificar que solo se devuelvan las propiedades from y subject:
GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"from","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});
En general, se recomienda usar $select para limitar las propiedades devueltas por una consulta a aquellas necesarias para la aplicación. Esto es especialmente cierto para las consultas que potencialmente pueden devolver un conjunto de resultados grande. Limitar las propiedades devueltas en cada fila reducirá la carga en la red y ayudará a mejorar el rendimiento de la aplicación.
En v1.0, algunos recursos de Microsoft Entra que derivan de directoryObject, como usuario y grupo, devuelven un subconjunto limitado y predeterminado de propiedades en las lecturas. Para estos recursos, debe usar $select para devolver propiedades fuera del conjunto predeterminado.
parámetros de omisión
Use el $skip parámetro de consulta para establecer el número de elementos que se omitirán al principio de una colección.
Por ejemplo, la siguiente solicitud devuelve eventos para el usuario ordenado por fecha de creación, empezando por el evento 21 de la colección:
GET https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Events.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
requestConfiguration.QueryParameters.Skip = 20;
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestSkip := int32(20)
requestParameters := &graphusers.ItemEventsRequestBuilderGetQueryParameters{
Orderby: [] string {"createdDateTime"},
Skip: &requestSkip,
}
configuration := &graphusers.ItemEventsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
events, err := graphClient.Me().Events().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
requestConfiguration.queryParameters.skip = 20;
});
En algunas API de Microsoft Graph, como Correo y Calendario de Outlook (mensaje, evento y calendario), se usa $skip para implementar la paginación. 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. Puede usar esta dirección URL para devolver la siguiente página de resultados. Para obtener más información, vea Paginación.
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. Muchas API de Microsoft Graph usan el parámetro de consulta skipToken para hacer referencia a las páginas siguientes del resultado.
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. Para más información, vea Paginación.
Nota:
Si usa el recuento de OData (agregando $count=true en la cadena de consulta) para las consultas en los objetos de directorio, la propiedad @odata.count solo está presente en la primera página.
El encabezado ConsistencyLevel necesario para las consultas avanzadas en objetos de directorio no se incluye de forma predeterminada en las solicitudes de página posteriores. Debe establecerse explícitamente en páginas posteriores.
parámetro superior
Use el parámetro de $top consulta para especificar el número de elementos que se incluirán en el resultado.
Si quedan más elementos en el conjunto de resultados, el cuerpo de la respuesta contendrá un parámetro @odata.nextLink. Este parámetro contiene una dirección URL que se puede usar para obtener la siguiente página de resultados. Para obtener más información, vea Paginación.
El valor mínimo de $top es 1 y el máximo depende de la API correspondiente.
Por ejemplo, la solicitud siguiente de mensajes de lista devuelve los cinco primeros mensajes en el buzón del usuario:
GET https://graph.microsoft.com/v1.0/me/messages?$top=5
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Top = 5;
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestTop := int32(5)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Top: &requestTop,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.top = 5;
});
El encabezado ConsistencyLevel necesario para las consultas avanzadas en objetos de directorio no se incluye de forma predeterminada en las solicitudes de página posteriores. Debe establecerse explícitamente en páginas posteriores.
Control de errores para parámetros de consulta
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 user/photo relación.
https://graph.microsoft.com/v1.0/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. Esto puede suceder con parámetros de consulta no admitidos, así como con combinaciones no compatibles de parámetros de consulta. En estos casos, debe examinar los datos devueltos por la solicitud para determinar si los parámetros de consulta especificados tuvieron el efecto previsto.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.