Skip to main content

Recipient

View as Markdown

RecipientInfo object​

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

Values:

  • TOKEN
  • DATABRICKS
  • OIDC_FEDERATION
  • OAUTH_CLIENT_CREDENTIALS
sharing_codestring

The one-time sharing code provided by the data recipient. This field is only present when the authentication_type is DATABRICKS.

data_recipient_global_metastore_idstring

The global Unity Catalog metastore id provided by the data recipient. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

ownerstring

Username of the recipient owner.

commentstring

Description about the recipient.

ip_access_listobject

IP Access List

Show child attributesHide child attributes
allowed_ip_addressesarray of string

Allowed IP Addresses in CIDR notation. Limit of 100.

properties_kvpairsobject

Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write.

Show child attributesHide child attributes
propertiesobject

A map of key-value properties attached to the securable.

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

activation_urlstringDeprecatedOutput only

Full activation url to retrieve the access token. It will be empty if the token is already retrieved.

activatedbooleanDeprecatedOutput only

A boolean status field showing whether the Recipient's activation URL has been exercised or not.

created_atint64Output only

Time at which this recipient was created, in epoch milliseconds.

created_bystringOutput only

Username of recipient creator.

tokensarray of objectOutput only

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes
idstringOutput only

Unique ID of the recipient token.

created_atint64Output only

Time at which this recipient token was created, in epoch milliseconds.

created_bystringOutput only

Username of recipient token creator.

activation_urlstringOutput only

Full activation URL to retrieve the access token. It will be empty if the token is already retrieved.

expiration_timeint64Output only

Expiration timestamp of the token in epoch milliseconds.

updated_atint64Output only

Time at which this recipient token was updated, in epoch milliseconds.

updated_bystringOutput only

Username of recipient token updater.

updated_atint64Output only

Time at which the recipient was updated, in epoch milliseconds.

updated_bystringOutput only

Username of recipient updater.

cloudstringOutput only

Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

regionstringOutput only

Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

metastore_idstringOutput only

Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the authentication_type is DATABRICKS.

idstringOutput only

[Create,Update:IGN] common - id of the recipient

Get a share recipient GA​

GET /api/2.1/unity-catalog/recipients/{name}

Gets a share recipient from the metastore. The caller must be one of:

  • A user with USE_RECIPIENT privilege on the metastore
  • The owner of the share recipient
  • A metastore admin

API scopes: sharing

Parameters​

namestringRequiredpath

Name of the recipient.

Response​

Returns the RecipientInfo object.

List share recipients GA​

GET /api/2.1/unity-catalog/recipients

Gets an array of all share recipients within the current metastore where:

  • the caller is a metastore admin, or
  • the caller is the owner. There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

Parameters​

data_recipient_global_metastore_idstringquery

If not provided, all recipients will be returned. If no recipients exist with this ID, no results will be returned.

max_resultsint32query

Maximum number of recipients 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 recipients are returned (not recommended).
  • Note: The number of returned recipients might be less than the specified max_results size, even zero. The only definitive indication that no further recipients can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

Response​

Returns a list of RecipientInfo objects.

Create a share recipient GA​

POST /api/2.1/unity-catalog/recipients

Creates a new recipient with the delta sharing authentication type in the metastore. The caller must be a metastore admin or have the CREATE_RECIPIENT privilege on the metastore.

API scopes: sharing

Request body​

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

Values:

  • TOKEN
  • DATABRICKS
  • OIDC_FEDERATION
  • OAUTH_CLIENT_CREDENTIALS
sharing_codestring

The one-time sharing code provided by the data recipient. This field is only present when the authentication_type is DATABRICKS.

data_recipient_global_metastore_idstring

The global Unity Catalog metastore id provided by the data recipient. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

ownerstring

Username of the recipient owner.

commentstring

Description about the recipient.

ip_access_listobject

IP Access List

Show child attributesHide child attributes
allowed_ip_addressesarray of string

Allowed IP Addresses in CIDR notation. Limit of 100.

properties_kvpairsobject

Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write.

Show child attributesHide child attributes
propertiesobjectRequired

A map of key-value properties attached to the securable.

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

Response​

Returns the RecipientInfo object.

Update a share recipient GA​

PATCH /api/2.1/unity-catalog/recipients/{name_arg}

Updates an existing recipient in the metastore. The caller must be a metastore admin or the owner of the recipient. If the recipient name will be updated, the user must be both a metastore admin and the owner of the recipient.

API scopes: sharing

Parameters​

name_argstringRequiredpath

Name of the recipient.

Request body​

new_namestring

New name for the recipient. .

namestring

Name of Recipient.

authentication_typestring

The delta sharing authentication type.

Values:

  • TOKEN
  • DATABRICKS
  • OIDC_FEDERATION
  • OAUTH_CLIENT_CREDENTIALS
sharing_codestring

The one-time sharing code provided by the data recipient. This field is only present when the authentication_type is DATABRICKS.

data_recipient_global_metastore_idstring

The global Unity Catalog metastore id provided by the data recipient. This field is only present when the authentication_type is DATABRICKS. The identifier is of format cloud:region:metastore-uuid.

ownerstring

Username of the recipient owner.

commentstring

Description about the recipient.

ip_access_listobject

IP Access List

Show child attributesHide child attributes
allowed_ip_addressesarray of string

Allowed IP Addresses in CIDR notation. Limit of 100.

properties_kvpairsobject

Recipient properties as map of string key-value pairs. When provided in update request, the specified properties will override the existing properties. To add and remove properties, one would need to perform a read-modify-write.

Show child attributesHide child attributes
propertiesobjectRequired

A map of key-value properties attached to the securable.

expiration_timeint64

Expiration timestamp of the token, in epoch milliseconds.

Response​

Returns the RecipientInfo object.

Delete a share recipient GA​

DELETE /api/2.1/unity-catalog/recipients/{name}

Deletes the specified recipient from the metastore. The caller must be the owner of the recipient.

API scopes: sharing

Parameters​

namestringRequiredpath

Name of the recipient.

Rotate a token GA​

POST /api/2.1/unity-catalog/recipients/{name}/rotate-token

Refreshes the specified recipient's delta sharing authentication token with the provided token info. The caller must be the owner of the recipient.

API scopes: sharing

Parameters​

namestringRequiredpath

The name of the Recipient.

Request body​

existing_token_expire_in_secondsint64Required

The expiration time of the bearer token in ISO 8601 format. This will set the expiration_time of existing token only to a smaller timestamp, it cannot extend the expiration_time. Use 0 to expire the existing token immediately, negative number will return an error.

Response​

Returns the RecipientInfo object.