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.
allowed_acceptance_types	array	Authentication types the invitee may choose from when activating. Each value must be TOKEN or DATABRICKS. Empty means all supported types are allowed. This field is only present when the **authentication_type** is **EMAIL**.
allowed_data_recipient_global_metastore_ids	array	Optional allowlist of the data recipient's global metastore IDs permitted to accept the invite with the DATABRICKS acceptance type. Each ID is of the form **cloud**:**region**:**metastore-uuid**. Empty means any metastore is allowed. If non-empty, **allowed_acceptance_types** must include **DATABRICKS**. This field is only present when the **authentication_type** is **EMAIL**.
authentication_type	string	The delta sharing authentication type. (DATABRICKS, EMAIL, 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.
email	string	The invited email address. This field is only present when the **authentication_type** is **EMAIL**. The 320-character cap follows RFC 5321 (64-octet local-part + ``@`` + 255-octet domain).
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.
allowed_acceptance_types	array	Authentication types the invitee may choose from when activating. Each value must be TOKEN or DATABRICKS. Empty means all supported types are allowed. This field is only present when the **authentication_type** is **EMAIL**.
allowed_data_recipient_global_metastore_ids	array	Optional allowlist of the data recipient's global metastore IDs permitted to accept the invite with the DATABRICKS acceptance type. Each ID is of the form **cloud**:**region**:**metastore-uuid**. Empty means any metastore is allowed. If non-empty, **allowed_acceptance_types** must include **DATABRICKS**. This field is only present when the **authentication_type** is **EMAIL**.
authentication_type	string	The delta sharing authentication type. (DATABRICKS, EMAIL, 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.
email	string	The invited email address. This field is only present when the **authentication_type** is **EMAIL**. The 320-character cap follows RFC 5321 (64-octet local-part + ``@`` + 255-octet domain).
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:
list	select	deployment_name	data_recipient_global_metastore_id, max_results, page_token, parent_recipient_name	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.
parent_recipient_name	string	If set, the response is scoped to the child recipients of the named parent recipient. Child recipients are otherwise hidden from the default list response. Only applicable to email recipient parents — non-email recipients have no children to scope to.

SELECT examples

get

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

SELECT
id,
name,
data_recipient_global_metastore_id,
metastore_id,
activated,
activation_url,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
authentication_type,
cloud,
comment,
created_at,
created_by,
email,
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,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
authentication_type,
cloud,
comment,
created_at,
created_by,
email,
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 }}'
AND parent_recipient_name = '{{ parent_recipient_name }}'
;

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,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
authentication_type,
cloud,
comment,
created_at,
created_by,
email,
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,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
comment,
data_recipient_global_metastore_id,
email,
expiration_time,
id,
ip_access_list,
owner,
properties_kvpairs,
sharing_code,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ authentication_type }}' /* required */,
'{{ allowed_acceptance_types }}',
'{{ allowed_data_recipient_global_metastore_ids }}',
'{{ comment }}',
'{{ data_recipient_global_metastore_id }}',
'{{ email }}',
{{ 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,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
authentication_type,
cloud,
comment,
created_at,
created_by,
email,
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: |
      The delta sharing authentication type.
  - name: allowed_acceptance_types
    value:
      - "{{ allowed_acceptance_types }}"
    description: |
      Authentication types the invitee may choose from when activating. Each value must be TOKEN or DATABRICKS. Empty means all supported types are allowed. This field is only present when the **authentication_type** is **EMAIL**.
  - name: allowed_data_recipient_global_metastore_ids
    value:
      - "{{ allowed_data_recipient_global_metastore_ids }}"
    description: |
      Optional allowlist of the data recipient's global metastore IDs permitted to accept the invite with the DATABRICKS acceptance type. Each ID is of the form **cloud**:**region**:**metastore-uuid**. Empty means any metastore is allowed. If non-empty, **allowed_acceptance_types** must include **DATABRICKS**. This field is only present when the **authentication_type** is **EMAIL**.
  - name: comment
    value: "{{ comment }}"
    description: |
      Description about the recipient.
  - 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: email
    value: "{{ email }}"
    description: |
      The invited email address. This field is only present when the **authentication_type** is **EMAIL**. The 320-character cap follows RFC 5321 (64-octet local-part + ``@`` + 255-octet domain).
  - 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 
allowed_acceptance_types = '{{ allowed_acceptance_types }}',
allowed_data_recipient_global_metastore_ids = '{{ allowed_data_recipient_global_metastore_ids }}',
comment = '{{ comment }}',
email = '{{ email }}',
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,
allowed_acceptance_types,
allowed_data_recipient_global_metastore_ids,
authentication_type,
cloud,
comment,
created_at,
created_by,
email,
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
;