アカウント APIを使用してワークスペースを作成する

このページでは、ワークスペース API を使用して、 Databricks アカウントに新しいワークスペースをデプロイする方法について説明します。

必要な設定オブジェクト

Databricks ワークスペースを作成するには、次の 2 つの構成オブジェクトを参照する必要があります。アカウント内の既存の設定を使用することも、必要に応じて新しい設定を作成することもできます。

ストレージ構成 : データ、ライブラリ、ログなどのワークスペース資産が格納されているルート S3 バケットへのアクセスを定義し、Databricks に付与します。「ストレージ構成を作成する」を参照してください
資格情報の構成 : AWS アカウントにリソースをデプロイするためのアクセス許可を Databricks に付与します。「資格情報構成の作成」を参照してください。

追加の設定オブジェクト

次のいずれかの機能を使用する場合は、ワークスペースをデプロイするときに特定の構成オブジェクトを参照する必要があります。

ネットワーク構成 : ワークスペースを独自の VPC (顧客管理VPC) にデプロイするには、ネットワーク構成を参照する必要があります。「カスタム VPC デプロイのネットワーク設定を作成する」を参照してください。
キー設定 : 顧客管理キーを使用してマネージドサービス、ワークスペースストレージ、またはその両方を暗号化するには、キー設定を参照する必要があります。「暗号化のための顧客管理キーの構成」を参照してください。
プライベートアクセス設定 AWS PrivateLink でプライベート接続を提供するには、プライベートアクセス設定オブジェクトを参照する必要があります。「プライベートアクセス設定の管理」を参照してください。

ワークスペースパラメーター参照の作成

新しいワークスペースを作成する CLI コマンドの例を次に示します。

Bash
databricks account workspaces create --json '{
  "aws_region": "us-west-2",
  "workspace_name": "string",
  "deployment_name": "workspace-1",
  "pricing_tier": "PREMIUM",
  "storage_configuration_id": "b43a6064-04c1-4e1c-88b6-d91e5b136b13",
  "credentials_id": "ccc64f28-ebdc-4c89-add9-5dcb6d7727d8",
  "network_id": "fd0cc5bc-683c-47e9-b15e-144d7744a496",
  "private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
  "managed_services_customer_managed_key_id": "849b3d6b-e68e-468d-b3e5-deb08b03c56d",
  "storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
  "custom_tags": {
    "property1": "string",
    "property2": "string"
  }
}'

Standard パラメーター

aws_region: ワークスペースのコンピュートプレーンの AWS 領域。「Databricks のクラウドとリージョン」を参照してください。
workspace_name：人間にとってわかりやすいワークスペースの名前。これは、Databricks UIでユーザーに表示されるワークスペース名です。
deployment_name: (推奨されますが、省略可能) ワークスペースの一意のデプロイ名。詳細については、ワークスペース API リファレンスを参照してください。
custom_tags: リソースを整理するためのメタデータとして機能するキーと値のペア。タグは、リソースの管理、識別、整理、検索、フィルタリング、およびコストと属性の使用状況の監視に役立ちます。
pricing_tier: ワークスペースの価格レベル。PREMIUM、 ENTERPRISE、または COMMUNITY_EDITION
storage_configuration_id: ストレージコンフィギュレーション ID は、ルート S3 バケットを表します。既存の構成を使用するか、新しいストレージ構成を作成します。
credentials_id: 資格情報の構成 ID。既存の設定を使用するか、新しい認証情報設定を作成します。

高度な構成

次の省略可能なパラメーターを使用して、ワークスペースのネットワーク機能とセキュリティ機能を構成します。

network_id: ネットワーク構成 ID。ワークスペースを顧客管理VPCにデプロイする場合に必要です。「カスタム VPC デプロイのネットワーク設定を作成する」を参照してください。
private_access_settings_id: AWS PrivateLink を有効にするために使用されるプライベートアクセス設定オブジェクトの ID。「プライベートアクセス設定の管理」を参照してください。すべての接続の種類 (フロントエンド、バックエンド、またはその両方) の PrivateLink アクセスに必要です。ワークスペースをデプロイするときに構成する必要があります。
managed_services_customer_managed_key_id: マネージドサービスのキー設定 ID は、キー設定オブジェクトの customer_managed_key_id フィールドです。ノートブックなどのマネージドサービスやコントロールプレーン内のシークレットデータを暗号化するために使用されます。マネージドサービスとワークスペースストレージの両方を暗号化する場合は、 storage_customer_managed_key_id フィールドに同じIDを使用します。ワークスペースをデプロイするときに構成する必要があります。マネージドサービスの顧客管理キーを参照してください。
storage_customer_managed_key_id: ワークスペースストレージのキー設定 ID (キー設定オブジェクトの customer_managed_key_id フィールド)。マネージドサービスとワークスペースストレージの両方を暗号化する場合は、 managed_services_customer_managed_key_id フィールドに同じIDを使用します。ワークスペースストレージの暗号化にのみ使用されます。ワークスペースをデプロイするときに構成する必要があります。「ワークスペースストレージの顧客管理キー」を参照してください。

ワークスペースの応答を作成する

ワークスペースの作成 API を呼び出すと、次のような応答が表示されます。

JSON
{
  "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  "aws_region": "string",
  "creation_time": 0,
  "credentials_id": "c7814269-df58-4ca3-85e9-f6672ef43d77",
  "custom_tags": {
    "property1": "string",
    "property2": "string"
  },
  "deployment_name": "string",
  "managed_services_customer_managed_key_id": "faacdc79-6530-4583-a154-5d427a663e53",
  "network_id": "d6797cf4-42b9-4cad-8591-9dd91c3f0fc3",
  "pricing_tier": "PREMIUM",
  "private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
  "storage_configuration_id": "04aae505-1b1e-4cb9-997d-e1c49282675d",
  "storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
  "workspace_id": 1614665312930232,
  "workspace_name": "string",
  "workspace_status": "PROVISIONING",
  "workspace_status_message": "Workspace resources are being set up."
}

ワークスペースの作成時にエラーが発生した場合は、「ワークスペースの作成エラーのトラブルシューティング」を参照してください。

新しいワークスペースを確認する

ワークスペースのステータスを確認するには、get ワークスペース APIを呼び出します。

ワークスペースの作成時に返されたJSON応答のworkspace_id値を使用します。

応答では、可能なworkspace_status値は次のとおりです。

NOT_PROVISIONED：まだプロビジョニングされていません。
PROVISIONING：まだプロビジョニング中です。 数分待ってから、このAPIリクエストを繰り返します。
RUNNING：デプロイメントが正常に完了し、現在実行されています。
FAILED：デプロイメントに失敗しました。
BANNED：禁止されています。
CANCELLING：キャンセル処理中。

失敗したステータス値を処理する方法については、ワークスペース作成エラーのトラブルシューティングを参照してください。

例えば：

Bash
curl -X GET
'https://accounts.cloud.databricks.com/api/2.0/accounts/<databricks-account-id>/workspaces/<databricks-workspace-id>' \
  --header 'Authorization: Bearer $OAUTH_TOKEN'

応答：

JSON
{
  "workspace_id": 123456789,
  "workspace_name": "my-company-example",
  "aws_region": "us-west-2",
  "creation_time": 1579768294842,
  "deployment_name": "my-company-example",
  "workspace_status": "RUNNING",
  "account_id": "<databricks-account-id>",
  "credentials_id": "<aws-credentials-id>",
  "storage_configuration_id": "<databricks-storage-config-id>",
  "workspace_status_message": "Workspace is running.",
  "network_id": "339f16b9-b8a3-4d50-9d1b-7e29e49448c3",
  "managed_services_customer_managed_key_id": "<aws-kms-managed-services-key-id>",
  "storage_customer_managed_key_id": "<aws-kms-notebook-workspace-storage-id>",
  "pricing_tier": "ENTERPRISE"
}

この例では、ワークスペースのステータス（workspace_status）がRUNNINGに設定されているため、成功しました。PROVISIONINGの場合は、成功するまでこのAPIリクエストを繰り返します。

価格は、デフォルトでアカウントに関連付けられているプランになります。AWSプラットフォーム層を参照してください。

新しいワークスペースのステータスがRUNNINGになったら、新しいワークスペースをテストします。

新しいワークスペースでのユーザーインターフェイスログイン — URL で Web アプリケーションにログインできることを確認します https://<deployment-name>.cloud.databricks.com。たとえば、ワークスペースの作成時に指定したデプロイメント名が ABCSalesの場合、ワークスペースの URL は https://abcsales.cloud.databricks.comになります。アカウントのユーザー名を使用してログインします。
新しいワークスペースでのREST APIログイン — REST APIにアクセスできることを確認します。次の例では、ワークスペースユーザーAPIを呼び出してユーザーのリストを取得します。
Bash
```
curl  -u <user-name> -X GET 'https://<deployment-name>.cloud.databricks.com/api/2.0/scim/v2/Users' \
--header 'Authorization: Bearer $OAUTH_TOKEN'
```
Databricks REST APIsの使用に関するその他の認証オプションなどの詳細については、ワークスペース APIを参照してください。

ステップ 8: デプロイ後の PrivateLink 構成 (省略可能)

このステップは、 AWS PrivateLink を設定する場合にのみ必要です。

ワークスペースの作成後：

フロントエンド の PrivateLink 接続を実装する場合は、「ステップ 5: ユーザー要求を Web アプリケーションにリダイレクトするように内部 DNS を構成する」の説明に従って、関連する DNS 構成の変更を実装します。
オプションで、「ステップ 5: 他の AWS サービスの VPC エンドポイントを追加する」の説明に従って、他の VPC エンドポイントを作成します。

ステップ 9: その他のオプションのデプロイ後構成

新しいワークスペースに対して、次のオプションの構成手順を検討することをお勧めします。

IP アクセスリストの有効化

Web アプリケーション、 REST APIs、 JDBC/ODBC エンドポイント、および DBConnect に接続できる IP アドレスを構成します。許可リストとブロックリストは、IP アドレスまたは範囲として指定できます。ワークスペースの IP アクセスリストの構成を参照してください。

Enable audit log システムテーブル

Databricks 、監査ログシステムテーブルを有効にして、 Databricks ユーザーが実行したアクティビティと発生した使用状況を監視することを強くお勧めします。ワークスペースで Unity Catalog が有効になっている必要があります。手順については、システムテーブルを使用したアカウントアクティビティのモニタリングを参照してください。

ワークスペースの作成エラーのトラブルシューティング

次のセクションでは、一般的なワークスペース作成エラーの解決策を説明します。

アドレスの最大数に達しました

Databricks がユーザーに代わって VPC を作成する場合は、少なくとも 1 つの未使用の Elastic IP が必要です。そうしないと、VPC は作成されず、次のエラーが発生します。

Console

The maximum number of addresses has been reached.

Elastic IPの数を増やして、う一度お試しください。

一般的なトラブルシューティング手順

すべてのワークスペース作成エラーについては、次のトラブルシューティング手順を記載された順序で試してください。

ネットワークの検証

ワークスペースの作成手順または状態チェックの手順でネットワーク関連のエラーが示されている場合は、ネットワーク構成の取得 API を呼び出して、ネットワーク設定が正しいことを確認します。

応答で、warning_messages error_messagesフィールドを表示します。両方の配列が空の場合、警告やエラーはありません。

そうでない場合は、警告とエラーのJSONオブジェクトを注意深く確認してください。

警告の場合、warning_typeの列挙は、問題がサブネットかセキュリティグループのどちらかにあったことを示します。warning_messageには、追加の詳細が記載されています。（NATゲートウェイではなく）ファイアウォールまたはNATインスタンスがある場合、ネットワーク検証によって常に警告が発行されることに注意してください。
エラーの場合、error_typeの列挙は認証情報、VPC、サブネット、セキュリティグループ、ネットワークACLのいずれかに問題があったことを示します。error_messageには、追加の詳細が記載されています。

インフラストラクチャの問題を修正する

ネットワーク設定 API API の取得リクエストに対するレスポンスのエラーに応じて、次のことを確認します。

セキュリティグループは、顧客管理VPC の要件に準拠しています。
クロスアカウント IAM ポリシーには、必要なアクセス許可が含まれています。デプロイタイプに使用するポリシーについては、「ワークスペースデプロイメント用の IAMロールを作成する」を参照してください。

失敗したワークスペースを更新する

失敗したワークスペースを更新するには、ワークスペースの更新 API を呼び出します。

注記

同じAPIを使用して、実行中の（正常にデプロイされた）ワークスペースを更新できますが、変更できるのは資格情報とネットワーク設定のみです。

これらのワークスペース構成フィールドを渡して変更できます：credentials_id、storage_configuration_id、network_id、managed_services_customer_managed_key_id、およびstorage_customer_managed_key_id

workspace_status値がPROVISIONINGを返す場合は、 get ワークスペース APIを使用してRUNNING状態を引き続き確認します。

ワークスペースの更新に失敗した場合は、ネットワークとワークスペースを再作成します

ワークスペースの更新 API が機能しない場合は、ネットワークを削除して再作成する必要があります (独自の VPC を指定した場合)、失敗したワークスペースを次の順序で再作成する必要があります。

ワークスペースの削除 API を使用してワークスペースを削除します。
独自の VPC を提供した場合は、ネットワーク設定の削除 API を使用してネットワーク設定を削除します。
vpc_id、 subnet_ids 、 security_group_idsの正しい値を使用してネットワークを再作成します。
credentials_id、 storage_configuration_id、 network_id、 managed_services_customer_managed_key_id、 storage_customer_managed_key_idの正しい値を使用してワークスペースを再作成します。

workspace_status値 PROVISIONINGを取得した場合は、get ワークスペース APIを使用してRUNNING状態を確認します。

必要な設定オブジェクト​

追加の設定オブジェクト​

ワークスペース パラメーター参照の作成​

Standard パラメーター​

高度な構成​

ワークスペースの応答を作成する​

新しいワークスペースを確認する​

ステップ 8: デプロイ後の PrivateLink 構成 (省略可能)​

ステップ 9: その他のオプションのデプロイ後構成​

IP アクセス リストの有効化​

Enable audit log システムテーブル​

ワークスペースの作成エラーのトラブルシューティング​

アドレスの最大数に達しました​

一般的なトラブルシューティング手順​

ネットワークの検証​

インフラストラクチャの問題を修正する​

失敗したワークスペースを更新する​

ワークスペースの更新に失敗した場合は、ネットワークとワークスペースを再作成します​