用SDK创建和管理沙盒

Important

此功能在 Beta 版中。 要在工作区中启用此功能预览,请选择在工作区预览页面启用 Databricks沙盒 设置。 请参阅 Manage Azure Databricks 预览版。

Python 版 Databricks SDK 包含一个沙箱客户端,用于创建沙箱、在其中运行命令、将端口转发到运行在其中的应用,并管理其生命周期。 有关Databricks沙盒的概述,请参见 Databricks沙盒。

安装 SDK

安装或升级包含沙盒客户端的 Python 版 Databricks SDK:

pip install --upgrade databricks-sdk

创建一个工作区客户端

所有沙箱操作都通过 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

从沙箱转发端口

使用端口转发功能,从本地计算机访问在沙箱中运行的 Web 服务器、Notebook 或 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 ,因此传递一个主机选项,例如 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")

其他资源