Parâmetros de Consulta

Você pode incluir parâmetros de consulta em solicitações à API REST dos domínios de identidades. Esses parâmetros são úteis para localizar recursos com atributos ou valores de atributo específicos e para classificar e paginar a saída.

Sobre Parâmetros de Consulta

Usando uma consulta, você pode filtrar a saída para:

Observação

Os recursos de filtragem de consulta dependem do serviço REST. Os serviços REST sem SCIM podem não suportar a filtragem avançada e os parâmetros que você deseja usar.

Lista apenas os recursos que contêm atributos especificados ou têm valores especificados para atributos.
Limite os atributos retornados no corpo da resposta.
Classificar o resultado em um atributo especificado, em ordem crescente ou descendente.
Limite o número de recursos retornados.
Especifique onde, na lista de recursos da coleção, iniciar a solicitação.

Os parâmetros de consulta geralmente são usados com métodos de pesquisa:

GET: Para filtrar os resultados da pesquisa. Consulte Parâmetros de Consulta com GET.
POST: Para filtrar os resultados da pesquisa usando os parâmetros no corpo da Solicitação (por motivos de segurança). Consulte Parâmetros de Consulta com um Corpo de Solicitação POST /.search.

Parâmetros de Consulta com GET

Ao executar uma pesquisa usando uma solicitação GET em um ponto final de recurso, como /Users ou /Groups, você coloca a consulta no URL. Anexe um ponto de interrogação (?) ao URL, seguido da consulta.

Observação

Os caracteres em um URL que estão fora do conjunto de caracteres ASCII, como espaços e aspas, devem ser codificados por URL. Exemplos são fornecidos com caracteres codificados por URL. + substitui espaços e %22 substitui as aspas (").

https://<domainURL>/admin/v1/Users?attributes=email&filter=userName+co+%22jensen%22

Para localizar todos os Grupos e AppRoles associados a um usuário específico:

https://<domainURL>/admin/v1/Users/1e895413c68d42c7bc006d0033794c1e?attributes=groups,urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:appRoles

Parâmetros de Consulta com um Corpo de Solicitação POST /.search

Você pode criar pesquisas com uma solicitação POST em um ponto final de recurso que termina em /.search. Nesse caso, você coloca a consulta no corpo da solicitação. Ao procurar informações confidenciais, como nomes de usuário, em que as informações confidenciais são enviadas juntamente com outros dados, use esse método (por motivos de segurança).

Este exemplo mostra o corpo da solicitação de um método POST executado no ponto final /Users/.search. Ele retorna as primeiras 10 entradas de usuário com displayName começando com smith e meta.resourceType igual a User.

{ 
"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"attributes": ["displayName","userName"], 
"filter": "(displayName sw \"smith\")", "startIndex": 1, "count": 10
}

O parâmetro attributes pode ser usado com todos os métodos, exceto DELETE. Os outros parâmetros de consulta são significativos apenas para métodos de pesquisa e são ignorados por outros métodos.


Parâmetro de Consulta de HTTP	Descrição
`attributes=attribute1,attribute2`	Especifica uma lista de strings com vários valores indicando os nomes dos atributos de recurso a serem retornados na resposta. Este parâmetro de consulta também aceita o ID do esquema de extensão como um nome de atributo válido. A inclusão do ID do esquema de extensão nos atributos retorna todos os atributos padrão dentro dele.
`attributeSets`	A pesquisa retorna um grupo de atributos na resposta, em vez de especificar cada atributo individualmente. Este parâmetro de consulta aceita valores separados por vírgulas dos seguintes parâmetros: all (retorna todos os atributos) sempre (retorna todos os atributos marcados como sempre no esquema) padrão (retorna todos os atributos padrão) request (retorna todos os atributos marcados como request no esquema) Esses valores não diferenciam maiúsculas de minúsculas. Se `attributes` e `attributeSets` forem especificados na solicitação, os valores de ambos serão retornados na resposta.
`count=N`	Indica o número máximo de resultados da pesquisa por página. Especifique um número não negativo para recuperar uma resposta. Um número negativo assume 50 como padrão e retorna os primeiros 50 recursos.
`startIndex=N`	Especifica o índice da página inicial. Este é o índice baseado em 1 do resultado da primeira consulta. Um valor menor que 1 é interpretado como 1.
`filter=Expression`	A pesquisa retorna todos os recursos no ponto final especificado para o qual a expressão é verdadeira. Consulte Usando o Parâmetro de Consulta de Filtro para obter mais informações.
`sortBy=attribute`	Fornece o nome do atributo no qual a resposta deve ser classificada.
`sortOrder=ascending` \| `sortOrder=descending`	Especifica a ordem na qual o parâmetro `sortBy` é aplicado. Se você especificar um valor para `sortBy` e não especificar um `sortOrder`, o padrão `sortOrder` será `ascending.`

Usando o Parâmetro de Consulta de Filtro

Você pode usar a consulta filter em pesquisas executadas com o método GET. O formato de uma consulta de filtro é:

filter=Expression

Um filtro deve conter pelo menos uma expressão válida. Cada expressão contém um nome de atributo seguido de um operador de atributo e um valor opcional. Os atributos pesquisáveis variam de um recurso para outro. Eles são discutidos nos tópicos dessas solicitações do GET.

O URL a seguir inclui uma consulta de filtro para usuários com o atributo userName que contém jensen:

https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22


Operador de Atributo	Descrição	Comportamento
`eq`	Igual	Os valores de atributo e operador devem ser idênticos para uma correspondência.
`ne`	Diferente	Os valores de atributo e operador não são idênticos.
`co`	Contém	O valor inteiro do operador deve ser uma substring do valor do atributo para uma correspondência.
`sw`	Começa com	O valor inteiro do operador deve ser uma substring do valor do atributo, começando no início do valor do atributo. Esse critério será atendido se as duas strings forem idênticas.
`ew`	termina com	O valor inteiro do operador deve ser uma substring do valor do atributo, correspondente no final do valor do atributo. Esse critério será atendido se as duas strings forem idênticas.
`pr`	Presente (tem valor)	Se o atributo tiver um valor não vazio ou se contiver um nó não vazio para atributos complexos, haverá uma correspondência.
`gt`	Superior a	Se o valor do atributo for maior que o valor do operador, haverá uma correspondência. A comparação real depende do tipo de atributo. Para tipos de atributo de string, essa é uma comparação lexicográfica e, para tipos `DateTime`, é uma comparação cronológica.
`ge`	Maior que ou igual a	Se o valor do atributo for maior ou igual ao valor do operador, haverá uma correspondência. A comparação real depende do tipo de atributo. Para tipos de atributo de string, essa é uma comparação lexicográfica e, para tipos `DateTime`, é uma comparação cronológica.
`lt`	Menor que	Se o valor do atributo for menor que o valor do operador, haverá uma correspondência. A comparação real depende do tipo de atributo. Para tipos de atributo de string, essa é uma comparação lexicográfica e, para tipos `DateTime`, é uma comparação cronológica.
`le`	Menor ou igual a	Se o valor do atributo for menor ou igual ao valor do operador, haverá uma correspondência. A comparação real depende do tipo de atributo. Para tipos de atributo de string, essa é uma comparação lexicográfica e, para tipos `DateTime`, é uma comparação cronológica.

Você pode combinar várias expressões usando os operadores lógicos and e or e negar uma expressão precedendo-a com o operador de atributo not. Use parênteses () para agrupamento de precedência e colchetes [] para agrupamento de filtro de atributo complexo.

Exemplos de Filtro de Parâmetros de Consulta

Use os exemplos de parâmetros de consulta a seguir como ponto inicial para consultas em um domínio de identidades.

Exemplos de Usuário

Para procurar usuários com o atributo userName igual a example, use este filtro:

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22

Este exemplo de filtro procura um usuário com um userName que contenha jensen:

https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22

Este exemplo de filtro procura um usuário com um userName que contenha example ou que comece com my:

https://<domainURL>/admin/v1/Users?filter=userName+co+%22example%22+or+userName+sw+%22my%22

Este exemplo de filtro procura um usuário com o subatributo familyName de name que contém jensen:

https://<domainURL>/admin/v1/Users?filter=name.familyName+co+%22jensen%22

Este exemplo de consulta de URL complexo retorna todos os usuários com um userName igual a example, lista os atributos emails.value e name.familyName no corpo de resposta JSON e retorna um máximo de oito usuários por página de saída.

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22&attributes=emails.value,name.familyName&count=8

Este exemplo de filtro procura usuários usando o parâmetro de filtro em GET.

https://<domainURL>/admin/v1/Users/?filter=phoneNumbers.value co "415"

Este exemplo de filtro retorna usuários que têm o atributo personalizado pesquisável Nickname. Para saber mais sobre atributos personalizados pesquisáveis, consulte Personalizando Esquemas do Usuário e Personalizando Esquemas.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname pr)

Este exemplo de filtro retorna usuários cujo atributo personalizado pesquisável corresponde a uma string de texto. Para saber mais sobre atributos personalizados pesquisáveis, consulte Personalizando Esquemas do Usuário e Personalizando Esquemas.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname eq "aabbccc")

Exemplos de Número de Telefone

Este exemplo de filtro procura usuários cujo número de telefone comece com "+1"*.

Nota

Funciona apenas com operações POST.


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"filter": "phoneNumbers.value sw \"+1\""
}

Este exemplo de filtro procura usuários cujo número de telefone residencial contenha a string "503".


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],  
"filter": "phoneNumbers[type eq \"home\"].value co \"503\""
}


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"filter": "phoneNumbers[type eq \"home\" and value co \"503\"]"
}

Este exemplo de filtro procura usuários com variações de número de telefone.

Nota

O parâmetro de filtro SCIM não suporta padrões RegEx. Você deve ter incluído todas as variações possíveis. Use o exemplo a seguir para começar.


POST https://<domainURL>/admin/v1/Users/.search 
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"phoneNumbers.value eq \"+1 9xxxx xxxxx\" or phoneNumbers.value eq \"+19xxxx xxxxx\" or phoneNUmbers.value eq \"+19xxxxxxxxx\""
}

Exemplos de Atribuição de Aplicativo

Este exemplo de filtro procura todos os usuários que têm um AppRole específico:

https://<domainURL>/admin/v1/Users?filter=urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:approles.value+eq+<idOfAppRole>

Este exemplo de filtro retorna membros do AppRole usando o approleid.


GET https://<domainURL>/admin/v1/AppRoles/{{approleid}}?attributes=members

Este exemplo de filtro retorna AppRoles para um aplicativo específico usando o appid.


GET https://<domainURL>/admin/v1/AppRoles?filter=app.value eq "{{appid}}"

Documentação do Oracle Cloud Infrastructure