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 |
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 |
|
Operadores Lambda |
|
Operadores condicionais |
|
Functions |
|
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
ene
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
- Exemplos marcados com ** só têm suporte com recursos avançados de consulta.
- Clique no método HTTP para experimentar os exemplos no Graph Explorer.
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')) ** |
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
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, consulteEnviar e exibir comentários de