翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 送信フック
<a name="submission-hooks"></a>

送信フックを使用すると、Deadline Cloud ジョブ送信ワークフロー中にカスタムスクリプトを実行できます。フックは、ジョブが Deadline Cloud サービスに到達する前に、ジョブを送信しているワークステーションでローカルに実行されます。フックはワーカーや AWS クラウドでは実行されません。フックはマシンで実行されるため、送信するユーザーが利用できるローカルファイル、環境変数、ネットワークリソースにアクセスできます。

フックを使用して、ジョブ設定の検証、追加のアセットの検出、送信パラメータの変更、本番追跡ソフトウェアなどの外部システムとの統合を行うことができます。ワーカーまたはクラウドで実行されるその他の統合ポイントについては、「」を参照してください[ジョブのフック、イベント、統合ポイント](integration-points.md)。

フックを設定する方法は 2 つあります。
+ **バンドルフック** – (`hooks.yaml`または `hooks.json`) ファイルを とともにジョブバンドルディレクトリに配置します`template.yaml`。バンドルフックは、送信前にバンドルが既に存在する CLI ワークフローに適しています。
+ **環境フック** – `DEADLINE_HOOKS_DIR`環境変数を を含むディレクトリにポイントします`hooks.yaml`。環境フックは、ジョブバンドルを変更せずにすべての送信にフックを適用するスタジオに役立ちます。

両方のソースを同時にアクティブにできます。両方が存在する場合、環境フックが最初に実行され、次にバンドルフックが実行されます。

**注記**  
Maya、Nuke、Blender などのアプリケーション内 (DCC) 送信者は、送信前フェーズと送信後フェーズでのみ環境フックを実行します。GUI 前フェーズは DCC 送信者には適用されません。詳細については、「[事前 GUI フック](#submission-hooks-pre-gui)」を参照してください。

## フックタイプ
<a name="submission-hooks-types"></a>

Deadline Cloud は、送信ワークフローの異なるポイントに対応する 3 つのフックタイプをサポートしています。

### 事前 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))
```

次の表に、GUI 以前のフックの出力フィールドを示します。


| フィールド | タイプ | 説明 | 
| --- | --- | --- | 
| `name` | 文字列 | ジョブ名フィールドを事前に入力します。 | 
| `description` | String | ジョブの説明フィールドを事前に入力します。 | 
| `parameters` | オブジェクト | パラメータ値を名前で事前入力します。ジョブテンプレートパラメータは、名前を直接使用します。共有ジョブプロパティは `deadline:`プレフィックスを使用します。 | 

次の表は、 `parameters` オブジェクトの `deadline:` プレフィックスで設定できる共有ジョブプロパティを示しています。


| キー | 型 | 説明 | 
| --- | --- | --- | 
| `deadline:priority` | 整数 | Priority (0～100)。 | 
| `deadline:maxFailedTasksCount` | 整数 | ジョブが失敗する前に失敗したタスクの最大数。 | 
| `deadline:maxRetriesPerTask` | 整数 | 失敗したタスクあたりの最大再試行回数。 | 
| `deadline:maxWorkerCount` | 整数 | 最大同時ワーカー数。 | 
| `deadline:targetTaskRunStatus` | String | 初期タスクのステータス: `READY`または `SUSPENDED`。 | 

**注記**  
CLI で指定された`--parameter`値は、フックで指定された よりも優先されます`parameters`。

### 送信前フック
<a name="submission-hooks-pre-submission"></a>

ジョブアタッチメントがハッシュされてアップロードされる前に、送信前フックが実行されます。次のタスクには、送信前フックを使用できます。
+ ジョブ設定の検証
+ 追加の入力ファイルを検出して追加する
+ 優先度などのジョブパラメータを変更する
+ スタジオポリシーを適用する

送信前フックは、失敗した場合に送信をブロックします (ゼロ以外の終了コードまたはタイムアウト）。

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`値はジョブバンドルディレクトリに対して解決されます。

### 送信後のフック
<a name="submission-hooks-post-submission"></a>

送信後フックは、`CreateJob`API コールが正常に返された後に実行されます。この時点で、ジョブは Deadline Cloud によって承認されています。次のタスクには、送信後フックを使用できます。
+ 通知の送信 (Slack、E メール)
+ 追跡システムを更新する
+ ログ送信の詳細

送信後のフックの失敗は警告として記録されますが、送信されたジョブには影響しません。

## 送信フックを設定する
<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>

各フックエントリは、次のフィールドを受け入れます。


| フィールド | [Required] (必須) | デフォルト | [Description] (説明) | 
| --- | --- | --- | --- | 
| `command` | はい | – | 実行可能ファイルまたはインタープリタ ( `python3`や など`bash`)。 | 
| `args` | いいえ | `[]` | コマンドライン引数。 | 
| `timeout` | いいえ | `60` | 秒単位の最大実行時間。 | 
| `env` | いいえ | `{}` | 追加の環境変数。フックは送信者の完全な環境を継承します。`DEADLINE_*` 変数とフック固有の`env`値は、上にレイヤー化されます。 | 

### パスの解決
<a name="submission-hooks-path-resolution"></a>

フックスクリプトは、次のルールに従って解決されます。
+ **絶対パス** – そのまま使用されます。
+ **相対パス** – ジョブバンドルディレクトリに対する相対パスを解決しました。
+ **コマンド名** – システム PATH で検索されます。

## フック入力
<a name="submission-hooks-input"></a>

フックは、stdin の JSON と便利な環境変数を介してジョブメタデータを受け取ります。

### 環境変数
<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>

完全なメタデータは 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": {}
}
```

## セキュリティ
<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>

パイプラインのテクニカルディレクターは、ワークステーション間で環境フックをデプロイすることで、すべてのアーティストに対して自動的に実行されるようにフックを設定できます。この手順は、スタジオにフックスクリプトの共有ネットワークロケーションがあり、アーティストワークステーションを設定するための管理アクセス権がある場合に使用します。

**スタジオの環境フックをデプロイするには**

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 にログインします。**stdout for JSON output in pre-GUI and pre-submission hooks。
+ **エラーを適切に処理します。**ユーザーが問題を特定できるように、stderr で明確なエラーメッセージを提供します。
+ **最初に CLI でテストします。**CLI 送信は、GUI 送信よりもデバッグが容易です。
+ **出力で絶対パスを使用します。**アセット参照にファイルを追加するときは、常に絶対パスを使用します。
+ **スタジオ全体のポリシーに環境フックを使用します。**環境フックは、バンドル作成者ではなくスタジオによって制御されるため、バンドルフックよりも安全です。
+ **有効にする前にバンドルフックを確認します。**バンドルフックの実行を許可する前に、信頼できないソースからバンドル`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)
+ [Deadline Cloud にジョブを送信する方法](submit-jobs-how.md)
+ [Deadline Cloud に送信するジョブを構築する](building-jobs.md)
+ GitHub ウェブサイトの [deadline-cloud](https://github.com/aws-deadline/deadline-cloud) リポジトリ