Recipient
RecipientInfo object
- namestring
Name of Recipient.
- authentication_typestring
The delta sharing authentication type.
- 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
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 GA
GET
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.
- page_tokenstringquery
Opaque pagination token to go to next page based on previous query.
Response
Returns a list of RecipientInfo objects.
Create GA
POST
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.
- 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.
- 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
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.
- 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.
- 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
Rotate Recipient Token GA
POST
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.