API Reference(1)

Shotgun 모듈 속성

• shotgun_api3.shotgun.LOG: API 실행 시 로그 메시지를 기록하는 로깅 인스턴스.
• shotgun_api3.shotgun.NO_SSL_VALIDATION: SSL 인증서의 호스트 이름 일치 검증을 비활성화하는 옵션.

---

Shotgun 클래스

shotgun_api3.shotgun.Shotgun

설명

Shotgun 서버와 클라이언트 간의 연결을 초기화하고 관리하는 클래스입니다. 이 클래스는 데이터를 CRUD(Create, Read, Update, Delete) 방식으로 Shotgun 서버와 주고받을 수 있게 합니다.

생성자 매개변수

 

매개변수	유형	필수   여부	설명
base_url	str	필수	Shotgun 서버의 HTTP/HTTPS URL. 슬래시(/) 없이 작성해야 함. 예: https://example.shotgunstudio.com
script_name	str	선택	서버 인증에 사용되는 Script 엔터티의 이름. script_name이 제공되면 api_key도 반드시 제공되어야 하며, login 및 password는 사용할 수 없음.
api_key	str	선택	Script 인증을 위한 API 키. script_name과 함께 사용됨.
convert_datetimes_to_utc	bool	선택	날짜/시간 데이터를 로컬 시간에서 UTC로 변환 후 서버로 전송. 기본값은 True.
http_proxy	str	선택	프록시 서버 URL. 형식은 [username:password@]111.222.333.444[:8080]로 입력. 예: 192.168.0.1:8888, joe:user@192.168.0.1:8888.
connect	bool	선택	True일 경우, Shotgun 인스턴스를 생성할 때 서버에 즉시 연결하여 호환성을 확인. 주로 테스트 목적으로 사용되며 기본값은 True.
ca_certs	str	선택	외부 SSL 인증서 파일 경로. 회사 내부의 인증서를 사용하거나 애플리케이션을 실행 파일로 패키징할 때 필요할 수 있음. 환경 변수 SHOTGUN_API_CACERTS로도 설정 가능.
login	str	선택	사용자 기반 인증을 위한 사용자 로그인 이름. 이 값이 설정되면 password도 반드시 제공되어야 하며, script_name 및 api_key는 사용할 수 없음.
password	str	선택	사용자 기반 인증을 위한 비밀번호. login과 함께 사용됨.
sudo_as_login	str	선택	모든 작업에 대해 지정된 사용자의 권한을 적용. 작업 기록에는 이 사용자가 작업한 것으로 표시되며, 실제 작업한 스크립트 또는 사용자는 메타데이터(sudo_actual_user)에 기록됨.
session_token	str	선택	세션 기반 인증에 사용하는 토큰. get_session_token() 메서드를 통해 토큰을 생성 가능.
auth_token	str	선택	2단계 인증이 활성화된 서버에서 인증에 필요한 토큰. login 및 password와 함께 사용되며, script_name 및 api_key는 사용할 수 없음. 단, 토큰이 만료되면 새로운 인증이 필요함.

 

---

주요 기능

• 인증(Authentication)
  • script_name + api_key 방식
  • login + password 방식 (사용자 기반 인증)
  • session_token 또는 auth_token 방식 (세션 및 2단계 인증)
• 시간 변환
  • convert_datetimes_to_utc 매개변수를 통해 서버와 클라이언트 간의 시간 데이터 동기화.
• 프록시 지원
  • http_proxy 매개변수를 사용하여 프록시 서버를 경유한 연결 설정 가능.
• SSL 인증서 설정
  • ca_certs를 통해 맞춤형 인증서 사용 가능.

---

주의사항

1. Python 2.6.2 이하 사용 시 프록시 문제
2. HTTPS 연결이 프록시 서버를 통해 작동하지 않을 수 있음. Python 2.6.3 이상으로 업그레이드 필요.
3. 2단계 인증
4. auth_token을 사용할 경우, 인증 토큰이 만료될 수 있으므로 세션을 즉시 설정해야 함.

---

Shotgun 메서드

연결 및 인증 (Connection & Authentication)

메서드	설명
Shotgun.connect	클라이언트를 서버에 연결. 이미 연결된 상태라면 아무 작업도 수행하지 않음.
Shotgun.close	현재 서버 연결을 종료.
Shotgun.authenticate_human_user	HumanUser를 인증.
Shotgun.get_session_token	현재 세션과 관련된 세션 토큰을 가져옴.
Shotgun.add_user_agent	사용자 에이전트 헤더에 추가.
Shotgun.reset_user_agent	사용자 에이전트를 기본값으로 재설정.
Shotgun.set_session_uuid	현재 API 인스턴스에서 브라우저 session_uuid를 설정.
Shotgun.info	서버로부터 API 관련 메타데이터를 가져옴.

---

CRUD 작업

메서드	설명
Shotgun.create	특정 엔터티 타입의 새 엔터티를 생성.
Shotgun.find	주어진 필터와 일치하는 엔터티 검색.
Shotgun.find_one	find()의 단축 메서드로, 단일 결과를 반환.
Shotgun.update	지정된 엔터티를 주어진 데이터로 업데이트.
Shotgun.delete	지정된 엔터티를 삭제(퇴역 처리).
Shotgun.revive	이전에 삭제된 엔터티를 복구.
Shotgun.batch	여러 create(), update(), delete() 요청을 일괄 처리.
Shotgun.summarize	쿼리 결과 필드 데이터를 요약.
Shotgun.note_thread_read	특정 노트의 전체 대화(답글 및 첨부 파일 포함)를 반환.
Shotgun.text_search	특정 엔터티 타입에서 텍스트 검색.
Shotgun.update_project_last_accessed	프로젝트의 last_accessed_by_current_user 필드를 현재 타임스탬프로 업데이트.
Shotgun.work_schedule_read	특정 날짜 범위에 대한 작업일 규칙 반환.
Shotgun.work_schedule_update	특정 날짜에 대한 작업 스케줄 업데이트.
Shotgun.preferences_read	사이트 선호도(subset) 읽기.

---

파일 작업 (Working With Files)

 

메서드	설명
Shotgun.upload	특정 엔터티에 파일 업로드.
Shotgun.upload_thumbnail	로컬 경로에서 파일을 업로드하고 이를 특정 엔터티의 썸네일로 설정.
Shotgun.upload_filmstrip_thumbnail	필름스트립 썸네일을 특정 엔터티에 업로드.
Shotgun.download_attachment	Shotgun 첨부 파일과 관련된 파일 다운로드.
Shotgun.get_attachment_download_url	제공된 첨부 파일의 다운로드 URL 반환.
Shotgun.share_thumbnail	썸네일을 여러 Shotgun 엔터티와 연동.

---

활동 스트림 (Activity Stream)

 

메서드	설명
Shotgun.activity_stream_read	Shotgun에서 활동 스트림 데이터를 검색.
Shotgun.follow	사용자가 특정 엔터티를 팔로우하도록 추가.
Shotgun.unfollow	사용자가 특정 엔터티 팔로우를 해제.
Shotgun.followers	특정 엔터티의 모든 팔로워를 반환.
Shotgun.following	사용자가 팔로우 중인 모든 엔터티 반환.

---

Shotgun 스키마 및 설정 (Schema and Preferences)

 

메서드	설명
Shotgun.schema_entity_read	모든 활성 엔터티 타입, 해당 표시 이름, 가시성 반환.
Shotgun.schema_field_read	특정 엔터티 타입의 모든 필드 스키마 또는 특정 필드 이름의 스키마 반환.
Shotgun.schema_field_create	특정 엔터티 타입에 새 필드 생성.
Shotgun.schema_field_update	특정 엔터티의 필드 속성 업데이트.
Shotgun.schema_field_delete	특정 엔터티 타입에서 필드 삭제.
Shotgun.schema_read	모든 엔터티의 모든 필드 스키마를 가져옴.
Shotgun.schema	버전 3.0.0 이후 사용되지 않음.
Shotgun.entity_types	버전 3.0.0 이후 사용되지 않음.

---

Deprecated (사용 중단된 메서드)

• Shotgun.schema
• Shotgun.entity_types참고: 위 메서드들은 더 이상 지원되지 않으므로 새 버전에서는 사용하지 않는 것이 좋습니다.

---

필터 및 데이터 처리

필터 문법

• 필터는 조건 리스트로 구성되며, 기본적으로 filter_operator로 결합됩니다.
  • all : 모든 조건을 만족해야 함 (AND 조건).
  • any : 조건 중 하나만 만족해도 됨 (OR 조건).

기본 필터 문법

• 기본 형식: [<field>, <relation>, <value(s)>]
• 예제:

filters = [
    ["sg_status_list", "is", "ip"],  # 상태가 "ip"인 것
    ["assets", "is", {"type": "Asset", "id": 9}]  # 특정 Asset ID와 연결된 것
]
result = sg.find("Shot", filters)

복합 필터 문법

• 복합 조건은 사전 형태로 작성되며, filter_operator를 사용하여 구성됩니다.
• 예제:

filters = [
    ["sg_status_list", "is", "ip"],  # 상태가 "ip"인 것
    {
        "filter_operator": "any",    # OR 조건
        "filters": [
            ["assets", "is", {"type": "Asset", "id": 9}],
            ["assets", "is", {"type": "Asset", "id": 23}]
        ]
    }
]
result = sg.find("Shot", filters)

---

지원되는 관계 연산자

• 다양한 데이터 타입에 대해 사용할 수 있는 연산자가 제공됩니다.
• 주요 연산자:
  • is, is_not: 특정 값과 같은지 비교.
  • less_than, greater_than: 값의 대소 비교.
  • contains, not_contains: 특정 문자열이나 값을 포함하는지 확인.
  • in, not_in: 값이 리스트에 포함되는지 확인.
  • between, not_between: 값이 특정 범위 내에 있는지 확인.
  • starts_with, ends_with: 문자열이 특정 접두사 또는 접미사로 시작/끝나는지 확인.

---

필터 프리셋

• 필터 프리셋은 복잡한 필터링 작업을 간단히 수행하기 위해 제공됩니다.
• 프리셋 이름과 파라미터를 사용하여 특정 작업을 정의할 수 있습니다.
• 필터 프리셋은 일반 필터와 함께 사용할 수 있으며, AND 조건으로 결합됩니다.

프리셋 사용 예제

LATEST 프리셋: 엔티티별 최신 데이터를 반환.

additional_filter_presets = [
    {
        "preset_name": "LATEST",
        "latest_by": "ENTITIES_CREATED_AT"
    }
]

filters = [["code", "is", "ABC"]]
result = sg.find("Version", filters=filters, additional_filter_presets=additional_filter_presets)

 

CUT_SHOT_VERSIONS 프리셋: 특정 Cut ID와 연결된 모든 Shot의 버전을 검색.

additional_filter_presets = [
    {
        "preset_name": "CUT_SHOT_VERSIONS",
        "cut_id": 1
    }
]

result = sg.find("Version", additional_filter_presets=additional_filter_presets)

---

사용 가능한 프리셋 목록

• Cut:
  • LATEST (최신 개정 번호를 반환).
• Version:
  • LATEST (엔티티별 최신 Version 반환).
  • CUT_SHOT_VERSIONS (특정 Cut ID와 연결된 Shot의 최신 Version 반환).
• Published Files:
  • LATEST (최신 파일 반환).

---

기타 주요 기능

• 워크 스케줄 관리: 작업일 규칙 읽기 및 업데이트(work_schedule_read, work_schedule_update).
• 활동 스트림: 활동 기록 데이터를 검색 (activity_stream_read).
• 요약(Summarize): 엔터티 데이터를 그룹화 및 통계 처리.

---

환경 변수 및 로컬라이제이션

• ShotGrid는 환경 변수와 지역 설정(Localization)을 지원하여 다양한 사용자 환경에서 적응 가능.