API View Model
View Model Options
The DevOps Secrets Safe View Model consists of the following options:
- Verbosity: When used, returns a full attribute listing of whatever element is being discovered. Otherwise, a slim view of the element is returned.
- Depth: The maximum depth of the view to return. A value of 0 returns only the element being discovered. A value of 1 returns the element specified and all direct children. A value of 2 returns all children and grandchildren of the element being discovered.
- Pagination: Pagination consists of two options:
- Page Size: The number of records to return for the direct children of the element being discovered. Values must be between 1 and 100.
All grandchildren of the element being discovered will also be limited to this page size if it is specified, otherwise, it will be limited to the maximum page size of 100.
- Page Number: The page number (1-based) of results to return.
- Sorting: Specifies the sort order to use with the elements being discovered.
View Model Usage
Each sub command get operation supports all or some subset of the following view model options:
- -v, --verbose: Verbosity is optional and defaults to false.
- -d, --depth: Depth is optional and defaults to 1.
- -ps, --page-size: Page size is optional and defaults to 50. Invalid values are forced within the range of 1 and 100 (maximum page size).
- -pn, --page_number: Page number is optional and defaults to 1. Invalid values are forced within the range of 1 and the total page count.
- -sb, --sort-by: Sorting is optional, and by default, no sorting is applied. This is defined as a single field or comma-delimited list of fields with the sort order (one of: asc or desc) specified in brackets after each.
Name(desc) OR Name(desc),Url(asc)
To determine what options are supported for each sub command get operation, use the -h (help) flag.
$ssrun user get -h
Usage: ssrun user get [-h] [-n USERNAME] [-i IDENTITY_PROVIDER] [-v] [-ps PAGE_SIZE] [-pn PAGE_NUMBER] [-sb SORT_BY] optional arguments: -h, --help : Show this help message and exit. -n, --name : If a name is specified, only that user is returned and sorting and pagination options are ignored. If no name is specified, a list of users is returned with sorting and pagination options (if specified) applied. -i, --identity-provider : Identity provider name. Defaults to internal if not specified. -v, --verbose : Verbose output. Use the -v flag to get a full listing of users attributes. Otherwise, a slim view of each user is returned. -ps, --page-size : Specifies the maximum number of elements to return in the user listing. Value must be between 1 and 100. All membership or group listings are also limited to this page size. -pn, --page_number : Specifies the page number (1-based) of results to return. -sb, --sort-by : Specifies the sort order for the users list. This is defined as a single field or comma delimeted list of fields with the sort order (one of:ace|desc) specified in brackets after each. For example: Name(desc) OR Name(desc),Url(asc).
In the above example, the get operation for the user sub command does not support the depth option. Whereas, it does for the safelist sub command:
$ ssrun safelist get -h
optional arguments: -h, --help : Show this help message and exit. -n, --name : If a name is specified, only that safelist is returned and sorting and pagination options are ignored. If no name is specified, a list of safelists is returned with sorting and pagination options (if specified) applied. -v, --verbose : Verbose output. Use the -v flag to get a full listing of safelist and IP range attributes. Otherwise, a slim view of each safelist and ip range is returned. -d, --depth : The maximum depth of the view to return. A value of 0 returns only the element specified. A value of 1 returns the element specified and all direct children. A value of 2 returns all children and grandchildren of the element specified. -ps, --page-size : Specifies the maximum number of elements to return in the safelist listing. Value must be between 1 and 100. All IP range listings are also limited to this page size. -pn, --page_number : Specifies the page number (1-based) of results to return. -sb, --sort-by : Specifies the sort order for the safelist list. This is defined as a single field or comma delimeted list of fields with the sort order (one of:ace|desc) specified in brackets after each. For example: Name(desc) OR Name(desc),Url(asc).
Discovery Results
When paging is applied to a result set, the output always contains the following block of pagination information:
"Paging": { "CurrentPage": 1, "PageCount": 15, "PageSize": 10, "TotalSize": 147 }
- CurrentPage: The current page of the results that were discovered.
- PageCount: The page number of the results that were returned.
- PageSize: The total the number of results that were returned.
- TotalSize: The total number of elements that exist.
In the example below, we specify that we want to use a page size of ten, that we want to view the second page of that result set, and that we want to sort the results in ascending order by name:
$ ssrun user get -ps 10 -pn 2 -sb 'Name(asc)'
{ "Uri": "/principal/internal/user", "Users": [ { "Uri": "/principal/internal/user/Berta" }, { "Uri": "/principal/internal/user/Bob" }, { "Uri": "/principal/internal/user/Boomer" }, { "Uri": "/principal/internal/user/Brad" }, { "Uri": "/principal/internal/user/Brenda" }, { "Uri": "/principal/internal/user/Catherine" }, { "Uri": "/principal/internal/user/Cathy" }, { "Uri": "/principal/internal/user/Chloe" }, { "Uri": "/principal/internal/user/Chris" }, { "Uri": "/principal/internal/user/Cicilia" } ], "Paging": { "CurrentPage": 2, "PageCount": 15, "PageSize": 10, "TotalSize": 147 } }
In the above example, the paging information informs us that there are a total of 15 pages available for discovery (given the page size we specified), and there are a total of 147 users.