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_namespec.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")