Delta Sharing (Databricks-to-Databricks共有) のデータ受信者を作成および管理する

この記事では、Delta Sharing で受信者を作成および管理する方法について説明します (受信者が Unity Catalog が有効になっている Databricks ワークスペース上にあります)。

受信者は、共有データを使用する現実世界のユーザーまたはユーザーグループの ID を表す名前付きオブジェクトです。 受信者の作成方法は、 受信者が Unity Catalog が有効になっている Databricks ワークスペースにアクセスできるかどうかによって異なります。

• Unity Catalog が有効になっている Databricks ワークスペースにアクセスできる受信者の場合は、Databricks によって完全に管理されるセキュリティで保護された接続を使用して受信者オブジェクトを作成できます。この共有モードは Databricks-to-Databricks 共有 と呼ばれ、この記事で説明されています。
• Databricksが有効になっている ワークスペースにアクセスできない受信者は、トークンベースの認証Unity Catalog (ベアラー トークンまたはOAuth フェデレーション) を使用して管理するセキュリティで保護された接続で 、オープン共有 を使用する必要があります。オープン共有受信者の作成に関する情報については、「 Open ID Connect (OIDC) フェデレーションを使用して Delta Sharing 共有の認証を有効にする (オープン共有)」 および「 ベアラー トークンを使用して非Databricks ユーザー用の受信者オブジェクトを作成する (オープン共有)」を参照してください。

これら 2 つの共有モードの詳細と、どちらを選択するかについては、「 オープン共有と Databricks-to-Databricks 共有」を参照してください。

必要条件

受取人を作成するには：

• メタストア管理者であるか、共有するデータが登録されている Unity Catalog メタストアの CREATE_RECIPIENT 特権を持っている必要があります。
• 受信者は、その Unity Catalog メタストアがアタッチされている Databricks ワークスペースを使用して作成する必要があります。
• Databricks ノートブックを使用して受信者を作成する場合、コンピュートは Databricks Runtime 11.3 LTS 以降を使用し、標準または専用アクセス モード (以前の共有およびシングル ユーザー アクセス モード) を使用する必要があります。

その他の受信者管理操作（共有の表示、削除、更新、受信者へのアクセス権の付与など）については、この記事の操作固有のセクションに記載されている権限要件を参照してください。

Databricksへのアクセス権を持つユーザーの受信者オブジェクトを作成する(Databricks-to-Databricks共有)

データ受信者が Unity Catalog に対して有効になっている Databricks ワークスペースにアクセスできる場合は、認証の種類が DATABRICKSの受信者オブジェクトを作成できます。

認証の種類が DATABRICKS の受信者オブジェクトは、特定の Unity Catalog メタストア上のデータ受信者を表し、受信者オブジェクト定義では、メタストアのクラウド、リージョン、UUID で構成される 共有識別子 文字列によって識別されます。 この受信者と共有されるデータには、そのメタストアでのみアクセスできます。

ステップ1: 受取人の共有識別子をリクエストしてください

受信者のユーザーに対して、受信者のユーザーまたはユーザーのグループが共有データを操作するワークスペースにアタッチされている Unity Catalog メタストアの共有識別子を送信するように依頼します。

共有識別子は、メタストアのクラウド、リージョン、UUID (メタストアの一意の識別子) で構成される文字列で、 <cloud>:<region>:<uuid>.

たとえば、次のスクリーンショットでは、完全な共有識別子文字列は aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016です。

受信者は、使用するワークスペースの Unity-Catalog 対応コンピュートで実行される ノートブックまたは クエリの Catalog Explorer、DatabricksUnity CatalogCLI 、または デフォルトSQL 関数 を使用して識別子を見つけることができます。CURRENT_METASTOREDatabricksDatabricks SQL

Catalog Explorer

To get the sharing identifier using Catalog Explorer:

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared with me tab, click your Databricks sharing organization name in the upper right, and select Copy sharing identifier.

SQL

Run the following command in a notebook or the Databricks SQL query editor:

SQL

SELECT CURRENT_METASTORE();

CLI

Run the following command using the Databricks CLI. The sharing identifier is returned as the global_metastore_id.

Bash

databricks metastores summary

この手順に含まれる情報を連絡先に送信することで受信者を支援するか、Databricks-to-Databricksモデルで [アクセスを取得する] に向けることができます。

ステップ 2: 受信者を作成する

Databricks-to-Databricks共有の受信者を作成するには、カタログ エクスプローラー、DatabricksUnity CatalogCLI 、またはCREATE RECIPIENTSQL DatabricksノートブックまたはDatabricks SQL クエリ エディターの コマンドを使用できます。

必要なアクセス許可 : メタストア管理者、または共有するデータが登録されている Unity Catalog メタストアの CREATE_RECIPIENT 権限を持つユーザー。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click New recipient.

4. Enter the Recipient name.

5. For Recipient type, select Databricks.

6. Enter the recipient's Sharing identifier.

   Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

7. (Optional) Enter a comment.

8. Click Create.

9. (Optional) Create custom Recipient properties.

   On the recipient Overview tab, click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

SQL

Run the following command in a notebook or the Databricks SQL query editor:

SQL

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
USING ID '<sharing-identifier>'
[COMMENT "<comment>"];

Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

You can also add custom properties for the recipient. For details, see Manage recipient properties.

CLI

Run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.
• <sharing-identifier>: The entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.
• <authentication-type>: Set to DATABRICKS when a sharing identifier string in the format <cloud>:<region>:<uuid> is provided for <sharing-identifier>.

Bash

databricks recipients create <recipient-name> <authentication-type> --sharing-code <sharing-identifier>

You can also add custom properties for the recipient. For details, see Manage recipient properties.

受信者は DATABRICKSのauthentication_typeで作成されます。

受信者に共有へのアクセス権を付与する

受信者を作成し、 共有を作成したら、その共有へのアクセス権を受信者に付与できます。

受信者に共有アクセス権を付与するには、Catalog Explorer、Databricks Unity Catalog CLI、または Databricks ノートブックまたは Databricks SQL クエリエディターの GRANT ON SHARE SQL コマンドを使用できます。

必要な権限 : 次のいずれかです。

• メタストア管理者。
• 共有オブジェクトと受信者オブジェクト ((USE SHARE + SET SHARE PERMISSION) または共有の所有者) および (USE RECIPIENT または受信者の所有者) の両方に対する委任されたアクセス許可または所有権。

手順については、「 Delta Sharing データ共有へのアクセスを管理する (プロバイダー向け)」を参照してください。

受信者を表示する

受信者のリストを表示するには、カタログ エクスプローラー、DatabricksUnity CatalogCLI 、またはSHOW RECIPIENTSSQL DatabricksノートブックまたはDatabricks SQL クエリ エディターの コマンドを使用できます。

必要なアクセス許可 : メタストア管理者であるか、メタストア内のすべての受信者を表示するための USE RECIPIENT 特権を持っている必要があります。 他のユーザーは、自分が所有する受信者にのみアクセスできます。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients.

SQL

Run the following command in a notebook or the Databricks SQL query editor. Optionally, replace <pattern> with a LIKE predicate.

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients list

受信者の詳細を表示する

受信者の詳細を表示するには、Catalog Explorer、Databricks Unity Catalog CLI、または Databricks ノートブックまたは Databricks SQL クエリエディターの DESCRIBE RECIPIENT SQL コマンドを使用できます。

必要な権限 : メタストア管理者、 USE RECIPIENT 権限を持つユーザー、または受信者オブジェクトの所有者。

詳細は次のとおりです。

• 受信者の作成者、作成タイムスタンプ、コメント、および認証タイプ(TOKEN または DATABRICKS)。
• 受信者がオープン共有を使用している場合: トークンの有効期間、アクティベーション リンク、アクティベーション ステータス (資格情報がダウンロードされたかどうか)、IP アクセス リスト (割り当てられている場合)。
• 受信者が Databricks 間の共有を使用している場合: 受信者の Unity Catalog メタストアのクラウド、リージョン、メタストア ID、およびアクティベーションの状態。
• 受信者のプロパティ (カスタム プロパティを含む)。 受取人のプロパティの管理を参照してください。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

DESCRIBE RECIPIENT <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients get <recipient-name>

受信者の共有権限を表示する

受信者にアクセス権が付与されている共有の一覧を表示するには、Catalog Explorer、Databricks CLI、または Databricks ノートブックまたは Databricks SQL クエリ エディターの SHOW GRANTS TO RECIPIENT SQL コマンドを使用できます。

必要な権限 : メタストア管理者、 USE RECIPIENT 権限を持つユーザー、または受信者オブジェクトの所有者。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. Go to the Shares tab to view the list of shares shared with the recipient.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients share-permissions <recipient-name>

受信者を更新する

受信者を更新するには、カタログエクスプローラー、DatabricksUnity CatalogCLI ALTER RECIPIENTSQL、Databricks ノートブックの コマンド、またはDatabricks SQL クエリエディターを使用できます。

更新できるプロパティには、受信者名、所有者、コメント、およびカスタム プロパティが含まれます。

必要なアクセス許可 : 所有者を更新するには、受信者オブジェクトのメタストア管理者または所有者である必要があります。 名前を更新するには、メタストア管理者 (または CREATE_RECIPIENT 権限を持つユーザー) であり 、所有者である必要があります。 コメントまたはカスタムプロパティを更新するには、所有者である必要があります。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. On the recipient details page:

   • Update the owner.

   • Edit or add a comment.

   • Rename the recipient.

     Click the kebab menu and select Rename.

   • Edit, remove, or add custom Recipient properties.

     Click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

   • Token-authenticated recipients only:

     • View and copy the Authentication link. See Get the activation link
     • Under Token Management, rotate or update the bearer token. See Manage recipient tokens.

   • OIDC federated recipients only:

     • Under OIDC federation policies, click Add policies. See LINK.
     • View and copy Recipient endpoint and Recipient MTLS endpoint.

SQL

Run one or more of the following commands in a notebook or the Databricks SQL query editor.

SQL

ALTER RECIPIENT <recipient-name> RENAME TO <new-recipient-name>;

ALTER RECIPIENT <recipient-name> OWNER TO <new-owner>;

COMMENT ON RECIPIENT <recipient-name> IS "<new-comment>";

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( <property-key>  =  property_value [, ...] )

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( <property-key> [, ...] )

For more information about properties, see Manage recipient properties.

CLI

Create a JSON file that includes an update to the recipient name, comment, owner, IP access list, or custom properties.

JSON

{
  "name": "new-recipient-name",
  "owner": "someone-else@example.com",
  "comment": "something new",
  "ip_access_list": {
    "allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
  },
  "property": {
    "country": "us",
    "id": "001"
  }
}

Then run the following command using the Databricks CLI. Replace <recipient-name> with the current recipient name and replace update-recipient-settings.json with the filename of the JSON file.

Bash

databricks recipients update --json-file update-recipient-settings.json

For more information about properties, see Manage recipient properties.

（オプション）アクセスリストを使用して受信者のアクセスを制限します

受信者オブジェクトを設定するときに、受信者のアクセスを制限した IP アドレスのセットに制限できます。 「IP アクセス リストを使用して Delta Sharing 受信者のアクセスを制限する (オープン共有)」を参照してください。

受取人のプロパティを管理します

受信者オブジェクトには、データ共有アクセスを絞り込むために使用できる定義済みのプロパティが含まれています。 たとえば、これらを使用して次の操作を実行できます。

• 異なるテーブルパーティションを異なる受信者と共有することで、複数の受信者と同じ共有を使用しながら、それらの受信者間のデータ境界を維持できます。
• 受信者のプロパティに基づいて、受信者がテーブルデータにアクセスするのを行または列レベルで制限する動的ビューを共有します。

カスタムプロパティを作成することもできます。

定義済みのプロパティは databricks. で始まり、次のものが含まれます。

• databricks.accountId:データ受信者が所属する Databricks アカウント(Databricks-to-Databricks 共有のみ)。
• databricks.metastoreId: データ受信者が属する Unity Catalog メタストア (Databricks間共有のみ)。
• databricks.name: データ受信者の名前。

価値がある可能性のあるカスタム プロパティには、たとえば、 countryなどがあります。 たとえば、カスタムプロパティ [ 'country' = 'us' ] を受信者にアタッチすると、テーブルデータを国ごとにパーティション分割し、米国のデータを含む行のみを、そのプロパティが割り当てられている受信者と共有できます。 また、受信者のプロパティに基づいて行または列へのアクセスを制限する動的ビューを共有することもできます。 詳細な例については、「 受信者のプロパティを使用してパーティションのフィルター処理を行う 」および「 共有に動的ビューを追加して行と列をフィルター処理する」を参照してください。

必要条件

受信者のプロパティは、Databricks Runtime 12.2 以降でサポートされています。

受信者を作成または更新するときにプロパティを追加する

受信者を作成するとき、または既存の受信者に対してプロパティを更新するときに、プロパティを追加できます。 カタログ エクスプローラ、 Databricks Unity Catalog CLI、または SQL コマンドは、 Databricks ノートブックまたは Databricks SQL クエリ エディタで使用できます。

必要なアクセス許可 : メタストア管理者、または Unity Catalog メタストアの CREATE RECIPIENT 権限を持つユーザー。

Catalog Explorer

When you create or update a recipient using Catalog Explorer, add or update custom properties by doing the following:

1. Go to the Recipient details page.

   If you are creating a new recipient, you land on this page after you click Create. If you are updating an existing recipient, go to this page by clicking the gear icon > Delta Sharing > Shared by me > Recipients and selecting the recipient.

2. Click Edit properties > +Add property.

3. Enter a property name (Key) and Value.

   For example, if you want to filter shared data by country and share only US data with this recipient, you can create a key named “country” with a value of “US.”

4. Click Save.

SQL

To add a custom property when you create a recipient, run the following command in a notebook or the Databricks SQL query editor:

SQL

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[USING ID '<sharing-identifier>'] /* Skip this if you are using open sharing */
[COMMENT "<comment>"]
PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

<property-key> can be a string literal or identifier. <property-value> must be a string literal.

For example:

SQL

CREATE RECIPIENT acme PROPERTIES ('country' = 'us', 'partner_id' = '001');

To add, edit, or delete custom properties for an existing recipient, run one of the following:

SQL

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( '<property-key>' );

CLI

To add custom properties when you create a recipient, run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.
• <property-key> can be a string literal or identifier.
• <property-value> must be a string literal.

Bash

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "<property-key>": "<property-value>",
    }
  }
}'

For example:

Bash

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "partner_id":"001"
    }
  }
}'

To add or edit custom properties for an existing recipient, use update instead of create:

Bash

databricks recipients update \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "partner_id":"001"
    }
  }
}'

受信者のプロパティを表示する

受取人のプロパティを表示するには、「受取人の詳細を表示する」の指示に従ってください。

受取人を削除する

受信者を削除するには、カタログ エクスプローラー、DatabricksUnity CatalogCLI 、またはDROP RECIPIENTSQL DatabricksノートブックまたはDatabricks SQL クエリ エディターの コマンドを使用できます。受信者を削除するには、受信者オブジェクトの所有者である必要があります。

受信者を削除すると、受信者が代表するユーザーは共有データにアクセスできなくなります。 受信者がオープン共有シナリオで使用するトークンは無効になります。

必要な権限 : 受信者オブジェクトの所有者。

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. On the Recipients tab, find and select the recipient.

5. Click the kebab menu and select Delete.

6. On the confirmation dialog, click Delete.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

DROP RECIPIENT [IF EXISTS] <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients delete <recipient-name>