본문으로 건너뛰기
D.Hub
KOEN
고급
10분

Python으로 시나리오 가져오기

최신 dhub2-examples CLI로 retail 시나리오의 자산과 데이터를 가져옵니다.

이 튜토리얼은 시나리오를 개발하거나 CI/CD에서 가져오기를 자동화하는 엔지니어를 위한 내용입니다. 포털에서 ZIP 파일을 직접 가져오려면 실습 시나리오 한 번에 가져오기를 이용하세요.

이 튜토리얼을 마치면

  • 최신 dhub2-examples와 Python 의존성을 설치합니다.
  • Manager API 로그인 정보를 안전하게 설정합니다.
  • retail 시나리오의 메타데이터, 코드 소스와 데이터 파일을 가져옵니다.
  • CLI 요약과 Portal 화면에서 결과를 확인합니다.

1. 저장소와 Python 환경 준비하기

다음 명령을 새 작업 폴더에서 실행합니다.

git clone https://github.com/dtonic/dhub2-examples.git
cd dhub2-examples
python -m venv .venv

가상 환경을 활성화합니다.

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Windows 한국어 콘솔에서는 CLI의 ✓ 문자를 출력할 때 UnicodeEncodeError가 날 수 있습니다. 같은 PowerShell 창에서 UTF-8 모드를 먼저 켜세요.

# Windows PowerShell
$env:PYTHONUTF8='1'

명령 프롬프트를 사용한다면 별도의 cmd 창에서 다음을 실행합니다.

REM Windows 명령 프롬프트(cmd)
set PYTHONUTF8=1

현재 CLI에 필요한 패키지는 다음 두 개입니다. tools/requirements.txt 파일은 사용하지 않습니다.

python -m pip install httpx python-dotenv

2. Manager API와 인증 설정하기

dhub2-examples 저장소 루트, 즉 tools와 scenarios 폴더가 보이는 위치에 .env 파일을 만듭니다. 로컬 로그인 계정으로 실행하려면 다음처럼 작성합니다. SSO 사용자에게는 IdP 비밀번호를 이 방식으로 입력하지 마세요.

DHUB2_API_URL=https://manager.hub.dtonic.io/api/v1
DHUB2_EMAIL=<your-email>
DHUB2_PASSWORD=<your-password>

SSO만 사용하는 환경에서는 CLI가 브라우저의 대화형 SSO 로그인을 대신할 수 없습니다. 관리자에게 다음 중 하나를 요청하세요.

  • 실습 기간에만 사용할 로컬 계정
  • client_credentials가 허용된 자동화용 OIDC 클라이언트와 필요한 컬렉션 권한

OIDC 클라이언트를 사용한다면 설정 → OIDC 클라이언트에서 발급한 Client ID와 한 번만 표시되는 Client Secret을 보안 저장소에 넣고, D.Hub OIDC 발급자 주소의 /token에서 액세스 토큰을 받습니다. 정확한 발급자 주소와 audience는 배포 관리자에게 확인하세요. 브라우저 개발자 도구나 localStorage에서 로그인 토큰을 복사하는 방법은 만료가 짧고 노출 위험이 있으므로 사용하지 않습니다.

curl -sS -X POST "$DHUB2_OIDC_ISSUER/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$DHUB2_CLIENT_ID" \
  --data-urlencode "client_secret=$DHUB2_CLIENT_SECRET" \
  --data-urlencode "audience=dhub2-manager"

응답의 access_token을 .env의 DHUB2_TOKEN에 넣습니다. 이미 안전하게 발급받은 Bearer token이 있다면 같은 형식을 사용합니다.

DHUB2_API_URL=https://manager.hub.dtonic.io/api/v1
DHUB2_TOKEN=<your-token>

DHUB2_API_URL은 Portal 주소가 아니라 /api/v1이 포함된 Manager API 기본 주소입니다. .env에는 인증 정보가 들어 있으므로 Git에 커밋하지 마세요.

3. 시나리오 가져오기

먼저 API 호출 없이 파일과 실행 순서를 확인할 수 있습니다.

python tools/import.py scenarios/retail_inventory_intelligence --dry-run

출력에 예상한 항목이 보이면 실제 가져오기를 실행합니다.

python tools/import.py scenarios/retail_inventory_intelligence

CLI는 다음 순서로 작업합니다.

  1. 컬렉션 1개
  2. 데이터셋 3개와 코드 2개
  3. 온톨로지 엔터티 4개와 관계 3개
  4. 파이프라인 2개와 대시보드 1개
  5. 에이전트 도구 1개와 에이전트 1개
  6. 코드 소스 2개와 Parquet 데이터 3개 업로드

깨끗한 환경에서 CLI가 출력하는 마지막 요약은 다음과 같습니다.

Created : 23
Skipped : 0
Failed  : 0
retail inventory intelligence 시나리오 dry-run에서 자산 목록과 Created 23, Skipped 0, Failed 0 요약이 표시된 터미널
실제 API 호출 전 dry-run의 자산 목록과 실패 0건을 확인합니다.

23은 자산 18개뿐 아니라 코드 소스 업로드 2건과 데이터 업로드 3건도 포함한 수입니다. 이 문구는 포털 UI가 아니라 명령의 실제 출력이므로 영문 그대로 확인합니다.

4. Portal에서 결과 확인하기

브라우저에서 조직의 Portal 주소를 열고 로그인합니다. 로컬 계정을 사용했다면 Login, SSO 계정을 사용했다면 SSO Login을 선택합니다. CLI의 서비스 클라이언트와 Portal 사용자는 서로 다른 신원이므로, Portal 계정에도 가져온 컬렉션을 볼 권한이 있어야 합니다.

로그인 후 왼쪽 컬렉션에서 retail_inventory_intelligence를 열고 다음을 확인합니다.

  • 데이터셋 3개: retail_inventory, competitor_prices, update_competitor_price
  • 코드 2개와 파이프라인 2개
  • 대시보드 inventory_overview
  • 온톨로지 엔터티 4개와 관계 3개
리테일 재고 분석 컬렉션에서 최근 항목 카드와 데이터셋 코드 파이프라인 대시보드 목록을 강조한 화면
CLI 실행 후 Portal에서 데이터셋·코드·파이프라인·대시보드가 같은 컬렉션에 생성됐는지 확인합니다.

retail_inventory, competitor_prices, update_competitor_price 데이터셋의 데이터 탭에는 가져오기 직후에 행이 표시됩니다. update_competitor_price는 파이프라인을 실행한 뒤 생성되는 자산이 아니라, 시나리오 가져오기 중 이미 생성되고 데이터가 업로드되는 데이터셋입니다. retail-assistant는 에이전트 목록에서 열고, 에이전트 상세에서 같은 컬렉션 범위의 도구 ontology_graph_query가 연결됐는지 확인합니다.

자산의 사용 순서는 리테일 재고와 가격 경쟁력 분석하기에서 이어서 확인하세요.