Tworzenie i zarządzanie piaskownicami za pomocą SDK

Ważna

Ta funkcja jest dostępna w wersji beta. Aby włączyć podgląd tej funkcji w obszarze roboczym, włącz ustawienie Databricks Sandbox na stronie Podglądy obszaru roboczego. Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Zestaw SDK Databricks dla Python zawiera klienta piaskownicy do tworzenia piaskownic, uruchamiania w nich poleceń, przekazywania portów do aplikacji działających w tych piaskownicach oraz zarządzania ich cyklem życia. Aby uzyskać przegląd Databricks Sandbox, zobacz Databricks Sandbox.

Zainstaluj zestaw SDK

Zainstaluj lub zaktualizuj SDK Databricks dla Python, który zawiera klienta sandbox:

pip install --upgrade databricks-sdk

Stwórz WorkspaceClient

Wszystkie operacje sandboxowe przebiegają przez .WorkspaceClient Utwórz WorkspaceClient, używając poświadczeń uzyskanych ze środowiska, profilu konfiguracji lub jawnie określonych hosta i tokenu:

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

Więcej informacji o konfigurowaniu i uwierzytelnianiu SDK można znaleźć w Databricks SDK dla Python.

Stwórz piaskownicę

Utwórz sandbox na podstawie identyfikatora. Możesz opcjonalnie skonfigurować specyfikację zasobów obliczeniowych, na przykład limit czasu bezczynności, który określa, jak długo środowisko sandbox pozostaje uruchomione bez aktywności:

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"

Wskazówka

Aby stworzyć piaskownicę z własnego obrazu kontenera, ustaw spec.environment.image_uri. Zobacz Utwórz piaskownicę z obrazu niestandardowego.

Pobierz i wypisz piaskownice

Pobierz pojedyncze środowisko testowe według nazwy lub wyświetl listę wszystkich środowisk testowych:

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)

Uruchom polecenie w piaskownicy

Uruchom polecenie w środowisku izolowanym i odczytaj dane wyjściowe. Pierwszym argumentem jest nazwa sandbox, następnie program do uruchomienia i jego argumenty. Jest to bezpośrednie wywołanie bez użycia powłoki, więc aby uruchomić polecenie w powłoce, wywołaj /bin/bash -c. Przepuszcz dowolne zmienne środowiskowe przez 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

Przekieruj port w piaskownicy

Użyj przekierowania portów, aby z lokalnego komputera uzyskać dostęp do serwera internetowego, notebooka lub interfejsu API działającego w piaskownicy. forward() otwiera nasłuchiwanie na 127.0.0.1 i przekazuje ruch HTTP oraz WebSocket do portu w piaskownicy. Uwierzytelnia się tymi samymi poświadczeniami do przestrzeni roboczej co WorkspaceClient, więc nie potrzebujesz kluczy SSH. Przekierowanie portów wymaga databricks-sdk wersji 0.166.0 lub nowszej. Zobacz dokumentację referencyjną zestawu SDK forward(), aby poznać sygnaturę metody i zakres obsługiwanych portów.

Uruchom aplikację w piaskownicy, która nasłuchuje na 0.0.0.0, a następnie przekieruj jej port. Uruchom aplikację w tle, aby polecenie wracało, gdy aplikacja działa dalej:

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() zwraca sterowanie, gdy tylko lokalny nasłuch jest gotowy, a przekazywanie działa w tle, dopóki nie wywołasz close() lub do zakończenia bloku with. Domyślnie SDK wybiera wolny port lokalny. Odczytaj go z fwd.local_port, lub ustaw konkretny port za pomocą 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()

Przekierowanie portów ma następujące wymagania i ograniczenia:

  • Aplikacja w piaskownicy musi nasłuchiwać na wszystkich interfejsach (0.0.0.0). Aplikacje nasłuchujące tylko na 127.0.0.1 są niedostępne. Wiele serwerów deweloperskich domyślnie wiąże się z 127.0.0.1, więc podaj opcję hosta, taką jak uvicorn --host 0.0.0.0, jupyter lab --ip=0.0.0.0 lub vite --host.
  • Możesz przekierować porty 10000 do 65535, z wyjątkiem 10101, 18767 i 19090, które platforma rezerwuje.
  • Przekierowanie portów przenosi ruch HTTP/1.1 i WebSocket. Surowe TCP, takie jak protokół wire bazy danych, nie jest obsługiwane.
  • Porty możesz przekazywać tylko w sandboxach, które należą do ciebie.
  • Pierwsze żądanie do zatrzymanego sandboxa go uruchamia. Aplikacja musi działać na żądanym porcie, aby żądanie zakończyło się sukcesem.
  • Połączenia WebSocket zamykają się po maksymalnie 1 godzinie. Połącz się ponownie, aby kontynuować.

Note

W wersjach 0.164.0 i 0.165.0 SDK Databricks metoda ta nosiła nazwę port_forward(). W wersji 0.166.0 i wyższych użyj forward().

Aby przekazać port z piaskownicy utworzonej za pomocą Databricks CLI, przekaż opcje SSH po --. Referencja Sandbox CLI dokumentuje to przekazywanie. Używaj -N , aby utrzymać połączenie otwarte bez uruchamiania zdalnej powłoki:

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

Zaktualizuj metadane sandboxowe

Możesz zaktualizować nazwę wyświetlania sandboxu oraz limit czasu nieaktywności. Akceptowane są tylko następujące ścieżki terenowe. Każda inna ścieżka zwraca: 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"]),
)

Zatrzymaj i uruchom ponownie piaskownicę

Zatrzymaj środowisko sandbox, aby zwolnić jego zasoby obliczeniowe, zachowując katalog domowy:

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

Uruchom ponownie środowisko testowe, aby wznowić pracę:

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

Sandbox automatycznie zatrzymuje się 24 godziny po każdym starcie, więc ponowne uruchomienie rozpoczyna nowy 24-godzinny okres. Zobacz ograniczenia sandboxów Databricks.

Usuń piaskownicę

Usuń piaskownicę, gdy skończysz. Usunięcie środowiska testowego powoduje usunięcie jego katalogu domowego i wstrzymanie naliczania opłat za to środowisko:

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

Dodatkowe zasoby