후크 유형 제출 후크 구성 후크 입력 보안 Studio 배포 오류 처리 모범 사례 제출 방법 추가 리소스

제출 후크

제출 후크를 사용하면 Deadline Cloud 작업 제출 워크플로 중에 사용자 지정 스크립트를 실행할 수 있습니다. 후크는 작업이 Deadline Cloud 서비스에 도달하기 전에 작업을 제출하는 워크스테이션에서 로컬로 실행됩니다. 후크는 작업자 또는 AWS 클라우드에서 실행되지 않습니다. 후크는 시스템에서 실행되므로 제출하는 사용자가 사용할 수 있는 로컬 파일, 환경 변수 및 네트워크 리소스에 액세스할 수 있습니다.

후크를 사용하여 작업 구성을 검증하거나, 추가 자산을 검색하거나, 제출 파라미터를 수정하거나, 프로덕션 추적 소프트웨어와 같은 외부 시스템과 통합할 수 있습니다. 작업자 또는 클라우드에서 실행되는 다른 통합 지점은 섹션을 참조하세요작업에 대한 후크, 이벤트 및 통합 지점.

후크를 구성하는 방법에는 두 가지가 있습니다.

번들 후크 - hooks.yaml (또는 hooks.json) 파일을와 함께 작업 번들 디렉터리에 배치합니다template.yaml. 번들 후크는 제출 전에 번들이 이미 존재하는 CLI 워크플로에 적합합니다.
환경 후크 - DEADLINE_HOOKS_DIR 환경 변수를가 포함된 디렉터리로 가리킵니다hooks.yaml. 환경 후크는 작업 번들을 수정하지 않고 모든 제출에 후크를 적용하려는 스튜디오에 유용합니다.

두 소스를 동시에 활성화할 수 있습니다. 둘 다 있으면 환경 후크가 먼저 실행된 다음 번들 후크가 실행됩니다.

참고

Maya, Nuke 또는 Blender와 같은 애플리케이션 내(DCC) 제출자는 제출 전 및 제출 후 단계에 대해서만 환경 후크를 실행합니다. 사전 GUI 단계는 DCC 제출자에게 적용되지 않습니다. 자세한 내용은 사전 GUI 후크 단원을 참조하십시오.

후크 유형

Deadline Cloud는 제출 워크플로의 여러 지점에 해당하는 세 가지 후크 유형을 지원합니다.

사전 GUI 후크

사전 GUI 후크는 제출 대화 상자가 열리기 전에 실행됩니다. 다음 작업에 사전 GUI 후크를 사용할 수 있습니다.

중요

사전 GUI 후크는 독립 실행형 GUI 제출자()에서만 실행됩니다deadline bundle gui-submit. Maya, Nuke 또는 Blender와 같은 인애플리케이션(DCC) 제출자에서는 실행되지 않습니다. 이러한 애플리케이션은 제출 대화 상자를 직접 빌드하고 사전 GUI 단계를 호출하지 않기 때문입니다. 사전 GUI 후크는 GUI 단계가 없는 CLI 제출(deadline bundle submit)에도 적용되지 않습니다. 사전 제출 및 사후 제출 후크는 모든 제출 방법에서 작동합니다.

작업 이름, 설명 및 우선 순위 미리 채우기
현재 장면 또는 파이프라인 컨텍스트를 기반으로 파라미터 기본값 설정
작업 메타데이터에 대한 프로젝트 관리 시스템 쿼리

사전 GUI 후크는 실패할 경우 대화 상자가 열리지 않도록 차단합니다(0이 아닌 종료 코드 또는 제한 시간).

JSON을 stdout으로 출력하여 초기 대화 상태를 수정합니다. 다음 예제에서는 출력 형식을 보여줍니다.


import json

output = {
    "name": "My Render - v042",
    "description": "Submitted via pipeline",
    "parameters": {
        "SceneFile": "/resolved/path/to/scene.ma",
        "OutputPath": "/shots/sh010/renders/",
        "deadline:priority": 75,
        "deadline:maxFailedTasksCount": 5,
        "deadline:maxRetriesPerTask": 3,
        "deadline:maxWorkerCount": 10,
        "deadline:targetTaskRunStatus": "READY"
    }
}
print(json.dumps(output))

다음 표에서는 사전 GUI 후크의 출력 필드를 설명합니다.

Field	유형	설명
`name`	문자열	작업 이름 필드를 미리 채웁니다.
`description`	문자열	작업 설명 필드를 미리 채웁니다.
`parameters`	객체	이름별로 파라미터 값을 미리 채웁니다. 작업 템플릿 파라미터는 이름을 직접 사용합니다. 공유 작업 속성은 `deadline:` 접두사를 사용합니다.

다음 표에서는 parameters 객체의 deadline: 접두사로 설정할 수 있는 공유 작업 속성을 설명합니다.

Key(키)	유형	설명
`deadline:priority`	Integer	우선 순위(0~100).
`deadline:maxFailedTasksCount`	Integer	작업이 실패하기 전에 최대 실패한 작업 수입니다.
`deadline:maxRetriesPerTask`	Integer	실패한 작업당 최대 재시도 횟수입니다.
`deadline:maxWorkerCount`	Integer	최대 동시 작업자 수.
`deadline:targetTaskRunStatus`	문자열	초기 작업 상태: `READY` 또는 `SUSPENDED`.

참고

CLI에서 제공하는 --parameter 값이 후크에서 제공하는 값보다 우선합니다parameters.

사전 제출 후크

사전 제출 후크는 작업 첨부 파일이 해시되고 업로드되기 전에 실행됩니다. 다음 작업에 대해 사전 제출 후크를 사용할 수 있습니다.

작업 구성 검증
입력 파일 검색 및 추가
우선순위와 같은 작업 파라미터 수정
스튜디오 정책 적용

사전 제출 후크는 실패할 경우 제출을 차단합니다(0이 아닌 종료 코드 또는 제한 시간).

JSON을 stdout으로 출력하여 제출을 수정합니다. 후크 출력은 중첩된 키 수준에서 자산 참조를 대체합니다. 후크가 inputFilenames를 출력하면 후크 출력이 전체 inputFilenames 목록을 대체합니다. Deadline Cloud는 출력에 포함하지 않는 키를 보존합니다.

다음 예시에서는 검색된 텍스처 파일을 제출에 추가합니다.


import json
import os
import sys

metadata = json.load(sys.stdin)
bundle_dir = metadata["jobBundleDir"]

textures = []
for root, _, files in os.walk(bundle_dir):
    for f in files:
        if f.endswith(('.exr', '.png', '.jpg', '.tx')):
            textures.append(os.path.join(root, f))

if textures:
    print(json.dumps({
        "attachments": {
            "assetReferences": {
                "inputFilenames": textures
            }
        }
    }))

사전 제출 후크는 stdout에서 parameters 맵을 내보내 작업 템플릿 파라미터 값을 수정할 수도 있습니다.


print(json.dumps({"parameters": {"SceneFile": "/resolved/scene.ma", "Quality": "high"}}))

파라미터 키는 작업 템플릿 파라미터 이름입니다. 후크의 값은 번들의 파라미터 값 위에 적용되지만 CLI에서 제공하는 --parameter 값은 여전히 후크에서 제공하는 값보다 우선합니다.

중요

PATH stdout에서 내보내는 파라미터는 절대값이어야 합니다. 후크는 제출 쉘의 작업 디렉터리에서 실행되지 않으므로 stdout의 상대 PATH 값이 모호하고 오류와 함께 거부됩니다. 절대 경로를 내보내거나(예:와 조인DEADLINE_JOB_BUNDLE_DIR) 값을 대신 디스크의 parameter_values.yaml/parameter_values.json에 씁니다. 여기서 상대는 작업 번들 디렉터리에 대해 확인PATH됩니다.

제출 후 후크

제출 후 후크는 CreateJob API 호출이 성공적으로 반환된 후 실행됩니다. 현재 Deadline Cloud에서 작업을 수락했습니다. 다음 작업에 대해 제출 후 후크를 사용할 수 있습니다.

알림 전송(Slack, 이메일)
추적 시스템 업데이트
로그 제출 세부 정보

제출 후 후크 실패는 경고로 기록되지만 제출된 작업에는 영향을 주지 않습니다.

제출 후크 구성

hooks.yaml 또는 hooks.json 파일에서 후크를 정의합니다. 파일을와 함께 작업 번들 디렉터리에 배치template.yaml하거나에 지정된 디렉터리에 배치합니다DEADLINE_HOOKS_DIR. 두 형식이 모두 동일한 디렉터리에 있는 경우 제출자는 오류를 보고합니다.

version 필드는 필수이며 여야 합니다"1.0".

다음 예제에서는 hooks.yaml 구성을 보여줍니다.


version: "1.0"
preGUI:
  - command: python3
    args: [scripts/prefill_from_shotgrid.py]
    timeout: 10

preSubmission:
  - command: python3
    args: [scripts/validate_assets.py]
    timeout: 60
    env:
      VALIDATION_LEVEL: strict

  - command: python3
    args: [scripts/discover_textures.py]

postSubmission:
  - command: python3
    args: [scripts/notify_slack.py]
    timeout: 15
    env:
      SLACK_WEBHOOK: https://hooks.slack.com/...

후크 정의 필드

각 후크 항목은 다음 필드를 허용합니다.

Field	필수	기본값	설명
`command`	예	–	실행 파일 또는 인터프리터(예: `python3` 또는 `bash`).
`args`	아니요	`[]`	명령줄 인수입니다.
`timeout`	아니요	`60`	초 단위의 최대 실행 시간입니다.
`env`	아니요	`{}`	추가 환경 변수. 후크는 제출자의 전체 환경을 상속합니다. `DEADLINE_*` 변수와 후크별 `env` 값은 위에 계층화됩니다.

경로 확인

후크 스크립트는 다음 규칙에 따라 확인됩니다.

절대 경로 - 있는 그대로 사용됩니다.
상대 경로 - 작업 번들 디렉터리를 기준으로 해결됩니다.
명령 이름 - 시스템 PATH에서 검색됩니다.

후크 입력

후크는 stdin의 JSON과 편의 환경 변수를 통해 작업 메타데이터를 수신합니다.

환경 변수

다음 환경 변수는 모든 후크에서 사용할 수 있습니다.

변수	설명
`DEADLINE_JOB_NAME`	작업 이름.
`DEADLINE_PRIORITY`	작업 우선 순위입니다.
`DEADLINE_FARM_ID`	팜 ID.
`DEADLINE_QUEUE_ID`	대기열 ID입니다.
`DEADLINE_JOB_BUNDLE_DIR`	작업 번들 디렉터리의 경로입니다.
`DEADLINE_STORAGE_PROFILE_ID`	스토리지 프로필 ID(설정된 경우).
`DEADLINE_JOB_ID`	작업 ID(제출 후 후크만 해당).

stdin의 JSON

전체 메타데이터는 stdin에서 JSON으로 제공됩니다. 다음 예제에서는 구조를 보여줍니다.


{
  "jobName": "My Render Job",
  "priority": 50,
  "farmId": "farm-abc123",
  "queueId": "queue-def456",
  "jobBundleDir": "/path/to/bundle",
  "parameters": {"SceneFile": "/path/to/scene.ma"},
  "submitterName": "Maya",
  "assetReferences": {
    "inputFilenames": ["/path/to/texture.exr"],
    "inputDirectories": [],
    "outputDirectories": ["/path/to/output"],
    "referencedPaths": []
  },
  "submissionPayload": {}
}

보안

후크는 기본적으로 비활성화되어 있습니다. 각 후크 소스에는 활성화해야 하는 고유한 설정이 있습니다.

번들 후크 활성화

작업 번들 hooks.yaml 내에서에 정의된 후크를 허용하려면 번들 후크 설정을 활성화합니다.

번들 후크를 활성화하려면

다음 명령을 실행합니다.


deadline config set settings.allow_bundle_hooks true

환경 후크 활성화

에서 지정한 디렉터리에서 후크를 허용하려면 환경 후크 설정을 DEADLINE_HOOKS_DIR활성화하고 디렉터리 경로를 설정합니다.

환경 후크를 활성화하려면

설정을 활성화합니다.


deadline config set settings.allow_environment_hooks true

일반적으로 애플리케이션 시작 관리자 스크립트에서 환경 변수를 설정합니다.
```
export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
```

확인 프롬프트

후크를 활성화하면 제출자가 후크가 실행되기 전에 확인하라는 메시지를 표시합니다. 대화 상자가 열리기 전에 사전 GUI 후크에 프롬프트가 표시됩니다. 제출을 선택하면 사전 제출 및 사후 제출 후크에 프롬프트가 표시됩니다.

프롬프트는 실행할 명령을 표시하므로 진행하기 전에 검토할 수 있습니다.


This job bundle contains submission hooks that will execute on your machine:

  Pre-GUI hooks:
    [1] python3 prefill_from_shotgrid.py

  Pre-submission hooks:
    [1] python3 validate_assets.py

  Post-submission hooks:
    [1] python3 notify.py

  Bundle: /path/to/bundle

Do you want to run these hooks? [Y/n]

CI/자동화 워크플로에 대한 확인 프롬프트를 건너뛰려면 다음 명령을 실행합니다.


deadline config set settings.auto_accept true

구성 설정 요약

설정	기본값	설명
`settings.allow_bundle_hooks`	`false`	작업 번들 `hooks.yaml` 파일에서 후크를 허용할지 여부를 지정합니다.
`settings.allow_environment_hooks`	`false`	`DEADLINE_HOOKS_DIR` 디렉터리에서 후크를 허용할지 여부를 지정합니다.
`settings.auto_accept`	`false`	확인 프롬프트를 건너뛸지 여부를 지정합니다. CI/자동화 환경에서는 주의해야 합니다.

Studio 배포

파이프라인 기술 책임자는 워크스테이션 간에 환경 후크를 배포하여 모든 아티스트에 대해 자동으로 실행되도록 후크를 구성할 수 있습니다. 스튜디오에 후크 스크립트에 대한 공유 네트워크 위치가 있고 아티스트 워크스테이션을 구성할 수 있는 관리 액세스 권한이 있는 경우이 절차를 사용합니다.

스튜디오의 환경 후크를 배포하려면

환경 후크를 허용하도록 워크스테이션을 구성합니다.
```
deadline config set settings.allow_environment_hooks true
```
각 애플리케이션의 시작 관리자 스크립트DEADLINE_HOOKS_DIR에서를 설정합니다.
```
# blender_launcher.sh
export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
exec blender "$@"
```

지정된 위치에 후크를 생성합니다.


/studio/pipeline/hooks/blender/
├── hooks.yaml
└── validate_scene.py

오류 처리

사전 제출 또는 사전 GUI 후크가 실패하면 오류 출력에 다음 정보가 포함됩니다.

실패한 후크
종료 코드
stdout 및 stderr 출력
제한 시간(후크 제한 시간이 초과된 경우)

제출자는 사용자가 문제를 해결할 때까지 제출을 차단합니다. 제출 후 후크 실패는 경고로 기록되지만 제출된 작업에 영향을 미치지 않습니다.

모범 사례

후크를 빠르게 유지합니다. 적절한 제한 시간을 설정하고 후크에서 장기 실행 작업을 방지합니다.
stderr에 로깅합니다. 사전 GUI 및 사전 제출 후크에서 JSON 출력에 대한 stdout을 예약합니다.
오류를 정상적으로 처리합니다. 사용자가 무엇이 잘못되었는지 식별할 수 있도록 stderr에 명확한 오류 메시지를 제공합니다.
먼저 CLI로 테스트합니다. CLI 제출은 GUI 제출보다 디버깅하기 쉽습니다.
출력에 절대 경로를 사용합니다. 자산 참조에 파일을 추가할 때는 항상 절대 경로를 사용합니다.
스튜디오 전체 정책에 환경 후크를 사용합니다. 환경 후크는 번들 작성자가 아닌 스튜디오에서 제어하므로 번들 후크보다 안전합니다.
활성화하기 전에 번들 후크를 검토합니다. hooks.yaml 번들 후크를 실행하기 전에 신뢰할 수 없는 소스의 번들을 검사합니다.

제출 방법

후크는 다음 제출 방법으로 작동합니다.

deadline bundle submit (CLI) - 사전 제출 및 사후 제출 후크가 실행됩니다. CLI에는 GUI 단계가 없으므로 사전 GUI 후크가 적용되지 않습니다.
deadline bundle gui-submit (독립 실행형 GUI) - 사전 GUI 후크를 포함하여 모든 단계가 실행됩니다.
애플리케이션 내(DCC) 제출자 - 제출 전 및 제출 후 후크가 실행됩니다. DCC 제출자는 사전 GUI 단계를 호출하지 않습니다.

독립 실행형 GUI는 작업 기록 번들hooks.yaml에 복사하고 스크립트 경로를 원래 번들 디렉터리로 다시 확인합니다.

통합 지점 및 관련 주제에 대한 자세한 내용은 다음을 참조하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

후크 및 통합 지점

고객 관리형 플릿