Delta Sharingによるデータ共有

[Share data using Delta Sharing \| Databricks on AWS](https://docs.databricks.com/data-sharing/delta-sharing/index.html) [2022/8/25時点]の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

本書では、皆様の組織外のデータ受信者とUnity Catalogのデータをどのように共有するのかを説明します。あなたがデータ受信者であれば、[Delta Sharingを用いて共有データにアクセスする](https://qiita.com/taka_yayoi/items/f45b77984c3ed4b6a0c0)をご覧ください。

# Delta Sharingはどのように動作するのか？

[Delta Sharing](https://delta.io/sharing)はDatabricksによって開発された、どのような計算プラットフォームを使っているのかに関係なく他の企業とデータを共有するためのセキュアなオープンプロトコルです。「データ提供者(data provider)」と呼ばれるDatabricksユーザーは、「データ受領者(data recipient)」と呼ばれる組織外の個人、グループとデータを共有するためにDelta Sharingを使用することができます。データ受領者は即時に最新バージョンの共有データで作業をスタートすることができます。コネクターの完全なリスト、どのように使用するのかの情報に関しては、[Delta Sharing](https://delta.io/sharing)のドキュメントを参照ください。メタストア上でDelta Sharingが有効化されると、Unity CatalogがDelta Sharingサーバーを実行します。
![](https://docs.databricks.com/_images/architecture.png)

共有データはDatabricksから直接提供されるのではなく、Databricksが稼働しているデータプロバイダーによって提供されます。

:::note info
**注意**
データ提供者の共有データに対してデータ受領者としてアクセスすることで、データ受領者はデータ提供者によって提供されっるデータ共有にアクセスすることを承認され、(1)データ受領者がそのような共有データを使用することに対して、Databricksがいかなる責任を持たないこと、(2)Databricksがデータ受領者が共有データを使用し、アクセスすることに関する情報(そのようなデータに紐づけられる認証情報ファイルを用いてデータにアクセスしたいかなる個人、企業を含みます)を収集する可能性があり、適切なデータ提供者に共有される可能性があることを許諾したとみなされます。
:::

# 共有と受信者

Delta Sharingでは、*共有(share)* は1つ以上の受信者と共有されるテーブルあるいはテーブルのパーティションの読み取り専用のコレクションとなります。メタストアでは複数の共有を持つことができ、それぞれの共有にどの受信者がアクセスできるのかを制御することができます。単一のメタストアには複数の共有を含めることができますが、それぞれの共有は一つのメタストアにしか所属することができません。共有を削除すると、その共有のすべての受信者は共有にアクセスできなくなります。

*受信者(recipient)* は1つ以上の共有にアクセスすることを今日に許可する資格情報を伴って企業に関連づけられるオブジェクトです。受信者を作成すると、その受信者にダウンロード可能な資格情報が生成されます。それぞれのメタストアでは複数の受信者を作成することができますが、それぞれの受信者は一つのメタストアにのみ所属することができます。受信者は複数の共有にアクセスすることができます。受信者を削除すると、当該受信者はこれまで与えられていた共有へのアクセスを失います。

共有と受信者は互いに独立に存在します。
![](https://docs.databricks.com/_images/shares-and-recipients.png)

# どのように管理者は受信者のアクセスを許可するのか？

受信者に共有のアクセスを許可するには、以下を実行します。

1. アカウント管理者として、お使いのDatabricksアカウントで[外部データ共有機能グループを有効化](#お使いのアカウントで外部データ共有機能グループを有効化する)します。
    1. アカウント管理者として、[それぞれのUnity CatalogメタストアのDelta Sharingを有効化](#メタストアでdelta-sharingを有効化する)します。
    1. メタストア管理者あるいはアカウント管理者として、メタストアの1つ以上のテーブルと関連づけられる[共有を作成](#共有を作成する)します。
    1. [受信者を作成](#受領者を作成する)します。一連の資格情報が受信者ごとに作成されます。
    1. 1つ以上の共有に対して[受信者の権限を許可](#受領者を作成する)します。
    1. セキュアなチャネルを用いて、受信者が資格情報をダウンロードできるようにアクティベーションリンクを受信者に送信します。
    1. 受信者は[共有にアクセス](https://qiita.com/taka_yayoi/items/f45b77984c3ed4b6a0c0)するために資格情報を使用します。

以下のセクションでは、どのようにDatabricksアカウントでDelta Sharingを有効化するのか、Unity Catalogメタストア上でDelta Sharingを有効化するのか、共有と受信者を管理し、Delta Sharingのアクティビティを監査するのかを説明します。

# 要件

- Unity Catalogが有効化され、少なくとも一つのメタストアが存在している必要があります。
- アカウント管理者のみがメタストアでDelta Sharingを有効化することができます。
- メタストア管理者あるいはアカウント管理者のみがDelta Sharingを用いてデータを共有することができます。[メタストア管理者](https://qiita.com/taka_yayoi/items/065706136dcd2ad9df33#%E3%83%A1%E3%82%BF%E3%82%B9%E3%83%88%E3%82%A2%E7%AE%A1%E7%90%86%E8%80%85)をご覧ください。
- データ受領者の認証情報をローテーションするには、Unity Catalog CLIを使用する必要があります。[(オプション)Unity Catalog CLIのインストール](https://qiita.com/taka_yayoi/items/3f2df6ddea81521ee786#%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3unity-catalog-cli%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)をご覧ください。
- 共有と受領者を管理するには、Data Science & Engineeringノートブック、あるいはDatabricks SQLのクエリーを使用します。

# お使いのアカウントで外部データ共有機能グループを有効化する

外部の受信者とDelta Sharingを使用するには、アカウント管理者はお使いのDatabricksアカウントで外部データ共有機能グループ(External Data Sharing feature group)を有効化する必要があります。

1. Databricksアカウント管理者として、[Account Console](https://accounts.cloud.databricks.com/login)にログインします。
1. サイドバーで![](https://docs.databricks.com/_images/settings-icon.png)**Settings**をクリックします。
1. **Feature enablement**タブに移動します。
1. **External Data Sharing Feature Group**行で**Enable**ボタンをクリックします。

    Delta Sharingに適用される**Terms**リンクをクリックして確認します。これらの状況を受け入れることを意思表示するために**Enable**をクリックします。

# メタストアでDelta Sharingを有効化する

Delta Sharingを使用してデータを共有する予定のある、それぞれのメタストアで以下のステップを実行します。

1. [アカウントコンソール](https://accounts.cloud.databricks.com/)にログインします。
1. サイドバーで![](https://docs.databricks.com/_images/data-icon.png)**Data**をクリックします。
1. メタストアの名前をクリックし、詳細を開きます。
1. **Enable Delta Sharing and allow a Databricks user to share data outside their organization**の隣のチェックボックスをクリックします。
1. デフォルトの受領者トークンの有効期限を設定することをお勧めします。受領者トークンがこの時間を過ぎると無効化され、再生成が必要となります。この設定をしない場合、受領者トークンの期限は存在しません。

    デフォルトの受領者トークンの有効期限を変更しても、既存の受領者トークンの有効期限は自動では更新されません。特定の受領者の受領者トークンの有効期限を更新するには、[受領者の認証情報をローテーションする](#受領者の認証情報をローテーションする)を参照ください。

    デフォルトの受領者トークンの有効期限を更新するには以下を実施します。

    1. **Set expiration**を有効化します。
    1. 秒、分、時間、日の値を入力し、単位を選択します。
    1. **Enable**をクリックします。

    詳細は[受領者に対する推奨セキュリティ](#受領者に対する推奨セキュリティ)をご覧ください。

1. 利用条項を読み、同意する場合に**Enable**をクリックします。

# (オプション)Unity Catalog CLIをインストールする

共有と受領者を管理するために、SQLコマンドかUnity Catalog CLIを使用することができます。CLIはお使いのローカル環境で実行され、Databricksの計算資源を必要としません。

CLIをインストールするには、Unity Catalogドキュメントの[(オプション)Unity Catalog CLIのインストール](https://qiita.com/taka_yayoi/items/3f2df6ddea81521ee786#%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3unity-catalog-cli%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)をご覧ください。

# 受領者トークンの有効期限を変更する

Delta Sharingが有効化されている際、デフォルトの受領者トークンの有効期限を変更するには以下の手順を踏みます。

:::note info
**注意**
デフォルトの受領者トークンの有効期限を変更しても、既存の受領者トークンの有効期限は自動では更新されません。特定の受領者の受領者トークンの有効期限を更新するには、[受領者の認証情報をローテーションする](#受領者の認証情報をローテーションする)を参照ください。
:::

1. [アカウントコンソール](https://accounts.cloud.databricks.com/)にログインします。
1. サイドバーで![](https://docs.databricks.com/_images/data-icon.png)**Data**をクリックします。
1. メタストアの名前をクリックし、詳細を開きます。
1. **Set expiration**を有効化します。
1. 秒、分、時間、日の値を入力し、単位を選択します。
1. **Enable**をクリックします。

**Set expiration**を無効化すると、受領者トークンは期限切れしなくなります。詳細は[受領者に対する推奨セキュリティ](#受領者に対する推奨セキュリティ)をご覧ください。

# 共有を管理する

Delta Sharingにおいては、グループとして共有したいと考えるメタストアのテーブル、ビューのコレクションを含むオブジェクトを*共有*(share)と呼びます。共有には、1つのメタストアからのみのテーブルを含めることができます。好きな時に共有にテーブルを追加、共有からテーブルを削除することができます。

以下のセクションでは、共有の作成、表示、更新、削除方法を説明します。

## 共有を作成する

共有を作成するには、ノートブックあるいはDatabricks SQLエディタで以下のコマンドを実行します。プレースホルダーの値を置き換えてください。

- `<share_name>`: 共有の名称
- `<comment>`: 共有を説明するコメント

```sql:SQL
CREATE SHARE [IF NOT EXISTS] <share_name> [COMMENT <comment>];
```

共有を説明した後は、[テーブルを追加](#共有に対してテーブルを追加削除する)し、1人以上の[受領者](#受領者の管理)を関連づけることができます。

## 共有を一覧する

全ての共有を表示するには、`SHOW SHARES`コマンドを使用します。

```sql:SQL
SHOW SHARES;
```

## 共有を表示する

共有のメタデータ、共有に関連づけられている全てのテーブルを表示すには、`DESCRIBE SHARE`コマンドを使用します。`<share_name>`を共有名で置き換えてください。

```sql:SQL
DESCRIBE SHARE <share_name>;
```

共有の全てのテーブルを一覧するには、`SHOW ALL IN SHARES`コマンドを使用します。

```sql:SQL
SHOW ALL IN SHARE <share_name>;
```

## 共有に対してテーブルを追加・削除する

以下のコマンドでプレースホルダーを置き換えてください。

- `<share_name>`: 共有名
- `<catalog_name>`: メタストア内のカタログ名
- `<schema_name>`: メタストア内のスキーマ名
- `<table_name>`: 追加するテーブルの名称
- `AS <new_schema_name.<new_table_name>`: (オプション)新たな名称でテーブルを共有
- `<comment>`: 共有を説明するコメント

共有とテーブルを関連づけるには、`ALTER SHARE ADD TABLE`コマンドを使用します。

:::note
**注意**
共有のオーナーは共有するテーブルでの`SELECT`を継続的に維持する必要があります。
:::

```sql:SQL
ALTER SHARE <share_name>
ADD TABLE <catalog_name>.<schema_name>.<table_name>
[COMMENT <comment>];
[deltaSharingPartitionListSpec]
[AS <new_schema_name.<new_table_name>]
[WITH CHANGE DATA FEED];
```

`WITH CHANGE DATA FEED`が指定されると、テーブルはチェンジデータフィードと共に共有され、受信者はバージョンや現在のテーブルバージョンを用いてテーブルデータをクエリーすることができます。

パーティションの共有の詳細については、[パーティションの指定](#パーティションの指定)をご覧下さい。チェンジデータフィードの詳細に関しては、[チェンジデータフィード](https://qiita.com/taka_yayoi/items/e3c40fce43561f73a50c)をご覧ください。

共有からテーブルを削除するには、`ALTER SHARE REMOVE TABLE`コマンドを使用します。

```sql:SQL
ALTER SHARE <share_name> REMOVE TABLE <catalog_name>.<schema_name>.<table_name>;
```

:::note info
**注意**
メタストアで定義されているオリジナルのスキーマ、テーブル名、あるいは共有で定義された名前を指定することができます。
:::

共有にテーブルを追加、共有からテーブルを削除した際、受領者が次回アクセスした際に変更が反映されます。

### パーティションの指定

共有にテーブルを追加する際にテーブルの一部のみを共有するために、パーティションを指定することができます。以下の例では、`year`、`month`、`date`のカラムでパーティションが作成されている`inventory`テーブルのデータの一部を共有する例を示しています。

- 2021年のデータ
- 2020年12月のデータ
- 2019年12月25日のデータ

```sql:SQL
ALTER SHARE share_name
ADD TABLE inventory
PARTITION (year = "2021"),
          (year = "2020", month = "Dec"),
          (year = "2019", month = "Dec", date = "2019-12-25");
```

## 共有を削除する

共有を削除するには、`DROP SHARE`コマンドを使用します。これまで共有されていたデータに受領者はアクセスできなくなります。`<share_name>`を共有名で置き換えてください。

```sql:SQL
DROP SHARE [IF EXISTS] <share_name>;
```

# 受領者の管理

受領者(recipient)はデータを共有したいと考える組織を表現する名前付きの認証情報セットです。このセクションでは、Delta Sharingでどのように受領者を管理するのかを説明します。

## 受領者を作成する

受領者を作成するには`CREATE RECIPIENT`コマンドを使用します。プレースホルダーの値を置き換えてください。

- `<recipient_name>`: 受領者の名称
- `<comment>`: コメント

```sql:SQL
CREATE RECIPIENT [IF NOT EXISTS] <recipient_name> COMMENT <comment>
```

受領者のトークンは、[受領者トークン有効期限](#受領者トークンの有効期限を変更する)が過ぎると無効化されます。詳細は[受領者に対する推奨セキュリティ](#受領者に対する推奨セキュリティ)をご覧ください。

受領者を作成したら以下を実行します。

1. アクティベーションリンクを取得するために[`DESCRIBE`コマンド](#受領者を表示する)を使用します。
1. セキュアな手段で受領者に、[共有データへのアクセス方法を説明しているドキュメント](https://docs.databricks.com/data-sharing/delta-sharing/recipient.html)とアクティベーションリンクを共有します。アクティベーションリンクは一度しかアクセスできません。受領者はダウンロードした認証情報を機密情報として取り扱い、組織外と共有してはいけません。必要であれば、[受領者の認証情報をローテーションする](#受領者の認証情報をローテーションする)ことも可能です。
1. [共有へのアクセスを許可](#受領者のアクセス権を管理する)します。

## 受領者を一覧する

全ての受領者を一覧するには`SHOW RECIPIENTS`コマンドを使用します。オプションとして、`<pattern>`を[`LIKE`述語](https://docs.databricks.com/spark/latest/spark-sql/language-manual/functions/like.html)で置き換えることができます。

```sql:SQL
SHOW RECIPIENTS [LIKE <pattern>];
```

## 受領者を表示する

作成者、作成時刻、トークンの有効期限、アクティベーションリンク、認証情報がダウンロードされたかどうかを含む受領者の詳細を表示するには、`DESCRIBE RECIPIENT`コマンドを使用します。`<recipient_name>`を受領者名で置き換えてください。

```sql:SQL
DESCRIBE RECIPIENT <recipient_name>;
```

受領者のアクセス権を表示するには、[受領者のアクセス権を管理する](#受領者のアクセス権を管理する)を参照ください。

## 受領者を削除する

受領者を削除するには、`DROP RECIPIENT`コマンドを使用します。削除する受領者名で`<recipient_name>`を置き換えてください。受領者を削除すると、認証情報が無効化され、共有を参照することができなくなります。

```sql:SQL
DROP RECIPIENT [IF EXISTS] <recipient_name>
```

## 受領者の認証情報をローテーションする

以下のようなケースにおいては、受領者の認証情報をローテーションし、新たなアクティベーションリンクを作成すべきです。

- 既存の受領者トークンが有効期限切れになりそう。
- 受領者がアクティベーションURLを紛失、あるいは漏洩した。
- 受領者によるダウンロード後に認証情報が破損、損失、あるいは漏洩した。
- メタストアで受領者トークンの有効期限を変更した後に、受領者トークンの有効期限をアップデートする。

1. まだ実施していないのであれば、[Unity Catalog CLIをインストール](https://qiita.com/taka_yayoi/items/3f2df6ddea81521ee786#%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3unity-catalog-cli%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)します。
1. Unity Catalog CLIを用いて以下のコマンドを実行します。括弧内の引数はオプションです。以下のプレースホルダーを置き換えてください。
    - `<recipient_name>`: 受領者名
    - `<expiration_seconds>`: オプション。既存の受領者トークンが期限切れになるまでの秒数。この期間は、既存のトークンは動作します。値に`0`を指定すると既存のトークンは即座に無効化されます。 

    ```sh:Shell
    uc rotate-recipient-token \
      --name <recipient_name> \
      [--existing-token-expire-in-seconds <expiration_seconds>]
    ```

1. `DESCRIBE RECIPIENT <recipient_name>`コマンドを使ってアクティベーションURLを確認し、セキュアな手段で受領者に共有します。

# 受領者のアクセス権を管理する

共有と受領者を作成したら、受領者が共有にアクセスすることを許可するために`GRANT`と`REVOKE`文を使用します。以下の例では、プレースホルダーを置き換えてください。

- `<share_name>`: 共有の名称
- `<recipient_name>`: 受領者の名称

共有の全てのアクセス権を表示するには以下を実行します。

```sql:SQL
SHOW GRANT ON SHARE <share_name>;
```

ある受領者のアクセス権を表示するには以下を実行します。

```sql:SQL
SHOW GRANT TO RECIPIENT <recipient_name>;
```

アクセスを許可するには以下を実行します。

```sql:SQL
GRANT SELECT
ON SHARE <share_name>
TO RECIPIENT <recipient_name>;
```

アクセスを剥奪するには以下を実行します。

```sql:SQL
REVOKE SELECT
ON SHARE <share_name>
FROM RECIPIENT <recipient_name>;
```

:::note info
**注意**
`SELECT`が共有に対して許可できる唯一のアクセス権です。
:::

## 受領者に対する推奨セキュリティ

[Delta Sharingを有効化](#メタストアでdelta-sharingを有効化する)した際には、受領者の認証情報に対するトークンの有効期限を設定します。トークンの有効期限を`0`に設定すると、受領者のトークンは有効期限切れになりません。トークンが有効期限切れになるように設定することをお勧めします。

以下の状況では、受領者の認証情報をローテーションすべきです。

- 既存の受領者トークンが有効期限切れになりそうな時。
- [受領者トークンの有効期限を変更](#受領者トークンの有効期限を変更する)し、既存の受領者に対して新たな有効期限を適用したい時。
- 受領者が自身のアクティベーションURLを紛失、あるいは漏洩した時。
- [受領者トークンの有効期限を変更](#受領者トークンの有効期限を変更する)した後に、受信者のトークンの有効期限を更新したい時。

任意のタイミングで、受領者は最大2つのトークンを持つ場合があります。アクティブなトークンとローテーションされたトークンです。ローテーションされたトークンが期限切れになるまで、再度トークンをローテーションしようとするとエラーになります。

受領者の認証除法をローテーションする際には、オプションで既存の受領者トークンが無効化されるまでの秒数を`--existing-token-expire-in-seconds`で指定することができます。この値を`0`に設定すると、既存の受領者トークンは即座に無効化されます。

受領者が2つのアクティブなトークンを持つ時間を最小にしつつも、受領者の組織に新たなアクティベーションURLにアクセスするための比較的短い期間に`--existing-token-expire-in-seconds`を設定することをお勧めします。受領者のトークンの漏洩が疑われる場合には、既存のトークンを即座に無効化することをお勧めします。

全ての受領者トークンが有効期限切れになると、受領者のローテーションは既存のアクティベーションURLを新たなものに置き換えます。トークンの有効期限が切れた受領者を、即座にローテーションするか削除することをお勧めします。

受領者のアクティベーションリンクを誤って間違った方に送信するか、セキュアで無いチャネルで送信してしまった場合、以下を実施することをお勧めします。

1. [共有に対する受領者のアクセス権を剥奪します](#受領者のアクセス権を管理する)。
1. 受領者をローテーションし、`--existing-token-expire-in-seconds`を`0`に設定します。
1. 意図した受領者にセキュアなチャネル経由で新たなアクティベーションリンクを共有します。
1. アクティベーションURLにアクセスされた後で、受領者の共有に対するアクセスを再度許可します。

極端なケースにおいては、受領者を[削除](#受領者を削除する)し、再作成することをお勧めします。

# Delta Sharingのリソースに対するアクセスとアクティビティの監査

[監査ログを設定](https://docs.databricks.com/administration-guide/account-settings/audit-logs.html)した後は、Delta Sharingは監査ログに、いつ誰が共有・受領者を作成、変更、アップデート、削除したのか、受領者がいつアクティベーションリンクにアクセスしたのか、認証情報をダウンロードしたのか、受領者の認証情報がいつローテーションされたのか、期限切れになったのかを記録します。Delta Sharingのアクティビティはアカウントログレベルで記録されます。

1. お使いのアカウントで[監査ログを有効化](https://docs.databricks.com/administration-guide/account-settings/audit-logs.html)します。

    :::note warn 
    **重要**
    Delta Sharingのアクティビティはアカウントレベルで記録されます。`workspace_ids_filter`の値を入力しないでください。

    お使いのアカウントでそれぞれのワークスペースに対する監査ログと、アカウントレベルのアクティビティの監査ログが送信されます。ログは設定したS3バケットに送信されます。
   :::

1. Delta Sharingのイベントは`serviceName`が`unityCatalog`に設定されます。それぞれのイベントの`requestParams`には`delta_sharing`プレフィックスが含まれます。

   例えば、以下の監査イベントは受領者トークンの有効期限に対するアップデートを示しています。この例では、検閲された値は`<redacted>`で置き換えられています。

```json:JSON
{
   "version":"2.0",
   "auditLevel":"ACCOUNT_LEVEL",
   "timestamp":1629775584891,
   "orgId":"3049059095686970",
   "shardName":"example-workspace",
   "accountId":"<redacted>",
   "sourceIPAddress":"<redacted>",
   "userAgent":"curl/7.64.1",
   "sessionId":"<redacted>",
   "userIdentity":{
      "email":"<redacted>",
      "subjectName":null
   },
   "serviceName":"unityCatalog",
   "actionName":"updateMetastore",
   "requestId":"<redacted>",
   "requestParams":{
       "id":"<redacted>",
       "delta_sharing_enabled":"true"
       "delta_sharing_recipient_token_lifetime_in_seconds": 31536000
    },
   "response":{
      "statusCode":200,
      "errorMessage":null,
      "result":null
   },
   "MAX_LOG_MESSAGE_LENGTH":16384
}
```

以下の表では、データ提供者の視点でのDelta Sharingにおける監査イベントを一覧しています

:::note info
**注意**
以下の重要なフィールドは常に監査ログに含まれます。

- `userIdentity.email`: アクティビティをスタートしたユーザーID
- `requestParams.id`: Unity Catalogのメタストア
:::

| アクション | requestParams |
|:--|:--|
| updateMetastore  | `delta_sharing_enabled`:存在する場合はDelta Sharingが有効化されたことを示します。<br>`delta_sharing_recipient_token_lifetime_in_seconds`: 存在する場合には、受領者トークンの有効期限が更新されたことを意味します。  |
| createRecipient  | `name`: 受領者名<br>`comment`: コメント  |
| deleteRecipient  | `name`: 受領者名  |
| getRecipient  | `name`: 受領者名  |
| listRecipients  | none  |
| rotateRecipientToken  | `name`: 受領者名<br>`comment`: ローテーションコマンドに指定されたコメント  |
| createShare  | `name`: 共有名<br>`comment`: コメント  |
| deleteShare  | `name`: 共有名  |
| getShare  | `name`: 共有名<br>`include_shared_objects`: リクエストに共有のテーブル名が含まれているかどうか  |
| updateShare  | `name`: 共有名<br>`updates`: 共有で追加・削除されるテーブルのJSON表現。個々のアイテムには`action`(addかremove)、`name`(テーブルの実際の名称)、`shared_as`(`name`と異なる名前で共有された際のスキーマ、テーブル名)、`partition_specification`(パーティション指定がある場合)が含まれます。  |
| listShares  | none  |
| getSharePermissions  | `name`: 共有名  |
| updateSharePermissions  |  `name`: 共有名<br>`changes`: アクセス権更新のJSON表現。それぞれには`principal`(アクセス権が許可・剥奪されたユーザー・グループ)、`add`(許可されたアクセス権のリスト)、`remove`(剥奪されたアクセス権のリスト)が含まれます。 |
| getRecipientSharePermissions  |`name`: 共有名   |
| getActivationUrlInfo  | `recipient_name`: アクティベーションURLを開いた受領者名  |
| retrieveRecipientToken  | `recipient_name`: トークンをダウンロードした受領者名  |

データ受領者の観点から、以下のDelta Sharingのエラーが記録されます。`<`と`>`の間のアイテムはプレースホルダーのテキストです。

- Delta Sharingは選択されたメタストアで有効化されていません。

```
DatabricksServiceException: FEATURE_DISABLED:
Delta Sharing is not enabled`
```

- カタログに対して実行しようとしたオペレーションは存在しません。

```
DatabricksServiceException: CATALOG_DOES_NOT_EXIST:
Catalog ‘xxx’ does not exist.`
```

- アカウント管理者、メタストア管理者では無いユーザーがアクセス権に関するオペレーションを試みました。

```
DatabricksServiceException: PERMISSION_DENIED:
Only administrators can <operation_name> <operation_target>
```

- メタストアが割り当てられていないワークスペースからメタストアに対するオペレーションが試みられました。

```
DatabricksServiceException: INVALID_STATE:
Workspace <workspace_name> is no longer assigned to this metastore
```

- リクエストに受領者名、共有名が含まれていません。

```
DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare Missing required field: <recipient_name>/<share_name>
```

- リクエストに不正な受領者名、共有名が含まれています。

```
DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare <recipient_name>/<share_name> is not a valid name
```

- `DatabricksServiceException: INVALID_PARAMETER_VALUE: Only managed or external table on Unity Catalog can be added to a share.`

    ユーザーがUnity Catalogメタストアにないテーブルを共有しようとしました。

- `DatabricksServiceException: INVALID_PARAMETER_VALUE: There are already two active tokens for recipient <recipient_name>.`

   ユーザーがすでにローテーションされており、以前のトークンが期限切れになっていない受領者をローテーションしようとしました。

- `DatabricksServiceException: RECIPIENT_ALREADY_EXISTS/SHARE_ALREADY_EXISTS: Recipient/Share <name> already exists`

    すでに存在する受領者、共有の名前で新規に作成しようとしました。

- `DatabricksServiceException: RECIPIENT_DOES_NOT_EXIST/SHARE_DOES_NOT_EXIST: Recipient/Share '<name>' does not exist.`

    存在しない受領者、共有に対してオペレーションを行おうとしました。

- `DatabricksServiceException: RESOURCE_ALREADY_EXISTS: Shared Table '<name>' already exists.`

    共有にテーブルを追加しようとしましたが、すでに追加済みです。

- `DatabricksServiceException: TABLE_DOES_NOT_EXIST: Table '<name>' does not exist.`

    存在しないテーブルを参照するオペレーションを実行しようとしました。

- `DatabricksServiceException: SCHEMA_DOES_NOT_EXIST: Schema '<name>' does not exist.`

    存在しないスキーマを参照するオペレーションを実行しようとしました。

データ受領者に関する監査イベントとエラーに関しては、[Delta Sharingリソースに対するアクセスとアクティビティの監査](https://qiita.com/taka_yayoi/items/f45b77984c3ed4b6a0c0#delta-sharing%E3%83%AA%E3%82%BD%E3%83%BC%E3%82%B9%E3%81%AB%E5%AF%BE%E3%81%99%E3%82%8B%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%A8%E3%82%A2%E3%82%AF%E3%83%86%E3%82%A3%E3%83%93%E3%83%86%E3%82%A3%E3%81%AE%E7%9B%A3%E6%9F%BB)をご覧ください。

# 制限

- Unity Catalogのメタストアに格納されているテーブルのみをDelta Sharingで共有することができます。
- Deltaフォーマットのマネージドテーブル、外部テーブルのみがサポートされています。
- このプレビューではビューの共有はサポートされていません。

# 次のステップ

- 受領者がどのようにDelta Sharingの[共有にアクセス](https://qiita.com/taka_yayoi/items/f45b77984c3ed4b6a0c0)するのかを学びます。
- [Unity Catalog](https://qiita.com/taka_yayoi/items/15aede468bdca58ec6a3)について学びます。

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)