Parâmetros de Consulta

Você pode incluir parâmetros de consulta em solicitações à API REST de domínios de identidades. Esses parâmetros são úteis para localizar recursos com atributos específicos ou valores de atributo 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 consultas dependem do serviço REST. Os serviços REST sem SCIM podem não suportar a filtragem e os parâmetros avançados que você deseja usar.

Liste apenas recursos que contenham atributos especificados ou que tenham valores especificados para atributos.
Limite os atributos retornados no corpo da resposta.
Classifica a saída em um atributo especificado, em ordem crescente ou decrescente.
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 pela 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. O + substitui espaços e %22 substitui 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 termine em /.search. Nesse caso, você coloca a consulta no corpo da solicitação. Ao procurar informações confidenciais, como nomes de usuário, onde as informações confidenciais são enviadas junto com outros dados, use este 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 HTTP	Descrição
`attributes=attribute1,attribute2`	Especifica uma lista de strings com vários valores indicando os nomes dos atributos do 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) always (retorna todos os atributos marcados como sempre no esquema) padrão (retorna todos os atributos padrão) request (retorna todos os atributos marcados como solicitação no esquema) Esses valores não fazem distinção entre maiúsculas e 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 de 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 primeiro resultado da 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 uma `sortOrder`, a `sortOrder` assumirá como padrão `ascending.`

Usando o Parâmetro de Consulta de Filtro

Você pode usar a consulta filter em pesquisas que executa 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 por um operador de atributo e um valor opcional. Os atributos pesquisáveis variam de um recurso para outro. Estes são discutidos nos tópicos para essas solicitações 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 do 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`	Inicia com	O valor inteiro do operador deve ser uma substring do valor do atributo, começando no início do valor do atributo. Este critério é satisfeito 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. Este critério é satisfeito se as duas strings forem idênticas.
`pr`	Presente (tem valor)	Se o atributo tiver um valor não vazio ou se ele contiver um nó não vazio para atributos complexos, haverá uma correspondência.
`gt`	Maior que	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 os tipos `DateTime`, é uma comparação cronológica.
`ge`	Maior que ou igual	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 os 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 os 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 os 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 filtros de atributos complexos.

Exemplos de Filtro de Parâmetros de Consulta

Use os exemplos de parâmetros de consulta a seguir como ponto de partida 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 pesquisa 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 da 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 que usam 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 pesquisa usuários cujo número de telefone começa com "+1"*.

Nota

Só funciona 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 pesquisa usuários que contêm o número de telefone residencial com 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 pesquisa 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 pesquisa 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 da AppRole usando a 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