Compartilhar via


Utilizar o parâmetro de consulta $search

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 Microsoft Entra recursos 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 main seguintes:

Usando $search em conjuntos de mensagens

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"

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. OBTER../me/messages?$search="attachment:api-catalog.md"
bcc O campo Cco de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias. OBTER../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
body O corpo de uma mensagem de email. OBTER../me/messages?$search="body:excitement"
cc O campo Cc de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias. OBTER../me/messages?$search="cc:danas"&$select=subject,ccRecipients
from O remetente de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias. OBTER../me/messages?$search="from:randiw"&$select=subject,from

OBTER../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from
hasAttachment true se uma mensagem de e-mail contiver um anexo que não seja um anexo inline, false caso contrário. OBTER../me/messages?$search="hasAttachments:true"
importance A prioridade de uma mensagem de email, que um remetente pode especificar ao enviar uma mensagem. Os valores possíveis são low, medium ou high. OBTER../me/messages?$search="importance:high"&$select=subject,importance
kind O tipo de mensagem. Os valores possíveis são contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks ou voicemail. OBTER../me/messages?$search="kind:voicemail"
participants Os campos de, para, Cc e Cco de uma mensagem de email, especificados como um endereço SMTP, nome de exibição ou alias. OBTER../me/messages?$search="participants:danas"
received A data em que uma mensagem de email foi recebida pelo destinatário. OBTER../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipients Os campos para, cc e bcc de uma mensagem de e-mail, especificados como um endereço SMTP, nome a apresentar ou alias. OBTER../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sent A data em que uma mensagem de email foi enviada pelo remetente. OBTER../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
size O tamanho de um item em bytes. OBTER../me/messages?$search="size:1..500000"
subject O texto na linha de assunto de uma mensagem de email. OBTER../me/messages?$search="subject:has"&$select=subject
to O campo para de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias. OBTER.../me/messages?$search="to:randiw"&$select=subject,toRecipients

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:

Usando $search em conjuntos de pessoas

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"

O exemplo a seguir mostra a resposta.

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

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

Saiba mais sobre a API de Pessoas em Obter informações sobre pessoas relevantes.

Como usar $search nos conjuntos de objetos do diretório

Microsoft Entra ID recursos 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 diferente1⁾: HelloWorld ou helloWORLD =>hello, world
  • Símbolos2⁾: hello.world =>hello, ., world, helloworld
  • Números: hello123world =>hello, 123, 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.

Por exemplo:

GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual

Esta ação procura todos os grupos com nomes a apresentar que tenham one e video tokens ou e-mails que comecem por onevideo.

$search também pode ser usado junto com o $filter:

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
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.

A sintaxe da pesquisa segue as seguintes regras:

  • Formato genérico: $search="clause1" [AND | OR] "\clauseX".
  • 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).

A tabela a seguir mostra alguns exemplos.

Classe de objeto Descrição Exemplo
Usuário O caderno de endereços exibe o nome do usuário. OBTER../users?$search="displayName:Guthr"
Usuário O caderno de endereços exibe o nome ou o email do usuário. OBTER../users?$search="displayName:Guthr" OR "mail:Guthr"
Grupo O caderno de endereços exibe o nome ou a descrição de um grupo. OBTER../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")
Grupo Nome de exibição do catálogo de endereços em um grupo habilitado para email. OBTER../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"