API가 받아들이는 값 보내기

API가 받아들이는 값 보내기 (Send values the API accepts)

누락된 값과 명시적인 false나 0을 헷갈리지 않게 SDK 옵션을 만드는 방법을 알아볼게요.

출처: 문서

본문

누락된 값과 명시적인 false 또는 0을 헷갈리지 않게 SDK 옵션을 만들어요. 기본값을 서비스가 정하는 설정에서 특히 중요해요.

인증된 클라이언트로 시작해요. SDK가 내보내는 옵션 타입을 사용하면 에디터가 지원하는 입력을 보여줄 수 있어요.

생성 옵션 만들기 (Construct creation options)

이미지 소스와 수명 주기(lifecycle) 설정을 제공하되, SDK가 요구하는 기간 단위를 사용해요. 예시는 초(seconds)를 받아 경계에서 변환해요.

이 예시는 관리형 이미지(managed image)를 사용하며, 관리형 이미지는 리소스 기본값을 제공해요. 레지스트리 이미지를 쓴다면 이미지 참조 옵션을 사용하고 지원되는 CPU/메모리 쌍을 제공해요.

서비스 기본값을 원할 때는 선택적 boolean의 부재(absence)를 유지해요. 명시적 false는 선택이지 누락이 아니에요. 요청을 만들기 전에 사용자가 준 값을 검증하세요.

TypeScript

return {
  displayName: name,
  image,
  platform,
  lifecycle: { timeoutMs: lifeSeconds * 1_000, autoResume },
};

전체 TypeScript 예시: values/build.ts

import type { ClientCreateOptions, Sandboxes } from '@docker/sandboxes';

export function createRequest(
  name: string,
  image: string,
  lifeSeconds: number,
  platform: ClientCreateOptions['platform'],
  autoResume: boolean | undefined,
): ClientCreateOptions {
  return {
    displayName: name,
    image,
    platform,
    lifecycle: { timeoutMs: lifeSeconds * 1_000, autoResume },
  };
}

export async function sendCreate(
  client: Sandboxes,
  request: ClientCreateOptions,
) {
  const sandbox = await client.create(request, { timeoutMs: 300_000 });
  return sandbox.waitUntilRunning();
}

실제 적용된 값 읽기 (Read the effective values)

샌드박스를 가져와 보고된 플랫폼, 리소스, 만료 시각을 확인해요. 이 값들은 서비스가 기록한 내용을 설명하며, 누락되거나 기본 처리된 입력 값과 다를 수 있어요.

언어의 네이티브 숫자·기간 표현을 유지해요. 큰 정수는 표시하거나 직렬화하기 위해 부동소수점 타입으로 변환하지 마세요.

TypeScript

return {
  expiresAt: sandbox.effectiveFeatures?.timeouts?.expiresAt,
  platform: sandbox.core.platform,
  cpus: sandbox.core.resources?.cpus ?? undefined,
};

전체 TypeScript 예시: values/read.ts

import type { Sandbox, Sandboxes } from '@docker/sandboxes';

export function reportedValues(sandbox: Sandbox) {
  return {
    expiresAt: sandbox.effectiveFeatures?.timeouts?.expiresAt,
    platform: sandbox.core.platform,
    cpus: sandbox.core.resources?.cpus ?? undefined,
  };
}

export async function readSandbox(client: Sandboxes, name: string) {
  return reportedValues(await client.get(name));
}

더 알아보기 (Learn more)

전체 레시피 목록은 Browse all recipes 에서 확인할 수 있어요.