API Usage Tips

모듈 임포트

• 권장: 전체 모듈(shotgun_api3)을 임포트합니다. 모듈 수준에서 관리되는 중요한 기능이 있기 때문입니다.

import shotgun_api3

• 비추천: 특정 클래스만 임포트하지 마세요.

from shotgun_api3 import Shotgun

---

멀티스레딩

• ShotGrid API는 **스레드 안전(thread-safe)**하지 않습니다. 각 스레드마다 별도의 연결 객체를 사용하는 것이 좋습니다.

---

엔터티 필드

• find() 또는 create() 호출 시 엔터티 필드는 표준 딕셔너리 형태로 반환됩니다:
  • type: 엔터티 타입(CamelCase).
  • name: 엔터티의 디스플레이 이름.

{'type': 'Asset', 'name': 'redBall', 'id': 1}

---

사용자 정의 엔터티(CustomEntities)

• 사용자 정의 엔터티는 API에서 항상 기본 이름으로 참조됩니다(예: CustomEntity01).
• 스튜디오 전역 매핑 테이블을 사용하여 간단하게 관리할 수 있습니다:

# studio_globals.py

entity_type_map = {
  'Widget': 'CustomEntity01',
  'Foobar': 'CustomEntity02',
  'Baz': 'CustomNonProjectEntity01,
}

# or even simpler, you could use a global like this
ENTITY_WIDGET = 'CustomEntity01'
ENTITY_FOOBAR = 'CustomEntity02'
ENTITY_BAZ = 'CustomNonProjectEntity01'

사용 예시

import shotgun_api3
import studio_globals

sg = shotgun_api3.Shotgun('<https://my-site.shotgrid.autodesk.com>', 'script_name', '0123456789abcdef0123456789abcdef0123456')
result = sg.find(studio_globals.ENTITY_WIDGET,
                 filters=[['sg_status_list', 'is', 'ip']],
                 fields=['code', 'sg_shot'])

---

연결 엔터티(Connection Entities)

• 다대다 관계를 관리하는 연결 엔터티.
• 예: PlaylistVersionConnection 엔터티는 재생 목록과 버전 간의 관계를 추적합니다.
• 연결 엔터티 예제:

filters = [['playlist', 'is', {'type':'Playlist', 'id':4}]]
fields = ['playlist.Playlist.code', 'sg_sort_order', 'version.Version.code']
result = sg.find('PlaylistVersionConnection', filters, fields)

리스트로 반환!

---

API로 접근할 수 없는 필드

• UI 전용 필드:
  • Smart Cut Fields: smart_cut_in, smart_cut_out 등.
  • 파이프라인 단계(Pipeline Step) 요약 필드.
  • 쿼리 필드(Query Fields): 클라이언트 UI에서만 실행 가능.

---

감사 필드(Audit Fields)

• created_by 및 created_at 필드는 생성 시 설정 가능하지만, updated_by와 updated_at은 자동으로 설정됩니다.

---

로깅

• API는 표준 Python 로깅을 사용합니다.
  • 로깅 활성화:

• import logging logging.basicConfig(level=logging.DEBUG)

  
   
  • 파일로 출력:

• logging.basicConfig(level=logging.DEBUG, filename='/path/to/logfile.log')

  
   
  • 로깅 비활성화:

• sg_log = logging.getLogger('shotgun_api3') sg_log.setLevel(logging.ERROR)

---

최적화

• 관련 쿼리 병합: 데이터 요청을 줄이기 위해 "필드 점 표기법(dot notation)" 사용.
  • 주의: 성능 문제로 다중 엔터티 필드에서는 지원되지 않습니다.

# Get shot codes and sequence status all in one query
project_name = 'Big Buck Bunny'
sg_shots = sg.find("Shot", [['project.Project.name', 'is', project_name]],
                   ['code', 'sg_sequence.Sequence.sg_status_list'])