recipients

Creates, updates, deletes, gets or lists a recipients resource.

Overview

Name	recipients
Type	Resource
Id	databricks_workspace.sharing.recipients

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	[Create,Update:IGN] common - id of the recipient
name	string	Name of Recipient.
data_recipient_global_metastore_id	string	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__.
metastore_id	string	Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
activated	boolean
activation_url	string	Full activation url to retrieve the access token. It will be empty if the token is already retrieved.
authentication_type	string	The delta sharing authentication type. (DATABRICKS, OAUTH_CLIENT_CREDENTIALS, OIDC_FEDERATION, TOKEN)
cloud	string	Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
comment	string	Description about the recipient.
created_at	integer	Time at which this recipient was created, in epoch milliseconds.
created_by	string	Username of recipient creator.
expiration_time	integer	Expiration timestamp of the token, in epoch milliseconds.
▶ip_access_list	object	IP Access List
owner	string	Username of the recipient owner.
▶properties_kvpairs	object	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.
region	string	Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
sharing_code	string	The one-time sharing code provided by the data recipient. This field is only present when the __authentication_type__ is **DATABRICKS**.
▶tokens	array	This field is only present when the __authentication_type__ is **TOKEN**.
updated_at	integer	Time at which the recipient was updated, in epoch milliseconds.
updated_by	string	Username of recipient updater.

list

Name	Datatype	Description
id	string	[Create,Update:IGN] common - id of the recipient
name	string	Name of Recipient.
data_recipient_global_metastore_id	string	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__.
metastore_id	string	Unique identifier of recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
activated	boolean
activation_url	string	Full activation url to retrieve the access token. It will be empty if the token is already retrieved.
authentication_type	string	The delta sharing authentication type. (DATABRICKS, OAUTH_CLIENT_CREDENTIALS, OIDC_FEDERATION, TOKEN)
cloud	string	Cloud vendor of the recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
comment	string	Description about the recipient.
created_at	integer	Time at which this recipient was created, in epoch milliseconds.
created_by	string	Username of recipient creator.
expiration_time	integer	Expiration timestamp of the token, in epoch milliseconds.
▶ip_access_list	object	IP Access List
owner	string	Username of the recipient owner.
▶properties_kvpairs	object	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.
region	string	Cloud region of the recipient's Unity Catalog Metastore. This field is only present when the __authentication_type__ is **DATABRICKS**.
sharing_code	string	The one-time sharing code provided by the data recipient. This field is only present when the __authentication_type__ is **DATABRICKS**.
▶tokens	array	This field is only present when the __authentication_type__ is **TOKEN**.
updated_at	integer	Time at which the recipient was updated, in epoch milliseconds.
updated_by	string	Username of recipient updater.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	name, deployment_name		Gets a share recipient from the metastore. The caller must be one of: * A user with USE_RECIPIENT
list	select	deployment_name	data_recipient_global_metastore_id, max_results, page_token	Gets an array of all share recipients within the current metastore where:
rotate_token	insert	name, deployment_name, existing_token_expire_in_seconds		Refreshes the specified recipient's delta sharing authentication token with the provided token info.
create	insert	deployment_name, name, authentication_type		Creates a new recipient with the delta sharing authentication type in the metastore. The caller must
update	update	name, deployment_name		Updates an existing recipient in the metastore. The caller must be a metastore admin or the owner of
delete	delete	name, deployment_name		Deletes the specified recipient from the metastore. The caller must be the owner of the recipient.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
name	string	Name of the recipient.
data_recipient_global_metastore_id	string	If not provided, all recipients will be returned. If no recipients exist with this ID, no results will be returned.
max_results	integer	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_token	string	Opaque pagination token to go to next page based on previous query.

SELECT examples

get

Gets a share recipient from the metastore. The caller must be one of: * A user with USE_RECIPIENT

SELECT
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
authentication_type,
cloud,
comment,
created_at,
created_by,
expiration_time,
ip_access_list,
owner,
properties_kvpairs,
region,
sharing_code,
tokens,
updated_at,
updated_by
FROM databricks_workspace.sharing.recipients
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

list

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

SELECT
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
authentication_type,
cloud,
comment,
created_at,
created_by,
expiration_time,
ip_access_list,
owner,
properties_kvpairs,
region,
sharing_code,
tokens,
updated_at,
updated_by
FROM databricks_workspace.sharing.recipients
WHERE deployment_name = '{{ deployment_name }}' -- required
AND data_recipient_global_metastore_id = '{{ data_recipient_global_metastore_id }}'
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;

INSERT examples

rotate_token

Refreshes the specified recipient's delta sharing authentication token with the provided token info.

INSERT INTO databricks_workspace.sharing.recipients (
existing_token_expire_in_seconds,
name,
deployment_name
)
SELECT 
{{ existing_token_expire_in_seconds }} /* required */,
'{{ name }}',
'{{ deployment_name }}'
RETURNING
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
authentication_type,
cloud,
comment,
created_at,
created_by,
expiration_time,
ip_access_list,
owner,
properties_kvpairs,
region,
sharing_code,
tokens,
updated_at,
updated_by
;

create

Creates a new recipient with the delta sharing authentication type in the metastore. The caller must

INSERT INTO databricks_workspace.sharing.recipients (
name,
authentication_type,
comment,
data_recipient_global_metastore_id,
expiration_time,
id,
ip_access_list,
owner,
properties_kvpairs,
sharing_code,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ authentication_type }}' /* required */,
'{{ comment }}',
'{{ data_recipient_global_metastore_id }}',
{{ expiration_time }},
'{{ id }}',
'{{ ip_access_list }}',
'{{ owner }}',
'{{ properties_kvpairs }}',
'{{ sharing_code }}',
'{{ deployment_name }}'
RETURNING
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
authentication_type,
cloud,
comment,
created_at,
created_by,
expiration_time,
ip_access_list,
owner,
properties_kvpairs,
region,
sharing_code,
tokens,
updated_at,
updated_by
;

Manifest

# Description fields are for documentation purposes
- name: recipients
props:
  - name: name
    value: "{{ name }}"
    description: Required parameter for the recipients resource.
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the recipients resource.
  - name: existing_token_expire_in_seconds
    value: {{ existing_token_expire_in_seconds }}
    description: |
      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.
  - name: name
    value: "{{ name }}"
    description: |
      Name of Recipient.
  - name: authentication_type
    value: "{{ authentication_type }}"
    description: |
      :param comment: str (optional) Description about the recipient.
  - name: comment
    value: "{{ comment }}"
  - name: data_recipient_global_metastore_id
    value: "{{ data_recipient_global_metastore_id }}"
    description: |
      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__.
  - name: expiration_time
    value: {{ expiration_time }}
    description: |
      Expiration timestamp of the token, in epoch milliseconds.
  - name: id
    value: "{{ id }}"
    description: |
      [Create,Update:IGN] common - id of the recipient
  - name: ip_access_list
    description: |
      IP Access List
    value:
      allowed_ip_addresses:
        - "{{ allowed_ip_addresses }}"
  - name: owner
    value: "{{ owner }}"
    description: |
      Username of the recipient owner.
  - name: properties_kvpairs
    description: |
      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.
    value:
      properties: "{{ properties }}"
  - name: sharing_code
    value: "{{ sharing_code }}"
    description: |
      The one-time sharing code provided by the data recipient. This field is only present when the __authentication_type__ is **DATABRICKS**.

UPDATE examples

update

Updates an existing recipient in the metastore. The caller must be a metastore admin or the owner of

UPDATE databricks_workspace.sharing.recipients
SET 
comment = '{{ comment }}',
expiration_time = {{ expiration_time }},
id = '{{ id }}',
ip_access_list = '{{ ip_access_list }}',
new_name = '{{ new_name }}',
owner = '{{ owner }}',
properties_kvpairs = '{{ properties_kvpairs }}'
WHERE 
name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
authentication_type,
cloud,
comment,
created_at,
created_by,
expiration_time,
ip_access_list,
owner,
properties_kvpairs,
region,
sharing_code,
tokens,
updated_at,
updated_by;

DELETE examples

delete

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

DELETE FROM databricks_workspace.sharing.recipients
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
;