【Databricks】REST APIのチートシート

# 背景・目的
DatabricksのREST APIを使う機会がありましたので、目的別に整理しメモしておきます。

:::note info
徐々に更新します。
:::

# まとめ
- REST APIは[こちら](https://docs.databricks.com/api/workspace/introduction)を参照してください。
- REST APIにはレート制限があります。それぞれのレート制限は[こちら](https://docs.databricks.com/ja/resources/limits.html#limits-api-rate-limits)を参照してください。
- 目的別のREST APIは下記のとおりです。（※2023/10/08時点の情報です）

|分類 | 目的 |  REST API(リファレンス) | 備考|
|:---|:---|:---|:---|
|Unity Catalog|[カタログのリストを取得したい](https://qiita.com/zumax/items/17200f91476d9730ab83#list-catalogs) |[List catalogs](https://docs.databricks.com/api/workspace/catalogs/list)|
|Identity and Access Management |[グループの一覧を取得したい](https://qiita.com/zumax/items/17200f91476d9730ab83#list-group-details)|[List group details](https://docs.databricks.com/api/workspace/groups/list)|Public Preview|
| | [ユーザの一覧を取得したい](https://qiita.com/zumax/items/17200f91476d9730ab83#list-users) |[List users](https://docs.databricks.com/api/workspace/users/list)| Public Preview|



# 概要
## 基本的な構文
基本的な構文の例を下記に記載します。
```
curl --request GET "https://${DATABRICKS_HOST}/api/2.0/clusters/get" \
     --header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     --data '{ "cluster_id": "1234-567890-a12bcde3" }'
```
下記を指定します。
- DATABRICKS_HOST: Databricksのホスト名
- DATABRICKS_TOKEN: アクセストークン

## レート制限
DatabricksのREST APIはレート制限があるようです。
- 1秒あたりのレートが設定されています。
- WorkspaceとAPIごとにレートが設定されています。詳細は[こちら](https://docs.databricks.com/ja/resources/limits.html#limits-api-rate-limits)を参照ください。
- 上限引き上げが可能なものもあります。引き上げる際は、Databricks担当者を通して依頼するようです。
- レート制限に引っかかる場合は、429 Too Many Requestsが返されます。


# 実践
## 前提
### アクセストークンの取得
REST APIに指定するアクセストークンを取得します。

1. ワークスペースにサインインします。
1. 右上のプルダウンから「User Settings」をクリックします。

    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/e770a9b3-d5ac-d42f-2df2-ac51eccb995c.png" width=200>

1. 「Developer」をクリックします。
    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/67a2a0aa-dc6b-e2c2-87bf-b2f618c00ac3.png" width=400>

1. Access tokensの「Manage」をクリックします。
    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/cb14d25c-d2b8-c481-f90f-ac82b5184704.png" width=500>

1. Access tokensの「Generate new token」をクリックします。
    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/0ee507fb-19ac-25df-0eeb-4e4d4a5d2886.png" width=600>

1. ポップアップがあがるので、CommentとLifetimeを入力し「Generate」をクリックします。
    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/b1193fff-6601-9a91-2ac2-3249b0acc44a.png" width=400>

1. 次のページでTokenが表示されるので、メモしてください。（ここでしか確認できません。）
1. 登録されました。
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/85ea8799-336a-323e-a75f-56a9853a577f.png)

### jqのインストール
:::note info
必須ではありません。
:::

1. REST APIで返されたJSONを見やすくするため、jqをインストールしておきます。


## REST API
### Unity Catalog
#### List catalogs
- API
```
/api/2.1/unity-catalog/catalogs
```

- サンプル
```
$ curl --request GET "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/catalogs" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"   | jq
  
{
  "catalogs": [
    {
      "name": "main",
      "owner": "XXXXX",
      "comment": "Main catalog (auto-created)",
      "catalog_type": "MANAGED_CATALOG",
      "metastore_id": "XXXXXX",
      "created_at": 1694869621233,
      "created_by": "XXXXX",
      "updated_at": 1694869621233,
      "updated_by": "XXXXX",
      "isolation_mode": "OPEN",
      "browse_only": false,
      "provisioning_info": {
        "state": "ACTIVE"
      },
      "id": "XXXXXXX",
      "full_name": "XXXX",
      "securable_type": "CATALOG",
      "securable_kind": "CATALOG_STANDARD"
    },
    {
      "name": "system",
      "owner": "XXXXX",
      "comment": "System catalog (auto-created)",
      "catalog_type": "SYSTEM_CATALOG",
      "metastore_id": "XXXXXXX",
      "created_at": 1694869621052,
      "created_by": "XXXXXX",
      "updated_at": 1694869621052,
      "updated_by": "XXXXXX",
      "isolation_mode": "OPEN",
      "browse_only": false,
      "provisioning_info": {
        "state": "ACTIVE"
      },
      "id": "XXXXXX",
      "full_name": "XXX",
      "securable_type": "CATALOG",
      "securable_kind": "CATALOG_SYSTEM"
    }
  ]
}
$
```

### Identity and Access Management
#### Groups
##### List group details
- API
```
/api/2.0/preview/scim/v2/Groups
```

- サンプル
:::note info 
※結果は省略しています。
:::

```
$ curl --request GET "https://${DATABRICKS_HOST}/api/2.0/preview/scim/v2/Groups" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"   | jq
```



#### Users
##### List users
- API
```
/api/2.0/preview/scim/v2/Users
```

- サンプル
:::note info 
※結果は省略しています。
:::

```
$ curl --request GET "https://${DATABRICKS_HOST}/api/2.0/preview/scim/v2/Users" \               
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"   | jq
```

# 参考
https://docs.databricks.com/api/workspace/introduction