Usar o parâmetro de consulta $filter

O Microsoft Graph dá suporte ao $filter parâmetro de consulta OData para recuperar um subconjunto de uma coleção.

A expressão especificada com $filter é avaliada para cada recurso na coleção e somente os itens em que a expressão avalia são incluídos true na resposta. Os recursos para os quais a expressão avalia false para ou para null, ou quais propriedades de referência que não estão disponíveis devido a permissões, são omitidos da resposta.

O $filter parâmetro de consulta também pode ser aplicado em relações como membros, memberOf, transitiveMembers e transitiveMemberOf. Por exemplo, "obtenha todos os grupos de segurança dos quais sou membro".

Operadores e funções com suporte em expressões de filtro

O Microsoft Graph dá suporte ao uso de operadores e funções a seguir. No entanto, o suporte por recursos individuais e suas propriedades ou relações pode variar. Além disso, algumas propriedades e relações dão suporte $filter apenas a consultas avançadas. Consulte a documentação de recurso específica para obter detalhes e Sintaxe para usar o parâmetro de consulta OData de filtro para obter exemplos de como usar esses operadores e funções.

Tipo de operador Operador
Operadores de igualdade
  • Igual a (eq)
  • Não é igual a (ne)
  • Negação lógica (not)
  • Em (in)
  • Tem (has)


Nota: Ao usar o in operador, a solicitação é limitada a 15 expressões na cláusula de filtro por padrão ou um comprimento de URL de 2.048 caracteres ao usar recursos avançados de consulta.
Operadores relacionais
  • Menor que (lt)
  • Maior que (gt)
  • Menor ou igual a ( le )
  • Maior ou igual a (ge)
Operadores Lambda
  • Qualquer (any)
  • Todos (all)
Operadores condicionais
  • E (and)
  • Ou (or)
Functions
  • Inicia com ( startswith )
  • Termina com (endswith)
  • Contém ( contains )

Filtrar usando operadores lambda

O OData define os any operadores e all para avaliar correspondências em propriedades de vários valores, ou seja, uma coleção de valores primitivos, como tipos de cadeia de caracteres ou coleção de recursos.

Operador any

O any operador aplica iterativamente uma expressão booliana a cada item de uma coleção e retorna true se a expressão for true para pelo menos um item da coleção, caso contrário, retornará false. A seguinte cadeia de consulta mostra a sintaxe do any operador:

$filter=collection/any(property:property/subProperty eq 'value-to-match')

Em que

  • a coleção é a propriedade que contém uma coleção de valores ou uma coleção de propriedades complexas.
  • property:property é a variável de intervalo que contém o elemento atual da coleção durante a iteração. Essa variável pode ser nomeada quase tudo, por exemplo, p:p.
  • SubProperty é necessário quando a consulta se aplica a uma coleção de entidades. Ele representa a propriedade do tipo complexo cujo valor você está correspondendo.
  • value-to-match representa o membro da coleção na qual você está correspondendo.

A sintaxe equivalente em C# e LINQ é a seguinte:

collection.Any(property => property.subProperty == "value-to-match")

Por exemplo, a propriedade imAddresses do user recurso contém uma coleção de tipos primitivos string. A consulta a seguir recupera apenas usuários com pelo menos um imAddress de admin@contoso.com.

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(i:i eq 'admin@contoso.com')

A propriedade assignedLicenses do user recurso contém uma coleção de objetos assignedLicense , um tipo complexo com duas propriedades, skuId e planos desabilitados. A consulta a seguir recupera apenas usuários com pelo menos uma licença atribuída identificada pelo skuId184efa21-98c3-4e5d-95ab-d07053a96e67.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

Para negar o resultado da expressão dentro da cláusula any, use o operador not, não o operador ne. Por exemplo, a consulta a seguir recupera apenas usuários que não receberam o imAddress de admin@contoso.com.

Observação: Para objetos de diretório como usuários, os operadores not e ne são suportados apenas em consultas avançadas.

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

Operador all

O all operador aplica uma expressão booliana a cada membro de uma coleção e retorna true se a expressão for true para todos os itens da coleção, caso contrário, retornará false. Atualmente, não há suporte no Microsoft Graph.

Exemplos usando o operador de consulta de filtro

A tabela a seguir mostra alguns exemplos que usam o parâmetro de consulta $filter. Para obter mais informações, consulte o protocolo OData.

Observação

Descrição Exemplo
Pesquisar por usuários com o nome Clara entre várias propriedades. OBTER~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Obter todos os usuários com o domínio de email igual a 'hotmail.com' OBTER~/users?$count=true&$filter=endswith(mail,'@hotmail.com') **
Obtenha todos os usuários sem licenças atribuídas OBTER~/users?$filter=assignedLicenses/$count eq 0&$count=true **
Obter todos os eventos do usuário conectado que começaram após 01/07/2017. GET~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'.
NOTA: A propriedade dateTime da entidade de evento é um tipo string.
Obter todos os emails de um endereço específico recebidos pelo usuário conectado. OBTER~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Obter todos os emails recebidos pelo usuário conectado em abril de 2017. OBTER~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Obter todos os emails não lidos na caixa de entrada do usuário conectado. OBTER~/me/mailFolders/inbox/messages?$filter=isRead eq false
Obter todos os usuários nos departamentos de Varejo e Vendas. OBTER~/users?$filter=department in ('Retail', 'Sales')
Listar os usuários com um plano de serviço específico que está em um estado suspenso. OBTER~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true **
Listar todos os grupos que não são do Microsoft 365 em uma organização. OBTER~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true **
Liste todos os usuários cujo nome da empresa não esteja indefinido (ou seja, não um null valor) ou Microsoft. OBTER~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true **
Listar todos os usuários cujo nome da empresa seja indefinido ou Microsoft. OBTER~/users?$filter=companyName in (null, 'Microsoft')&$count=true **
Use a conversão OData para obter uma participação transitória em grupos com um nome de exibição que comece com “a”, incluindo o número de objetos retornados. OBTER~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a') **

Sintaxe para usar o parâmetro de consulta OData de filtro

O artigo a seguir demonstra a sintaxe para usar o $filter parâmetro de consulta OData e seus operadores associados. Os exemplos são fornecidos apenas para diretrizes e não refletem uma lista abrangente para o aplicativo de $filter.

Observação

  • Os valores GUID e DateTimeOffset não estão entre aspas nas $filter expressões.

** : este exemplo só tem suporte com recursos avançados de consulta.

Para tipos primitivos únicos, como String, Int e datas

Operador Sintaxe
eq ~/users?$filter=userType eq 'Member'
not ~/users?$filter=not(userType eq 'Member') **
ne ~/users?$filter=companyName ne null **
startswith ~/users?$filter=startswith(userPrincipalName, 'admin')
endswith ~/users?$filter=endswith(mail,'@outlook.com') **
in ~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')

Nota: Para cadeias de caracteres de consulta usando in operador, a solicitação é limitada a 15 expressões na cláusula de filtro por padrão ou um comprimento de URL de 2.048 caracteres ao usar recursos avançados de consulta.
le ~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z **
ge ~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z **
not e endswith ~/users?$filter=not(endswith(mail, 'contoso.com')) **
not e startswith ~/users?$filter=not(startswith(mail, 'A')) **
not e eq ~/users?$filter=not(companyName eq 'Contoso E.A.') **
not e in ~/users?$filter=not(userType in ('Member')) **
contains ~/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, './members')
has ~/identity/conditionalAccess/templates?$filter=scenarios has 'secureFoundation'

Para uma coleção de tipos primitivos

Operador (s) Sintaxe
eq ~/groups?$filter=groupTypes/any(c:c eq 'Unified')
not ~/groups?$filter=not(groupTypes/any(c:c eq 'Unified')) **
ne ~/users?$filter=companyName ne null **
startswith ~/users?$filter=businessPhones/any(p:startswith(p, '44')) **
endswith ~/users?$filter=endswith(mail,'@outlook.com') **
not e endswith ~/groups?$filter=not(endswith(mail,'contoso.com')) **
not e startswith ~/groups?$filter=not(startswith(mail,'Pineview')) **
not e eq ~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com') **
eq e $count para coleções vazias ~/users?$filter=assignedLicenses/$count eq 0 **
ne e $count para coleções vazias ~/users?$filter=assignedLicenses/$count ne 0 **
not e $count para coleções vazias ~/users?$filter=not(assignedLicenses/$count eq 0) **
$count para coleções com um objeto ~/servicePrincipals?$filter=owners/$count eq 1 **

Para tipos GUID

Operador (s) Sintaxe
eq ~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47 **
not ~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47) **

Para uma coleção de tipos GUID

Operador (s) Sintaxe
eq ~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2) **
le ~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2) **
ge ~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2) **

Para uma coleção de tipos complexos

Operador (s) Sintaxe
eq ~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil') **
not e eq ~/users?$filter=not(certificateUserIds/any(x:x eq '9876543210@mil')) **
startswith ~/users?$filter=certificateUserIds/any(x:startswith(x,'987654321')) **
endswith ~/users?$filter=proxyAddresses/any(p:endswith(p,'contoso.com')) **