本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 提交掛鉤
<a name="submission-hooks"></a>

提交掛鉤可讓您在截止日期雲端任務提交工作流程期間執行自訂指令碼。在任務到達截止日期雲端服務之前，勾點會在提交任務的工作站本機執行。勾點不會在工作者或 AWS 雲端中執行。由於掛鉤在您的機器上執行，因此它們可以存取提交使用者可用的本機檔案、環境變數和網路資源。

您可以使用勾點來驗證任務組態、探索其他資產、修改提交參數，或與生產追蹤軟體等外部系統整合。如需在工作者或雲端上執行的其他整合點，請參閱 [任務的勾點、事件和整合點](integration-points.md)。

有兩種方式可以設定勾點：
+ **套件掛鉤** – 將 `hooks.yaml`（或 `hooks.json`) 檔案與 放在您的任務套件目錄中`template.yaml`。套件掛鉤適用於套件在提交之前已存在的 CLI 工作流程。
+ **環境掛鉤** – 將`DEADLINE_HOOKS_DIR`環境變數指向包含 的目錄`hooks.yaml`。環境勾點對於希望在所有提交中強制執行勾點而不修改任務套件的工作室來說非常有用。

兩個來源可以同時處於作用中狀態。當兩者都存在時，環境掛鉤會先執行，然後綁定掛鉤。

**注意**  
僅針對提交前和提交後階段的應用程式內 (DCC) 提交者，例如 Maya、Nuke 或 Blender 執行環境掛鉤。GUI 前階段不適用於 DCC 提交者。如需詳細資訊，請參閱[GUI 前勾點](#submission-hooks-pre-gui)。

## 勾點類型
<a name="submission-hooks-types"></a>

Deadline Cloud 支援對應至提交工作流程中不同點的三種掛接類型。

### GUI 前勾點
<a name="submission-hooks-pre-gui"></a>

提交對話方塊開啟之前，會執行 GUI 前勾點。您可以針對下列任務使用 GUI 前勾點：

**重要**  
GUI 前勾點只會與獨立 GUI 提交器 () 一起執行`deadline bundle gui-submit`。它們不會在 Maya、Nuke 或 Blender 等應用程式內 (DCC) 提交者中執行，因為這些應用程式會直接建置其提交對話方塊，而不會叫用 GUI 前階段。GUI 前勾點也不適用於沒有 GUI 階段的 CLI 提交 (`deadline bundle submit`)。提交前和提交後掛鉤適用於所有提交方法。
+ 預先填入任務名稱、描述和優先順序
+ 根據目前的場景或管道內容設定參數預設值
+ 查詢專案管理系統以取得任務中繼資料

如果對話方塊失敗 （非零結束碼或逾時），前置 GUI 掛鉤會封鎖對話方塊開啟。

將 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))
```

下表說明 pre-GUI 勾點的輸出欄位。


| 欄位 | Type | Description | 
| --- | --- | --- | 
| `name` | String | 預先填入任務名稱欄位。 | 
| `description` | String | 預先填入任務描述欄位。 | 
| `parameters` | 物件 | 依名稱預先填入參數值。任務範本參數會直接使用其名稱。共用任務屬性使用 `deadline:`字首。 | 

下表說明您可以在 `parameters` 物件中使用 `deadline:`字首設定的共用任務屬性。


| 金錀 | Type | 說明 | 
| --- | --- | --- | 
| `deadline:priority` | Integer | 優先順序 (0–100)。 | 
| `deadline:maxFailedTasksCount` | Integer | 任務失敗前的失敗任務上限。 | 
| `deadline:maxRetriesPerTask` | Integer | 每個失敗任務的重試次數上限。 | 
| `deadline:maxWorkerCount` | Integer | 並行工作者上限。 | 
| `deadline:targetTaskRunStatus` | String | 初始任務狀態： `READY`或 `SUSPENDED`。 | 

**注意**  
CLI 提供的`--parameter`值優先於勾點提供的 `parameters`。

### 提交前掛鉤
<a name="submission-hooks-pre-submission"></a>

預先提交掛鉤會在任務連接雜湊並上傳之前執行。您可以針對下列任務使用預先提交掛鉤：
+ 驗證任務組態
+ 探索並新增其他輸入檔案
+ 修改任務參數，例如優先順序
+ 強制執行 Studio 政策

如果失敗 （非零結束碼或逾時），預先提交掛鉤區塊提交。

將 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 上發出的參數必須是絕對的。勾點不會從提交 shell 的工作目錄執行，因此 stdout 上的相對`PATH`值不明確，且會因錯誤而被拒絕。發出絕對路徑 （例如，加入 `DEADLINE_JOB_BUNDLE_DIR`)，或改為將值寫入磁碟上的 `parameter_values.yaml`/`parameter_values.json`，其中相對值`PATH`會針對任務套件目錄解析。

### 提交後掛鉤
<a name="submission-hooks-post-submission"></a>

提交後掛鉤會在 `CreateJob` API 呼叫成功傳回後執行。Deadline Cloud 此時已接受任務。您可以針對下列任務使用提交後掛鉤：
+ 傳送通知 (Slack、電子郵件）
+ 更新追蹤系統
+ 日誌提交詳細資訊

提交後掛鉤失敗會記錄為警告，但不會影響提交的任務。

## 設定提交掛鉤
<a name="submission-hooks-configuration"></a>

在 `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/...
```

### 勾點定義欄位
<a name="submission-hooks-definition-fields"></a>

每個勾點項目接受下列欄位。


| 欄位 | 必要 | 預設 | 說明 | 
| --- | --- | --- | --- | 
| `command` | 是 | – | 可執行檔或解譯器 （例如， `python3`或 `bash`)。 | 
| `args` | 否 | `[]` | 命令列引數。 | 
| `timeout` | 否 | `60` | 最長執行時間，以秒為單位。 | 
| `env` | 否 | `{}` | 其他環境變數。勾點會繼承提交者的完整環境。`DEADLINE_*` 變數和任何勾點特定`env`值都會分層在頂端。 | 

### 路徑解析
<a name="submission-hooks-path-resolution"></a>

掛鉤指令碼會根據下列規則解析：
+ **絕對路徑** – 依原狀使用。
+ **相對路徑** – 已相對於任務套件目錄解析。
+ **命令名稱** – 在系統 PATH 中搜尋。

## 勾點輸入
<a name="submission-hooks-input"></a>

勾點透過 JSON on stdin 和便利環境變數接收任務中繼資料。

### 環境變數
<a name="submission-hooks-env-vars"></a>

下列環境變數適用於所有勾點。


| 變數 | 說明 | 
| --- | --- | 
| `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
<a name="submission-hooks-json-stdin"></a>

完整中繼資料會以 JSON on stdin 的形式提供。下列範例顯示 結構：

```
{
  "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": {}
}
```

## 安全
<a name="submission-hooks-security"></a>

掛鉤預設為停用。每個掛接來源都有自己的設定，您必須啟用。

### 啟用套件掛鉤
<a name="submission-hooks-enable-bundle"></a>

若要允許任務套件`hooks.yaml`內在 中定義的掛鉤，請啟用套件掛鉤設定。

**啟用套件掛鉤**
+ 執行以下命令：

  ```
  deadline config set settings.allow_bundle_hooks true
  ```

### 啟用環境掛鉤
<a name="submission-hooks-enable-environment"></a>

若要允許來自 指定目錄的掛鉤`DEADLINE_HOOKS_DIR`，請啟用環境掛鉤設定並設定目錄路徑。

**啟用環境掛鉤**

1. 啟用 設定：

   ```
   deadline config set settings.allow_environment_hooks true
   ```

1. 設定環境變數，通常在應用程式啟動器指令碼中：

   ```
   export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
   ```

### 確認提示
<a name="submission-hooks-confirmation"></a>

當您啟用掛鉤時，提交者會在掛鉤執行之前提示您確認。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
```

### 組態設定摘要
<a name="submission-hooks-config-summary"></a>


| 設定 | 預設 | 說明 | 
| --- | --- | --- | 
| `settings.allow_bundle_hooks` | `false` | 指定是否允許來自任務套件`hooks.yaml`檔案的勾點。 | 
| `settings.allow_environment_hooks` | `false` | 指定是否允許來自 `DEADLINE_HOOKS_DIR` 目錄的勾點。 | 
| `settings.auto_accept` | `false` | 指定是否略過確認提示。在 CI/自動化環境中謹慎使用 。 | 

## Studio 部署
<a name="submission-hooks-studio-deployment"></a>

管道技術主管可以透過跨工作站部署環境勾點，將勾點設定為自動為所有藝術家執行。當您的 Studio 具有掛接指令碼的共用網路位置，而且您具有設定藝術家工作站的管理存取權時，請使用此程序。

**部署 Studio 的環境勾點**

1. 設定工作站以允許環境掛鉤：

   ```
   deadline config set settings.allow_environment_hooks true
   ```

1. 在每個應用程式的啟動器指令碼`DEADLINE_HOOKS_DIR`中設定：

   ```
   # blender_launcher.sh
   export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
   exec blender "$@"
   ```

1. 在指定位置建立掛鉤：

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

## 錯誤處理
<a name="submission-hooks-error-handling"></a>

當預先提交或預先 GUI 勾點失敗時，錯誤輸出會包含下列資訊：
+ 哪個勾點失敗
+ 結束程式碼
+ stdout 和 stderr 輸出
+ 逾時持續時間 （如果勾點逾時）

提交者會封鎖提交，直到您解決問題為止。提交後掛鉤失敗會記錄為警告，但不會影響提交的任務。

## 最佳實務
<a name="submission-hooks-best-practices"></a>
+ **保持快速掛鉤。**設定適當的逾時，並避免勾點中長時間執行的操作。
+ **記錄到 stderr。**在 GUI 前和提交前掛鉤中預留 JSON 輸出的 stdout。
+ **正常處理錯誤。**在 stderr 上提供明確的錯誤訊息，讓使用者可以識別錯誤。
+ **首先使用 CLI 進行測試。**CLI 提交比 GUI 提交更容易偵錯。
+ **在輸出中使用絕對路徑。**將檔案新增至資產參考時，請一律使用絕對路徑。
+ **使用全工作室政策的環境勾點。**環境勾點比套件勾點更安全，因為它們是由 Studio 控制，而不是套件作者。
+ **啟用之前，請先檢閱套件掛鉤。**在允許套件掛鉤執行之前，`hooks.yaml`檢查來自不受信任來源的套件。

## 提交方法
<a name="submission-hooks-cli-gui"></a>

勾點使用下列提交方法：
+ `deadline bundle submit` (CLI) – 提交前和提交後掛鉤執行。CLI 沒有 GUI 階段，因此不適用預 GUI 掛鉤。
+ `deadline bundle gui-submit` （獨立 GUI) – 所有階段都會執行，包括預先 GUI 掛鉤。
+ 應用程式內 (DCC) 提交者 – 提交前和提交後掛鉤執行。DCC 提交者不會叫用 GUI 前階段。

獨立 GUI `hooks.yaml`會複製到任務歷史記錄套件，並將指令碼路徑解析回原始套件目錄。

## 其他資源
<a name="submission-hooks-related"></a>

如需整合點和相關主題的詳細資訊，請參閱下列內容：
+ [任務的勾點、事件和整合點](integration-points.md)
+ [如何將任務提交至截止日期雲端](submit-jobs-how.md)
+ [建置任務以提交至截止日期雲端](building-jobs.md)
+ GitHub 網站上的 [deadline-cloud](https://github.com/aws-deadline/deadline-cloud) 儲存庫