Além de outros parâmetros de consulta OData, o Microsoft Graph dá suporte ao parâmetro de consulta $search para restringir os resultados de uma solicitação para corresponder a um critério de pesquisa.
O suporte para o $search parâmetro de consulta varia consoante a entidade, com alguns, como os recursos do Microsoft Entra que derivam de directoryObject, suportando $search apenas em consultas avançadas. Este artigo descreve a sintaxe e o comportamento da pesquisa nas três áreas principais seguintes:
Pode procurar mensagens com base num valor em propriedades de mensagens específicas. Os resultados da pesquisa são classificados pela data e hora em que a mensagem foi enviada. Um $search pedido devolve até 1000 resultados.
Se você realizar uma pesquisa em mensagens e especificar apenas um valor sem as propriedades de mensagens específicas, a pesquisa será realizada nas propriedades de pesquisa padrão from, subject e body.
O exemplo a seguir retorna todas as mensagens na Caixa de Entrada do usuário que contenham "pizza" em qualquer uma das três propriedades de pesquisa padrão:
GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"
// 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.Search = "\"pizza\"";
});
// 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
)
requestSearch := "\"pizza\""
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
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.search = "\"pizza\"";
});
Como alternativa, você pode pesquisar mensagens especificando os nomes de propriedade da mensagem na tabela a seguir, que são reconhecidos pela sintaxe da Linguagem de Consulta de Palavra-chave (KQL). Esses nomes de propriedades correspondem às propriedades definidas na entidade mensagem do Microsoft Graph. O Outlook e outros aplicativos do Microsoft 365 como o SharePoint são compatíveis com a sintaxe KQL, proporcionando a conveniência de um domínio de descoberta comum para seus repositórios de dados.
Propriedades de emails pesquisáveis
Descrição
Exemplo
attachment
Os nomes dos arquivos anexados a uma mensagem de email.
Para saber mais sobre as propriedades de email pesquisáveis, KQL como a sintaxe, operadores com suporte e dicas de pesquisa, confira os seguintes artigos:
Pode aplicar-se $search às propriedades displayName e emailAddresses do recurso da pessoa . O pedido devolve até 250 resultados por predefinição.
O pedido seguinte procura "Irene McGowan" nos objetos da pessoa da coleção do utilizador com sessão iniciada. O Microsoft Graph define o âmbito da pesquisa para as propriedades displayName ou emailAddresses .
GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"
// 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.People.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"Irene McGowen\"";
});
// 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
)
requestSearch := "\"Irene McGowen\""
requestParameters := &graphusers.ItemPeopleRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
configuration := &graphusers.ItemPeopleRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PersonCollectionResponse result = graphClient.me().people().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"Irene McGowen\"";
});
Como usar $search nos conjuntos de objetos do diretório
Os recursos do Microsoft Entra ID e as respetivas relações derivadas de directoryObject suportam o $search parâmetro de consulta apenas em consultas avançadas.
Observação
O parâmetro de consulta $search não está disponível no momento nos locatários Azure AD B2C.
Existe um problema conhecido relacionado com $search objetos de diretório para valores que contêm um símbolo de e comercial (&).
A implementação de pesquisa não suporta lógica "contém". Em vez disso, ele usa uma abordagem de geração de tokens que funciona extraindo palavras do valor da propriedade e da cadeia de caracteres de pesquisa usando espaços, números, maiúsculas e minúsculas diferentes, e símbolos conforme mostrado nos exemplos a seguir:
Espaços: hello world =>hello, world
Caixa diferente⁽1⁾: HelloWorld ou helloWORLD =>hello, world
⁽1⁾ Para diferentes maiúsculas/minúsculas, a tokenização só funciona atualmente quando a caixa está a mudar de minúsculas para maiúsculas, pelo HELLOworld que é considerada um único token: helloworlde HelloWORld são dois tokens: hello, world.
⁽2⁾ A lógica de tokenização também combina palavras separadas apenas por símbolos; por exemplo, procurar helloworld localizações hello-world e hello.world.
Após a tokenização, os tokens são correspondidos independentemente da caixa original e são correspondidos por qualquer ordem. Por exemplo, displayName 李四(David Li) corresponde a cadeias de pesquisa como 李四(David Li), 李四, David, Li, David), , (李四, Li 李. Uma alteração no alfabeto, como do latim para o cirílico ou chinês, não cria um novo token. Por exemplo, displayName 蓝色group corresponde às 蓝色group cadeias de pesquisa e 蓝色 , mas não group; enquanto displayName group蓝色 corresponde às group蓝色 cadeias de pesquisa e group , mas não 蓝色 ou 蓝.
O suporte à pesquisa com token funciona apenas nos campos displayName e descrição. Qualquer campo do Tipo de cadeia pode ser colocado em $search; campos que não displayName e descrição predefinido para $filterstartswith comportamento.
GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual
// 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.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestSearch := "\"displayName:OneVideo\" OR \"mail:onevideo\""
requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
Search: &requestSearch,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual
// 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.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "mailEnabled eq true";
requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\"";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "mailEnabled eq true";
requestConfiguration.queryParameters.search = "\"displayName:OneVideo\"";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
procurar todos os grupos habilitados para email com nomes de exibição que se pareçam com "OneVideo".
Os resultados são restritos com base numa conjunção lógica ("E") da $filter consulta completa e na $search.
O número de cláusulas (clause) não é limitado. O uso de parênteses para a precedência também é suportado.
A sintaxe de cada cláusula é: "<property>:<text to search>".
O nome da propriedade deve ser especificado na cláusula.
A cláusula inteira deve ser declarada entre aspas duplas. Se ele contiver aspas duplas ou barra invertida, ele deverá ser escapado com uma barra invertida. Todos os outros caracteres especiais devem ser codificados em URL.
Operadores lógicos AND e OR devem ser colocados fora das aspas duplas e devem estar em maiúsculas.
A pesquisa verdadeira só é suportada pelas propriedades displayName e description ; mas qualquer propriedade que possa ser utilizada no $filter também pode ser utilizada dentro $searchde . Consoante a propriedade, o comportamento da pesquisa é "procurar" ou $filter com "startsWith" se a pesquisa não for suportada na propriedade .
As entradas de cadeia que fornece em $searche as propriedades pesquisáveis são divididas em partes por espaços, maiúsculas e minúsculas diferentes (números e carateres especiais).
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.