使用 SDK 建立並管理沙盒

Important

這項功能位於 測試版 (Beta) 中。 要在工作區中啟用此功能預覽,請在工作區預覽頁面中選擇 Databricks 沙盒 設定。 請參閱 管理 Azure Databricks 預覽。

Databricks SDK for Python 包含一個沙盒用戶端,用於建立沙盒、在沙盒中執行指令、將連接埠轉送給執行其中的應用程式,以及管理其生命週期。 關於 Databricks 沙盒的概述,請參閱 Databricks 沙盒。

安裝 SDK

安裝或升級包含沙盒用戶端的 Python 版 Databricks SDK:

pip install --upgrade databricks-sdk

建立 WorkspaceClient

所有沙盒操作皆透過 WorkspaceClient。 使用從您的環境、設定檔或明確指定的主機和權杖解析出的認證資訊來建立 WorkspaceClient:

from databricks.sdk import WorkspaceClient

# Resolve credentials from the environment or the default config profile:
w = WorkspaceClient()

# Or select a specific ~/.databrickscfg profile:
w = WorkspaceClient(profile="my-workspace")

# Or pass the host and token explicitly:
w = WorkspaceClient(host="https://<workspace>.cloud.databricks.com", token="dapi...")

欲了解更多關於配置與驗證 SDK 的資訊,請參閱 Databricks SDK for Python。

建立一個沙盒

根據 ID 建立沙盒。 你可以選擇性地設定運算規範,例如控制沙盒在無活動狀態下持續運行多久的非活動逾時:

from google.protobuf.duration_pb2 import Duration
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec

created = w.sandbox.create_sandbox(
    sandbox=Sandbox(
        spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=900))),
    ),
    sandbox_id="my-sandbox",
)
print(created.name)   # "sandboxes/my-sandbox"

Tip

若要從你自己的容器映像建立沙盒,請設定 spec.environment.image_uri。 請參考從自訂映像檔建立沙盒。

取得並列出沙盒

依名稱檢索單一沙盒,或列出所有沙盒:

sandbox = w.sandbox.get_sandbox("sandboxes/my-sandbox")
print(sandbox.status.state)   # SandboxState.SANDBOX_STATE_RUNNING

for sandbox in w.sandbox.list_sandboxes():
    print(sandbox.name, sandbox.status.state if sandbox.status else None)

在沙盒中執行指令

在沙盒中執行指令並讀取其輸出。 第一個參數是沙盒名稱,接著是要執行的程式及其參數。 這是一個沒有 shell 的直接執行,所以要執行 shell 指令,請呼叫 /bin/bash -c。 透過 envs 傳遞任何環境變數:

from google.protobuf.duration_pb2 import Duration

resp = w.sandbox.execute_command_sync(
    "sandboxes/my-sandbox",
    "/bin/bash",
    args=["-c", "echo hello world && whoami"],
    envs={"MY_VAR": "value"},
    execution_timeout=Duration(seconds=30),
)
print(resp.status)      # ExecuteCommandStatus.EXECUTE_COMMAND_STATUS_COMPLETED
print(resp.exit_code)   # 0
print(resp.stdout)      # "hello world\nsandbox-agent\n"
print(resp.stderr)
print(resp.truncated)   # True if the output was truncated

從沙盒轉送連接埠

使用連接埠轉發,從本機連線到在沙箱中執行的網頁伺服器、筆記本或 API。 forward() 在 127.0.0.1 開啟監聽器,並將 HTTP 和 WebSocket 流量轉送到沙箱中的某個埠口。 它使用與 WorkspaceClient 相同的工作區憑證進行認證,所以你不需要 SSH 金鑰。 連接埠轉發需要 databricks-sdk 0.166.0 或更新版本。 請參閱 SDK forward() 參考資料 ,了解方法合約及支援的連接埠範圍。

在沙盒中啟動一個會監聽於 0.0.0.0 的應用程式,然後轉發其連接埠。 請在背景執行應用程式,讓指令在應用程式持續執行時返回:

w.sandbox.execute_command_sync(
    "sandboxes/my-sandbox",
    "/bin/bash",
    args=["-c", "nohup python3 -m http.server 10080 --bind 0.0.0.0 > /tmp/server.log 2>&1 &"],
)

with w.sandbox.forward("sandboxes/my-sandbox", 10080) as fwd:
    print(fwd.url)          # http://127.0.0.1:<local-port>
    input("Press Enter to stop forwarding...")

forward()會在本地監聽器準備就緒後立即回傳,而轉發會在背景中持續執行,直到你呼叫 close() 或 with 區塊結束為止。 預設情況下,SDK 會選擇一個免費的本地連接埠。 從 fwd.local_port讀取,或用以下 local_port方式設定特定連接埠:

fwd = w.sandbox.forward("sandboxes/my-sandbox", 10080, local_port=8080)
# Open http://127.0.0.1:8080 in a browser or send requests with curl.
fwd.close()

埠轉發具有以下需求與限制:

  • 沙盒中的應用程式必須在所有介面上監聽(0.0.0.0)。 只在 127.0.0.1 上接聽的應用程式將無法存取。 許多開發伺服器預設會綁定到 127.0.0.1 ,因此會傳遞 host 選項,例如 uvicorn --host 0.0.0.0、 jupyter lab --ip=0.0.0.0、 或 vite --host。
  • 你可以轉寄 10000 到 65535 的連接埠,但 10101、18767 和 19090 除外,這些連接埠由平台保留。
  • 埠轉發會傳輸 HTTP/1.1 和 WebSocket 流量。 原始 TCP,例如資料庫線協定,不被支援。
  • 你只能在自己擁有的沙盒裡轉發埠口。
  • 第一個對已停止沙盒的請求就會啟動它。 應用程式必須在所請求的連接埠上執行,請求才會成功。
  • WebSocket 連線最多會在 1 小時後關閉。 重新連線以繼續。

Note

在 Databricks SDK 0.164.0 與 0.165.0 版本中,此方法被命名為 port_forward()。 在 0.166.0 及以上版本中,請使用 forward()。

若要從您使用 Databricks CLI 建立的沙箱轉發埠,請在 -- 後傳入 SSH 選項。 沙盒 CLI 參考說明了此傳遞方式。 使用 -N 以在不啟動遠端 shell 的情況下保持連線開啟:

databricks sandbox ssh -- -N -L 8080:localhost:8080

更新沙盒元資料

你可以更新沙盒的顯示名稱和閒置逾時。 僅接受下列欄位路徑。 任何其他路徑都會傳回 INVALID_PARAMETER_VALUE:

  • display_name
  • spec.compute.inactivity_timeout
from databricks.sdk.common.types.fieldmask import FieldMask
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec
from google.protobuf.duration_pb2 import Duration

# Rename the sandbox
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(display_name="renamed sandbox"),
    update_mask=FieldMask(["display_name"]),
)

# Extend the inactivity timeout
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=1800)))),
    update_mask=FieldMask(["spec.compute.inactivity_timeout"]),
)

停止並重新啟動沙盒

停止沙盒以釋放其運算資源,同時保留你的主目錄:

w.sandbox.stop_sandbox("sandboxes/my-sandbox")    # Moves to SANDBOX_STATE_STOPPED

再次啟動沙箱以繼續工作:

w.sandbox.start_sandbox("sandboxes/my-sandbox")   # Moves to SANDBOX_STATE_RUNNING

沙盒會在每次啟動後 24 小時自動停止,因此再次啟動沙盒時,會開始新的 24 小時週期。 詳見 Databricks 沙盒限制。

刪除沙盒

完成後刪除沙盒。 刪除沙盒會移除其主目錄,並停止對沙盒的計費:

w.sandbox.delete_sandbox("sandboxes/my-sandbox")

其他資源