diff --git a/specification/security/query_user/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts new file mode 100644 index 0000000000..977c7bdba2 --- /dev/null +++ b/specification/security/query_user/SecurityQueryUserRequest.ts @@ -0,0 +1,72 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { UserQueryContainer } from './types' +import { RequestBase } from '@_types/Base' +import { integer } from '@_types/Numeric' +import { Sort, SortResults } from '@_types/sort' + +/** + * Retrieves information for Users in a paginated manner. You can optionally filter the results with a query. + * @rest_spec_name security.query_user + * @availability stack since=8.14.0 stability=stable + * @availability serverless stability=stable visibility=private + * @cluster_privileges read_security + */ +export interface Request extends RequestBase { + body: { + /** + * A query to filter which users to return. + * If the query parameter is missing, it is equivalent to a `match_all` query. + * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, + * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. + * You can query the following information associated with user: `username`, `roles`, `enabled` + */ + query?: UserQueryContainer + /** + * Starting document offset. + * By default, you cannot page through more than 10,000 hits using the from and size parameters. + * To page through more hits, use the `search_after` parameter. + * @server_default 0 + */ + from?: integer + /** + * Fields eligible for sorting are: username, roles, enabled + * In addition, sort can also be applied to the `_doc` field to sort by index order. + * @doc_id sort-search-results */ + sort?: Sort + /** + * The number of hits to return. + * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. + * To page through more hits, use the `search_after` parameter. + * @server_default 10 + */ + size?: integer + /** + * Search after definition + */ + search_after?: SortResults + } + query_parameters: { + /** + * If true will return the User Profile ID for the users in the query result, if any. + */ + with_profile_uid?: boolean + } +} diff --git a/specification/security/query_user/SecurityQueryUserResponse.ts b/specification/security/query_user/SecurityQueryUserResponse.ts new file mode 100644 index 0000000000..c37d6344c5 --- /dev/null +++ b/specification/security/query_user/SecurityQueryUserResponse.ts @@ -0,0 +1,38 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { integer } from '@_types/Numeric' +import { QueryUser } from '@security/query_user/types' + +export class Response { + body: { + /** + * The total number of users found. + */ + total: integer + /** + * The number of users returned in the response. + */ + count: integer + /** + * A list of user information. + */ + users: QueryUser[] + } +} diff --git a/specification/security/query_user/types.ts b/specification/security/query_user/types.ts new file mode 100644 index 0000000000..e3c19f621a --- /dev/null +++ b/specification/security/query_user/types.ts @@ -0,0 +1,105 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { SingleKeyDictionary } from '@spec_utils/Dictionary' +import { Field } from '@_types/common' +import { BoolQuery } from '@_types/query_dsl/compound' +import { SortResults } from '@_types/sort' +import { + ExistsQuery, + IdsQuery, + PrefixQuery, + RangeQuery, + TermQuery, + TermsQuery, + WildcardQuery +} from '@_types/query_dsl/term' +import { MatchQuery, SimpleQueryStringQuery } from '@_types/query_dsl/fulltext' +import { MatchAllQuery } from '@_types/query_dsl/MatchAllQuery' +import { User } from '@security/_types/User' + +/** + * @variants container + * @non_exhaustive + */ +export class UserQueryContainer { + /** + * Returns users based on their IDs. + * This query uses the user document IDs stored in the `_id` field. + * @doc_id query-dsl-ids-query + */ + ids?: IdsQuery + /** + * matches users matching boolean combinations of other queries. + * @doc_id query-dsl-bool-query + */ + bool?: BoolQuery + /** + * Returns users that contain an indexed value for a field. + * @doc_id query-dsl-exists-query + */ + exists?: ExistsQuery + /** + * Returns users that match a provided text, number, date or boolean value. + * The provided text is analyzed before matching. + * @doc_id query-dsl-match-query + */ + match?: SingleKeyDictionary + /** + * Matches all users, giving them all a `_score` of 1.0. + * @doc_id query-dsl-match-all-query + */ + match_all?: MatchAllQuery + /** + * Returns users that contain a specific prefix in a provided field. + * @doc_id query-dsl-prefix-query + */ + prefix?: SingleKeyDictionary + /** + * Returns users that contain terms within a provided range. + * @doc_id query-dsl-range-query + */ + range?: SingleKeyDictionary + /** + * Returns users based on a provided query string, using a parser with a limited but fault-tolerant syntax. + * @doc_id query-dsl-simple-query-string-query + */ + simple_query_string?: SimpleQueryStringQuery + /** + * Returns users that contain an exact term in a provided field. + * To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization. + * @doc_id query-dsl-term-query + */ + term?: SingleKeyDictionary + /** + * Returns users that contain one or more exact terms in a provided field. + * To return a document, one or more terms must exactly match a field value, including whitespace and capitalization. + * @doc_id query-dsl-terms-query + */ + terms?: TermsQuery + /** + * Returns users that contain terms matching a wildcard pattern. + * @doc_id query-dsl-wildcard-query + */ + wildcard?: SingleKeyDictionary +} + +export class QueryUser extends User { + _sort?: SortResults +}