Skip to main content

Recipient

View as Markdown

RecipientInfo object​

namestring

Name of Recipient.

authentication_typestring

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_urlstring

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

activatedboolean

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

created_atint64

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

created_bystring

Username of recipient creator.

tokensarray of object

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes
idstring

Unique ID of the recipient token.

created_atint64

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

created_bystring

Username of recipient token creator.

activation_urlstring

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

expiration_timeint64

Expiration timestamp of the token in epoch milliseconds.

updated_atint64

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

updated_bystring

Username of recipient token updater.

updated_atint64

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

updated_bystring

Username of recipient updater.

cloudstring

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

regionstring

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

metastore_idstring

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

idstring

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

Get 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​

namestringpath

Name of the recipient.

Response​

Returns the RecipientInfo object.

Create 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

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_urlstring

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

activatedboolean

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

created_atint64

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

created_bystring

Username of recipient creator.

tokensarray of object

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes
idstring

Unique ID of the recipient token.

created_atint64

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

created_bystring

Username of recipient token creator.

activation_urlstring

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

expiration_timeint64

Expiration timestamp of the token in epoch milliseconds.

updated_atint64

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

updated_bystring

Username of recipient token updater.

updated_atint64

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

updated_bystring

Username of recipient updater.

cloudstring

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

regionstring

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

metastore_idstring

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

idstring

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

Response​

Returns the RecipientInfo object.

Update 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_argstringpath

Name of the recipient.

Request body​

new_namestring

New name for the recipient. .

namestring

Name of Recipient.

authentication_typestring

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_urlstring

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

activatedboolean

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

created_atint64

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

created_bystring

Username of recipient creator.

tokensarray of object

This field is only present when the authentication_type is TOKEN.

Show child attributesHide child attributes
idstring

Unique ID of the recipient token.

created_atint64

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

created_bystring

Username of recipient token creator.

activation_urlstring

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

expiration_timeint64

Expiration timestamp of the token in epoch milliseconds.

updated_atint64

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

updated_bystring

Username of recipient token updater.

updated_atint64

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

updated_bystring

Username of recipient updater.

cloudstring

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

regionstring

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

metastore_idstring

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

idstring

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

Response​

Returns the RecipientInfo object.

Delete 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​

namestringpath

Name of the recipient.