Como formular e testar uma consulta de assinatura

Este documento explica como formular e testar as suas consultas de associação para garantir que os usuários corretos sejam retornados.

Antes de começar

Execute as seguintes tarefas antes de continuar com as informações desta página:

Leia a visão geral da API Groups.
Leia a visão geral dos grupos dinâmicos.
Configure a API Groups.

Como formular e testar sua consulta

As consultas de assinatura têm o formato target_field condition e são formatadas como expressões de Common Expression Language (CEL, na sigla em inglês). Veja a lista de campos do recurso User que podem ser usados em Atributos de usuário válidos para grupos dinâmicos.

Amostras de consultas

O exemplo a seguir mostra como verificar um valor específico em um campo user.addresses usando a função CEL exists():

user.addresses.exists(ad, ad.locality=='Sunnyvale')

A macro exists() é usada para criar consultas de assinatura para campos do tipo de lista.

Veja um exemplo de verificação de vários valores, (criação) de area e building_id, em uma única entrada de lista:

user.locations.exists(loc, loc.area=='Sunnyvale' && loc.building_id=='Building 1')

O exemplo a seguir mostra como encontrar usuários que fazem parte de uma determinada unidade organizacional:

Todos os usuários diretos em uma determinada unidade organizacional: user.org_unit_id==orgUnitId('03ph8a2z1enx4lx')
Todos os usuários diretos e indiretos em uma determinada unidade organizacional: user.org_units.exists(org_unit, org_unit.org_unit_id==orgUnitId('03ph8a2z1khexns'))

user.name.value.equalsIgnoreCase('jOhn DoE')`

Negação nas consultas

Você pode usar um operador NOT ! em consultas de associação para excluir usuários com determinados atributos. Confira alguns exemplos a seguir:

Todos os usuários que não pertencem a uma determinada unidade organizacional:
```
!(user.org_unit_id==orgUnitId('03ph8a2z1enx4lx'))
```
Todos os usuários que não pertencem à organização Marketing:
```
!user.organization.exists(org, org.title = "Marketing")
```

Algumas combinações do operador NOT ! e da macro exists() não são compatíveis:

Qualquer consulta NOT ! que use a macro exists() e o operador AND && dentro dela:

!user.organization.exists(org, (org.title == "Cloud" && org.department == "Sales"))

Qualquer consulta que use a macro exists() com o operador NOT ! dentro dela:

user.organization.exists(org, (org.title == "Cloud" || !(org.department == "Sales")))

Como testar consultas de assinatura

Para testar suas consultas de assinatura, use o criador de consultas simples. Ele permite usar menus suspensos e campos de texto para inserir e testar uma consulta. Depois de confirmar que a consulta de associação está retornando os resultados corretos, crie as consultas CEL correspondentes com a API Groups.

Atributos personalizados do usuário

Os atributos de usuário personalizados podem ser usados em consultas de grupos dinâmicos, desde que o esquema personalizado já exista em user.custom_schemas, mas não são aceitos nos menus suspensos do criador de consultas simples. Para testar uma consulta de um atributo de usuário personalizado, insira-a no formato de consulta CEL diretamente na caixa de texto Inserir consulta CEL. Veja um exemplo de esquema personalizado:

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "true"
    }
  ]
}

Campo de valor único

user.custom_schemas.employmentData.EmployeeNumber == 'value'

Campo de vários valores

user.custom_schemas.employmentData.JobFamily.exists(fld, fld == 'value')

A seguir

Depois de testar sua consulta de assinatura, será possível usá-la ao criar um grupo. Para mais informações, consulte Como criar um grupo dinâmico.