Usar parámetros de consulta para personalizar respuestas
Artículo
Microsoft Graph admite parámetros de consulta 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 de API a otra y, en función de la API, puede diferir entre los puntos de conexión v1.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.0 , el $ prefijo es opcional solo para un subconjunto de API.
Por motivos de simplicidad, incluya siempre $ en todas las versiones.
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 compatibles con una API y sus propiedades, consulte la tabla "Propiedades" de la página de recursos y la sección "Parámetros de consulta opcionales" de las operaciones LIST y GET para la API.
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 Explorador de Graph) controlan esta codificación automáticamente. Si se produce un error en una consulta, una posible causa es un error al codificar los valores de parámetro de consulta correctamente. En algunos casos, debe 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')";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
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')";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
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')";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
En el caso de las solicitudes que usan comillas simples, si los valores de parámetro también contienen comillas simples, deben tener dos caracteres de escape; De lo contrario, se produce un error en la solicitud debido a una sintaxis no 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?'"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
filter = "subject eq 'let''s meet for lunch?'",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
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 de una 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;
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.contacts.contacts_request_builder import ContactsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ContactsRequestBuilder.ContactsRequestBuilderGetQueryParameters(
count = True,
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.contacts.get(request_configuration = request_configuration)
En el caso de los objetos de directorio, es decir, los recursos que derivan de directoryObject, el parámetro de $count consulta solo se admite en consultas avanzadas.
parámetro de expansión
Muchos de los recursos de Microsoft Graph exponen ambas propiedades declaradas de los recursos y 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"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
expand = ["children"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)
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)"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
expand = ["children($select=id,name)"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)
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";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
format = "json",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
El $format parámetro de consulta admite varios formatos (por ejemplo, , atomxmly json), pero es posible que los resultados no se devuelvan en todos los formatos.
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 siguiente solicitud devuelve los usuarios de la organización ordenados por su nombre para mostrar en orden ascendente:
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"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
orderby = ["displayName"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
Algunas API admiten la ordenación 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"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
orderby = ["from/emailAddress/address"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Para ordenar los resultados en orden ascendente o descendente, anexe o ascdesc al nombre del campo, separados por un espacio; por ejemplo, ?$orderby=name desc (sin codificar), ?$orderby=name%20desc (url codificada). Si no se especifica el criterio de ordenación, se deduce el orden ascendente predeterminado.
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"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
orderby = ["from/emailAddress/name desc","subject"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.mail_folders.by_mail_folder_id('mailFolder-id').messages.get(request_configuration = request_configuration)
Cuando se especifica $filter, el servicio deduce 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"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
filter = "Subject eq 'welcome' and importance eq 'normal'",
orderby = ["subject","importance","receivedDateTime desc"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
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 $select consulta para devolver un subconjunto de propiedades para un recurso. 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"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["from","subject"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
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 la versión 1.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;
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.events.events_request_builder import EventsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = EventsRequestBuilder.EventsRequestBuilderGetQueryParameters(
orderby = ["createdDateTime"],
skip = 20,
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.events.get(request_configuration = request_configuration)
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 abarcan varias páginas, estas API devuelven una propiedad @odata.nextLink con una dirección URL que contiene un $skip parámetro. 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.
Este parámetro contiene un token opaco que hace referencia a la página siguiente de resultados y se devuelve en la dirección URL proporcionada en la propiedad @odata.nextLink de la respuesta. Para obtener 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 contiene 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;
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
top = 5,
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
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 devuelven 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"
}
}
}
Sin embargo, a veces los parámetros de consulta especificados en una solicitud producen un error silencioso. Por ejemplo, para parámetros de consulta no admitidos y para combinaciones no admitidas 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.
Obtenga información sobre cómo mostrar los correos electrónicos de un usuario en aplicaciones ASP.NET Core con Microsoft Graph. Además, obtenga información sobre cómo optimizar consultas de Microsoft Graph y cargar correo electrónico en lotes.