Workspace Binding

View as Markdown

GetGET /api/2.1/unity-catalog/bindings/{securable_type}/{securable_full_name}UpdatePATCH /api/2.1/unity-catalog/bindings/{securable_type}/{securable_full_name}

Get

GET /api/2.1/unity-catalog/bindings/{securable_type}/{securable_full_name}

Gets workspace bindings of the securable. The caller must be a metastore admin or an owner of the securable.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

securable_typestringpath

The type of the securable to bind to a workspace (catalog, storage_credential, credential, or external_location).

securable_full_namestringpath

The name of the securable.

max_resultsint32query

Maximum number of workspace bindings 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 the workspace bindings are returned (not recommended).

Constraints: <= 1000

page_tokenstringquery

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

Response

bindingsarray of object

List of workspace bindings

Show child attributesHide child attributes

workspace_idint64

Required

binding_typestring

One of READ_WRITE/READ_ONLY. Default is READ_WRITE.

Values: BINDING_TYPE_UNSPECIFIED, BINDING_TYPE_READ_WRITE, BINDING_TYPE_READ_ONLY

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).

View as Markdown

Response

{
  "bindings": [
    {
      "workspace_id": 0,
      "binding_type": "string"
    }
  ],
  "next_page_token": "string"
}

Update

PATCH /api/2.1/unity-catalog/bindings/{securable_type}/{securable_full_name}

Updates workspace bindings of the securable. The caller must be a metastore admin or an owner of the securable.

API scopes: unity-catalog

Parameters

securable_typestringpath

The type of the securable to bind to a workspace (catalog, storage_credential, credential, or external_location).

securable_full_namestringpath

The name of the securable.

Request body

addarray of object

List of workspace bindings to add. If a binding for the workspace already exists with a different binding_type, adding it again with a new binding_type will update the existing binding (e.g., from READ_WRITE to READ_ONLY).

Show child attributesHide child attributes

workspace_idint64

Required

binding_typestring

One of READ_WRITE/READ_ONLY. Default is READ_WRITE.

Values: BINDING_TYPE_UNSPECIFIED, BINDING_TYPE_READ_WRITE, BINDING_TYPE_READ_ONLY

removearray of object

List of workspace bindings to remove.

Show child attributesHide child attributes

workspace_idint64

Required

binding_typestring

One of READ_WRITE/READ_ONLY. Default is READ_WRITE.

Values: BINDING_TYPE_UNSPECIFIED, BINDING_TYPE_READ_WRITE, BINDING_TYPE_READ_ONLY

Response

bindingsarray of object

List of workspace bindings.

Show child attributesHide child attributes

workspace_idint64

Required

binding_typestring

One of READ_WRITE/READ_ONLY. Default is READ_WRITE.

Values: BINDING_TYPE_UNSPECIFIED, BINDING_TYPE_READ_WRITE, BINDING_TYPE_READ_ONLY

View as Markdown

Request

{
  "add": [
    {
      "workspace_id": 0,
      "binding_type": "string"
    }
  ],
  "remove": [
    {
      "workspace_id": 0,
      "binding_type": "string"
    }
  ]
}

Response

{
  "bindings": [
    {
      "workspace_id": 0,
      "binding_type": "string"
    }
  ]
}