Update the access level for a REST API path or command/command directory path
Suggest changes
PDFs
PATCH /security/roles/{owner.uuid}/{name}/privileges/{path}
Introduced In: 9.6
Updates the access level for a REST API path or command/command directory path. Optionally updates the query, if 'path' refers to a command/command directory path. The REST API path can be a resource-qualified endpoint. Currently, the only supported resource-qualified endpoints are the following:
Snapshots APIs
– /api/storage/volumes/{volume.uuid}/snapshots
File System Analytics APIs
– /api/storage/volumes/{volume.uuid}/files
– /api/storage/volumes/{volume.uuid}/top-metrics/clients
– /api/storage/volumes/{volume.uuid}/top-metrics/directories
– /api/storage/volumes/{volume.uuid}/top-metrics/files
– /api/storage/volumes/{volume.uuid}/top-metrics/users
– /api/svm/svms/{svm.uuid}/top-metrics/clients
– /api/svm/svms/{svm.uuid}/top-metrics/directories
– /api/svm/svms/{svm.uuid}/top-metrics/files
– /api/svm/svms/{svm.uuid}/top-metrics/users
ONTAP S3 APIs
– /api/protocols/s3/services/{svm.uuid}/users
Artificial Intelligence Data Engine (AIDE) APIs
Data Compute Node (DCN) APIs
– /api/dcn/cluster/nodes/{node.uuid}/metrics
– /api/dcn/network/ports/{port.uuid}/metrics
Data-Engine APIs
– /api/data-engine/policies/{policy.uuid}/versions
– /api/data-engine/workspaces/{workspace.uuid}/acls
– /api/data-engine/workspaces/{workspace.uuid}/data-collections
– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/acls
– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{entity.uuid}/entities
– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/search
– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/versions
– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/versions/{version.uuid}/diffs
– /api/data-engine/workspaces/{workspace.uuid}/data-sources
– /api/data-engine/workspaces/{workspace.uuid}/entities
– /api/data-engine/workspaces/{workspace.uuid}/entities/{entity.uuid}/custom-attributes
– /api/data-engine/workspaces/{workspace.uuid}/queries
– /api/data-engine/workspaces/{workspace.uuid}/queries/{query.uuid}/entities
– /api/data-engine/workspaces/{workspace.uuid}/versions
– /api/data-engine/workspaces/{workspace.uuid}/versions/{version.uuid}/diffs
When used in the context of data collection APIs, {version.uuid} refers to a data collection version. In the context of workspace APIs, it refers to a workspace version.
In the APIs above, and in the context of REST roles, the wildcard character * can be used in place of {volume.uuid} or {svm.uuid} to represent all volumes or all SVMs, depending on whether the REST endpoint references volumes or SVMs. The {volume.uuid} corresponds to the -instance-uuid field in the output of the "volume show" command at the diagnostic privilege level. It can also be retrieved through the REST endpoint /api/storage/volumes.
In the AIDE APIs described above, and in the context of REST roles, the wildcard character * can be used in place of variable components in the Uniform Resource Identifier (URI) path, such as {node.uuid}, {port.uuid}, {policy.uuid}, {workspace.uuid}, {datacollection.uuid}, {entity.uuid}, {version.uuid}, or {query.uuid}. The specific variable to be replaced depends on whether the REST endpoint references nodes, ports, policies, workspaces, data collections, entities, versions, or queries.
However, when using the wildcard character * in place of a variable component in a URI path, it must replace
all variable components in that path. Mixing wildcards and specific values for different variable components within the same URI path is not supported in REST roles. For example, a URI path such as /api/data-engine/workspaces/c6e1b325-4125-11f0-abb5-bc2411f6fd43/data-collections/*/search is not supported.
In summary, only the following two types of resource-qualified endpoints are supported in a REST role:
-
All variable components in the URI path are specific values. Example: /api/data-engine/workspaces/c6e1b325-4125-11f0-abb5-bc2411f6fd43/data-collections/b09b6d25-4126-11f0-abb5-bc2411f6fd43/search
-
All variable components in the URI path are wildcards. Example: /api/data-engine/workspaces//data-collections//search
AIDE APIs are supported only in cluster-scoped REST roles, not in SVM-scoped REST roles.
Required parameters
-
owner.uuid- UUID of the SVM that houses this role. -
name- Name of the role to be updated. -
path- Constituent REST API path or command/command directory path, whose access level and/or query are/is to be updated. Can be a resource-qualified endpoint (example: /api/storage/volumes/43256a71-be02-474d-a2a9-9642e12a6a2c/snapshots). Currently, resource-qualified endpoints are limited to the Snapshots, File System Analytics_, Artificial Intelligence Data Engine (AIDE)_ and ONTAP S3 endpoints listed above in the description.
Optional parameters
-
access- Access level for the path. -
query- Optional query, if the path refers to a command/command directory path.
Related ONTAP commands
-
security login rest-role modify -
security login role modify
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
owner.uuid |
string |
path |
True |
Role owner UUID |
name |
string |
path |
True |
Role name |
path |
string |
path |
True |
REST API path or command/command directory path |
Request Body
| Name | Type | Description |
|---|---|---|
access |
string |
Access level for the REST endpoint or command/command directory path. If it denotes the access level for a command/command directory path, the only supported enum values are 'none','readonly' and 'all'. |
query |
string |
Optional attribute that can be specified only if the "path" attribute refers to a command/command directory path. The privilege tuple implicitly defines a set of objects the role can or cannot access at the specified access level. The query further reduces this set of objects to a subset of objects that the role is allowed to access. The query attribute must be applicable to the command/command directory specified by the "path" attribute. It is defined using one or more parameters of the command/command directory path specified by the "path" attribute. |
Example request
{
"access": "all",
"query": "-vserver vs1|vs2|vs3 -destination-aggregate aggr1|aggr2"
}Response
Status: 200, OkError
Status: DefaultONTAP Error Response Codes
| Error Code | Description |
|---|---|
5636168 |
This role is mapped to a REST role and can only be modified by updating the REST role. |
5636192 |
The query parameter cannot be specified for the privileges tuple with API endpoint entries. |
5636200 |
The specified value of the access parameter is invalid, if a command or command directory is specified in the path parameter. |
5636259 |
The specified child AIDE object was not found within the specified parent AIDE object. |
5636261 |
The specified grandchild AIDE object was not found within the specified child AIDE object that belongs to the specified parent AIDE object. |
Also see the table of common errors in the Response body overview section of this documentation.
Definitions
See Definitions
href
| Name | Type | Description |
|---|---|---|
href |
string |
_links
role_privilege
A tuple containing a REST endpoint or a command/command directory path and the access level assigned to that endpoint or command/command directory. If the "path" attribute refers to a command/command directory path, the tuple could additionally contain an optional query. The REST endpoint can be a resource-qualified endpoint. At present, the only supported resource-qualified endpoints are the following
Snapshots APIs
-
/api/storage/volumes/{volume.uuid}/snapshots
File System Analytics APIs
-
/api/storage/volumes/{volume.uuid}/files
-
/api/storage/volumes/{volume.uuid}/top-metrics/clients
-
/api/storage/volumes/{volume.uuid}/top-metrics/directories
-
/api/storage/volumes/{volume.uuid}/top-metrics/files
-
/api/storage/volumes/{volume.uuid}/top-metrics/users
-
/api/svm/svms/{svm.uuid}/top-metrics/clients
-
/api/svm/svms/{svm.uuid}/top-metrics/directories
-
/api/svm/svms/{svm.uuid}/top-metrics/files
-
/api/svm/svms/{svm.uuid}/top-metrics/users
-
/api/protocols/s3/services/{svm.uuid}/users
In the above APIs, wildcard character * could be used in place of {volume.uuid} or {svm.uuid} to denote all volumes or all SVMs, depending upon whether the REST endpoint references volumes or SVMs. The {volume.uuid} refers to the -instance-uuid field value in the "volume show" command output at diagnostic privilege level. It can also be fetched through REST endpoint /api/storage/volumes.
| Name | Type | Description |
|---|---|---|
access |
string |
Access level for the REST endpoint or command/command directory path. If it denotes the access level for a command/command directory path, the only supported enum values are 'none','readonly' and 'all'. |
query |
string |
Optional attribute that can be specified only if the "path" attribute refers to a command/command directory path. The privilege tuple implicitly defines a set of objects the role can or cannot access at the specified access level. The query further reduces this set of objects to a subset of objects that the role is allowed to access. The query attribute must be applicable to the command/command directory specified by the "path" attribute. It is defined using one or more parameters of the command/command directory path specified by the "path" attribute. |
error_arguments
| Name | Type | Description |
|---|---|---|
code |
string |
Argument code |
message |
string |
Message argument |
returned_error
| Name | Type | Description |
|---|---|---|
arguments |
array[error_arguments] |
Message arguments |
code |
string |
Error code |
message |
string |
Error message |
target |
string |
The target parameter that caused the error. |