본문으로 건너뛰기

v1 (BackendClient) 과 v2 (BackendClientV2) 선택하기

SDK 는 두 개의 독립적인 백엔드 클라이언트를 제공하며, 둘은 서로를 대체하지 않는다 (SYN-6806). 어떤 호출부가 어느 클라이언트를 쓰는지는 코드에 명시적으로 고정되어 있으며, 호출을 조용히 바꿔버리는 환경변수 스위치는 없다. 이 가이드는 각각을 고르고 배선하고 읽는 방법을 설명한다.

v1v2
클래스BackendClientBackendClientV2 / AsyncBackendClientV2
모듈synapse_sdk/clients/backend/synapse_sdk/clients/backend_v2/
페이지네이션offset (count/next/previous/results)cursor (next/previous/results, count 없음)
리소스 표면flat (client.list_projects(...))namespaced (client.projects.list(...))
응답원시 dict타입 Pydantic 모델 (*V2List / *V2Detail)
접근 토큰 헤더Synapse-Access-Token: Token <t>SYNAPSE-ACCESS-TOKEN: syn_<t>
테넌트 헤더SYNAPSE-Tenant: Token <c>SYNAPSE-Tenant: <c> (기본; tenant_token_prefix=True → Token <c>)

결정 규칙​

호출부의 기능이 클라이언트를 결정하며, 그 결정은 코드에 고정된다. export 는 v2 로, to_task 와 dataset 다운로드는 v1 로 동작한다.

호출 규약고정 클라이언트근거
export/handlers.py (Task / Assignment / GroundTruth / GroundTruthEvent)v22-phase list → bulk_fetch/bulk_data; v2 필수 (v2 부재 시 명시적 에러, v1 폴백 없음)
to_task/steps/fetch_tasks.pyv1v1 list_tasks
dataset/action.py _download_splitv1v1 list_ground_truth_events

새 코드 작성 시에는 작업에 맞는 클라이언트를 고른다:

  • 대용량 결과를 스트리밍/export 해야 하고 bulk hydration·cursor 페이징이 필요 → v2 (export 경로).
  • 기존 v1 스코프 파이프라인 (to_task, dataset 다운로드, create_backend_client 를 쓰는 jobs 상태 동기화) → v1.
  • 모르겠으면 / v1 스코프 표면 작업 중 → v1 (완전히 지원되는 비-deprecated 1급 클라이언트).

두 클라이언트 함께 배선 (build_runtime_clients)​

실행 경로는 synapse_sdk.utils.auth.build_runtime_clients 로 두 클라이언트를 한 번에 배선한다 (자세한 env 우선순위는 아래 표 참고):

from synapse_sdk.utils.auth import build_runtime_clients

clients = build_runtime_clients()
ctx = RuntimeContext(
    client=clients.client,        # v1 (v1 자격증명 없으면 None)
    v2_client=clients.v2_client,  # v2 (v2 자격증명 없으면 None)
)

계약은 "자격증명 있으면 배선, 없으면 None" 이다 — 각 클라이언트는 해당 자격증명이 있을 때만 생성된다. None 은 "미구성"으로 취급하며 에러가 아니다. clients.client_v1 / clients.client_v2 는 clients.client / clients.v2_client 의 정식 대칭 alias 다.

자격증명 env 우선순위​

v1 과 v2 는 공용 핵심 소스를 공유하고 v2 전용 폴백을 둔다 (의도된 계약 — v1 자격증명 하나로 v2 도 배선된다).

자격증명 소스v1v2
SYNAPSE_HOST / SYNAPSE_ACCESS_TOKEN (v1 핵심)✅✅ (공유)
SYNAPSE_PLUGIN_RUN_USER_TOKEN / SYNAPSE_PLUGIN_RUN_TENANT✅✅ (drf_token/tenant 로)
SYNAPSE_BACKEND_V2_ACCESS_TOKEN / SYNAPSE_BACKEND_V2_DRF_TOKEN / SYNAPSE_BACKEND_V2_TENANT❌✅ (v2 전용 폴백)
~/.synapse/config.json✅✅

우선순위(높→낮): 환경변수, 그 다음 ~/.synapse/config.json. v2 는 항상 tenant_token_prefix=True 를 강제한다 (v1 스타일 SYNAPSE-Tenant: Token <c>).

v2 전용 / v1 전용 표면​

  • v1 전용 (v1 사용): agents, storages, legacy serve_applications/, 그리고 v1↔v2 diff 의 v1 전용 엔드포인트 31개.
  • v2 전용 (v2 사용): membership / permission trio 라우트, workshops, 그리고 v2 전용 엔드포인트 101개.

마이그레이션 노트​

v1 과 v2 는 병존한다 — 호출부 전환은 선택적이며 점진적이다. v1 (BackendClient 및 그 v1 팩토리) 은 비-deprecated 로 문서화되어 있으며 제거 계획이 없다. v2 전용 표면이나 v2 스트리밍/bulk 동작이 필요할 때만 전환한다.

참고​