Share Permission

View as Markdown

Get permissionsGET /api/2.1/unity-catalog/shares/{name}/permissionsUpdate permissionsPATCH /api/2.1/unity-catalog/shares/{name}/permissions

GetSharePermissionsResponse object

next_page_tokenstring

Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).

privilege_assignmentsarray of object

The privileges assigned to each principal

Show child attributesHide child attributes

principalstring

The principal (user email address or group name). For deleted principals, principal is empty while principal_id is populated.

privilegesarray of string

The privileges assigned to the principal.

Example: SELECT

View as Markdown

The GetSharePermissionsResponse object

{
  "next_page_token": "string",
  "privilege_assignments": [
    {
      "principal": "string",
      "privileges": [
        "SELECT"
      ]
    }
  ]
}

Get permissions GA

GET /api/2.1/unity-catalog/shares/{name}/permissions

Gets the permissions for a data share from the metastore. The caller must have the USE_SHARE privilege on the metastore or be the owner of the share.

API scopes: sharing

Parameters

namestringRequiredpath

The name of the share.

max_resultsint32<= 1000query

Maximum number of permissions to return.

• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to a value less than 0, an invalid parameter error is returned;
• If not set, all valid permissions are returned (not recommended).
• Note: The number of returned permissions might be less than the specified max_results size, even zero. The only definitive indication that no further permissions can be fetched is when the next_page_token is unset from the response.

page_tokenstringquery

Opaque pagination token to go to next page based on previous query.

Response

Returns the GetSharePermissionsResponse object.

View as Markdown

Response

{
  "next_page_token": "string",
  "privilege_assignments": [
    {
      "principal": "string",
      "privileges": [
        "SELECT"
      ]
    }
  ]
}

Update permissions GA

PATCH /api/2.1/unity-catalog/shares/{name}/permissions

Updates the permissions for a data share in the metastore. The caller must have both the USE_SHARE and SET_SHARE_PERMISSION privileges on the metastore, or be the owner of the share.

For new recipient grants, the user must also be the owner of the recipients. recipient revocations do not require additional privileges.

API scopes: sharing

Parameters

namestringRequiredpath

The name of the share.

Request body

omit_permissions_listboolean

Optional. Whether to return the latest permissions list of the share in the response.

changesarray of object

Array of permissions change objects.

Show child attributesHide child attributes

principalstring

The principal whose privileges we are changing. Only one of principal or principal_id should be specified, never both at the same time.

addarray of string

The set of privileges to add.

removearray of string

The set of privileges to remove.

Response

privilege_assignmentsarray of object

The privileges assigned to each principal

Show child attributesHide child attributes

principalstring

The principal (user email address or group name). For deleted principals, principal is empty while principal_id is populated.

privilegesarray of string

The privileges assigned to the principal.

Example: SELECT

View as Markdown

Request

{
  "omit_permissions_list": true,
  "changes": [
    {
      "principal": "string",
      "add": [
        "string"
      ],
      "remove": [
        "string"
      ]
    }
  ]
}

Response

{
  "privilege_assignments": [
    {
      "principal": "string",
      "privileges": [
        "SELECT"
      ]
    }
  ]
}