Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Ganci di invio Gli hook di invio consentono di eseguire script personalizzati durante il flusso di lavoro di invio dei lavori di Deadline Cloud. Gli hook vengono eseguiti localmente sulla workstation che invia il lavoro, prima che il lavoro raggiunga il servizio Deadline Cloud. Gli hook non vengono eseguiti sui lavoratori o nel cloud. AWS Poiché gli hook vengono eseguiti sulla macchina, hanno accesso ai file locali, alle variabili di ambiente e alle risorse di rete disponibili per l'utente che li invia. È possibile utilizzare gli hook per convalidare le configurazioni dei lavori, scoprire risorse aggiuntive, modificare i parametri di invio o effettuare l'integrazione con sistemi esterni come il software di tracciamento della produzione. Per altri punti di integrazione che funzionano sui lavoratori o nel cloud, consulta. [Ganci, eventi e punti di integrazione per le offerte di lavoro](integration-points.md) Esistono due modi per configurare gli hook: + **Bundle hook**: inserisci accanto un `hooks.yaml` (o`hooks.json`) file nella directory dei job bundle. `template.yaml` I bundle hook funzionano bene per i flussi di lavoro CLI in cui il pacchetto esiste già prima dell'invio. + **Environment hook: indirizza** la variabile di `DEADLINE_HOOKS_DIR` ambiente su una directory che contiene. `hooks.yaml` Gli Environment Hook sono utili per gli studi che desiderano applicare gli hook a tutti gli invii senza modificare i job bundle. Entrambe le fonti possono essere attive contemporaneamente. Quando entrambe sono presenti, vengono eseguiti prima gli hook di ambiente, quindi i bundle hook. **Nota** In-application i mittenti (DCC) come Maya, Nuke o Blender eseguono gli hook ambientali solo per le fasi precedenti e successive all'invio. La fase precedente alla GUI non si applica ai mittenti DCC. Per ulteriori informazioni, consulta [Pre-GUI ganci](#submission-hooks-pre-gui). ## Tipi di ganci Deadline Cloud supporta tre tipi di hook che corrispondono a diversi punti del flusso di lavoro di invio. ### Pre-GUI ganci Pre-GUI gli hook vengono eseguiti prima dell'apertura della finestra di dialogo di invio. È possibile utilizzare gli hook pre-GUI per le seguenti attività: **Importante** Pre-GUI gli hook funzionano solo con l'interfaccia grafica standalone submitter (). `deadline bundle gui-submit` Non vengono eseguiti in programmi di invio in-application (DCC) come Maya, Nuke o Blender, perché tali applicazioni creano direttamente la finestra di dialogo di invio e non richiamano la fase pre-GUI. Pre-GUI gli hook non si applicano inoltre all'invio della CLI `deadline bundle submit` (), che non ha una fase GUI. Pre-submission e gli hook post-invio funzionano con tutti i metodi di invio. + Pre-populate nome, descrizione e priorità del lavoro + Imposta i parametri predefiniti in base alla scena corrente o al contesto della pipeline + Interroga un sistema di gestione dei progetti per i metadati delle attività Pre-GUI gli hook bloccano l'apertura della finestra di dialogo in caso di errore (codice di uscita diverso da zero o timeout). Invia JSON su stdout per modificare lo stato iniziale della finestra di dialogo. L'esempio seguente mostra il formato di output: ``` 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)) ``` La tabella seguente descrive i campi di output per gli hook precedenti alla GUI. | Campo | Tipo | Description | | --- | --- | --- | | `name` | Stringa | Pre-fills il campo del nome del lavoro. | | `description` | Stringa | Pre-fills il campo della descrizione del lavoro. | | `parameters` | Oggetto | Pre-fills valori dei parametri per nome. I parametri del modello Job utilizzano direttamente il loro nome. Le proprietà condivise del lavoro utilizzano il `deadline:` prefisso. | La tabella seguente descrive le proprietà del lavoro condiviso che è possibile impostare con il `deadline:` prefisso nell'`parameters`oggetto. | Chiave | Tipo | Description | | --- | --- | --- | | `deadline:priority` | Numero intero | Priorità (0—100). | | `deadline:maxFailedTasksCount` | Numero intero | Numero massimo di attività non riuscite prima del fallimento del processo. | | `deadline:maxRetriesPerTask` | Numero intero | Numero massimo di tentativi per operazione non riuscita. | | `deadline:maxWorkerCount` | Numero intero | Numero massimo di lavoratori simultanei. | | `deadline:targetTaskRunStatus` | Stringa | Stato dell'attività iniziale: `READY` o`SUSPENDED`. | **Nota** CLI-supplied `--parameter`i valori hanno la precedenza su quelli forniti dal gancio`parameters`. ### Pre-submission ganci Pre-submission gli hook vengono eseguiti prima che gli allegati del lavoro vengano sottoposti a hash e caricati. È possibile utilizzare gli hook di pre-invio per le seguenti attività: + Convalida la configurazione del lavoro + Scopri e aggiungi file di input aggiuntivi + Modifica i parametri del lavoro, come la priorità + Applica le politiche dello studio Pre-submission gli hook bloccano l'invio se falliscono (codice di uscita diverso da zero o timeout). Invia JSON su stdout per modificare l'invio. L'output dell'hook sostituisce i riferimenti alle risorse a livello di chiave annidata. Se l'hook emette`inputFilenames`, l'output dell'hook sostituisce l'intero elenco. `inputFilenames` Deadline Cloud conserva le chiavi che non includi nell'output. L'esempio seguente aggiunge i file di texture rilevati all'invio: ``` 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 } } })) ``` Pre-submission gli hook possono anche modificare i valori dei parametri del modello di lavoro emettendo una `parameters` mappa su stdout: ``` print(json.dumps({"parameters": {"SceneFile": "/resolved/scene.ma", "Quality": "high"}})) ``` Le chiavi dei parametri sono nomi dei parametri del modello di lavoro. I valori di un hook vengono applicati sopra i valori dei parametri del pacchetto, ma i valori hanno comunque la precedenza su CLI-supplied `--parameter` quelli forniti dall'hook. **Importante** `PATH`i parametri emessi su stdout devono essere assoluti. Un hook non viene eseguito dalla directory di lavoro della shell di invio, quindi un `PATH` valore relativo su stdout è ambiguo e viene rifiutato con un errore. Emetti un percorso assoluto (ad esempio, join with`DEADLINE_JOB_BUNDLE_DIR`) o scrivi invece il valore `parameter_values.json` su`parameter_values.yaml`/on disk, dove un relativo `PATH` viene risolto nella directory del job bundle. ### Post-submission ganci Post-submission gli hook vengono eseguiti dopo che la chiamata `CreateJob` API è tornata correttamente. Il lavoro è stato accettato da Deadline Cloud a questo punto. Puoi utilizzare gli hook post-invio per le seguenti attività: + Inviare notifiche (Slack, email) + Aggiorna i sistemi di tracciamento + Dettagli di invio del registro Post-submission gli errori degli hook vengono registrati come avvisi ma non influiscono sul lavoro inviato. ## Configura gli hook di invio Definisci gli hook in un `hooks.yaml` file or. `hooks.json` Inserite il file nella directory del job bundle accanto `template.yaml` o nella directory specificata da. `DEADLINE_HOOKS_DIR` Se entrambi i formati esistono nella stessa directory, il mittente segnala un errore. Il `version` campo è obbligatorio e deve esserlo. `"1.0"` L'esempio seguente mostra una `hooks.yaml` configurazione: ``` 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/... ``` ### Campi di definizione degli hook Ogni voce dell'hook accetta i seguenti campi. | Campo | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | | `command` | Sì | – | Eseguibile o interprete (ad esempio `python3` o`bash`). | | `args` | No | `[]` | Command-line argomenti. | | `timeout` | No | `60` | Tempo massimo di esecuzione in secondi. | | `env` | No | `{}` | Variabili di ambiente aggiuntive. Gli hook ereditano l'intero ambiente del mittente. Le `DEADLINE_*` variabili e tutti i valori specifici dell'hook sono sovrapposti`env`. | ### Risoluzione del percorso Gli script Hook vengono risolti in base alle seguenti regole: + **Percorsi assoluti**: usati così come sono. + **Percorsi relativi**: risolti in relazione alla directory del job bundle. + **Nomi dei comandi**: ricerca nel PATH di sistema. ## Input Hook Gli hook ricevono i metadati del lavoro tramite JSON su stdin e tramite variabili di ambiente di convenienza. ### Variabili di ambiente Le seguenti variabili di ambiente sono disponibili per tutti gli hook. | Variabile | Description | | --- | --- | | `DEADLINE_JOB_NAME` | Nome del lavoro. | | `DEADLINE_PRIORITY` | Priorità del lavoro. | | `DEADLINE_FARM_ID` | ID della fattoria. | | `DEADLINE_QUEUE_ID` | ID della coda. | | `DEADLINE_JOB_BUNDLE_DIR` | Percorso della directory del job bundle. | | `DEADLINE_STORAGE_PROFILE_ID` | ID del profilo di archiviazione (se impostato). | | `DEADLINE_JOB_ID` | Job ID (solo hook successivi all'invio). | ### JSON su stdin I metadati completi vengono forniti come JSON su stdin. L'esempio seguente mostra la struttura: ``` { "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": {} } ``` ## Sicurezza Gli hook sono disabilitati per impostazione predefinita. Ogni fonte di hook ha le proprie impostazioni che è necessario abilitare. ### Attivazione dei bundle hook Per consentire gli hook definiti `hooks.yaml` all'interno dei job bundle, abilita l'impostazione bundle hooks. **Per abilitare i bundle hook** + Esegui il comando seguente: ``` deadline config set settings.allow_bundle_hooks true ``` ### Abilitare gli hook ambientali Per consentire gli hook da una directory specificata da`DEADLINE_HOOKS_DIR`, abilita l'impostazione environment hooks e imposta il percorso della directory. **Per abilitare gli hook ambientali** 1. Abilita l'impostazione: ``` deadline config set settings.allow_environment_hooks true ``` 1. Imposta la variabile di ambiente, in genere in uno script di avvio dell'applicazione: ``` export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender ``` ### Prompt di conferma Quando abiliti gli hook, il mittente ti chiede di confermare prima che gli hook vengano eseguiti. Pre-GUI gli hook mostrano il prompt prima dell'apertura della finestra di dialogo. Pre-submission e gli hook post-invio mostrano il prompt quando si sceglie Invia. Il prompt mostra quali comandi verranno eseguiti e consente di esaminarli prima di procedere: ``` 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] ``` Per saltare le richieste di conferma per i CI/automation flussi di lavoro, esegui il comando seguente: ``` deadline config set settings.auto_accept true ``` ### Riepilogo delle impostazioni di configurazione | Impostazione | Predefinita | Description | | --- | --- | --- | | `settings.allow_bundle_hooks` | `false` | Specifica se consentire gli hook dal file del job bundle`hooks.yaml`. | | `settings.allow_environment_hooks` | `false` | Speciifica se consentire gli hook dalla directory. `DEADLINE_HOOKS_DIR` | | `settings.auto_accept` | `false` | Specifica se ignorare le richieste di conferma. Usare con cautela negli ambienti. CI/automation | ## Distribuzione in studio I direttori tecnici di Pipeline possono configurare gli hook in modo che vengano eseguiti automaticamente per tutti gli artisti distribuendo hook ambientali tra le workstation. Usa questa procedura quando il tuo studio dispone di una posizione di rete condivisa per gli hook script e disponi dell'accesso amministrativo per configurare le workstation degli artisti. **Per distribuire hook ambientali per uno studio** 1. Configura le workstation per consentire i collegamenti ambientali: ``` deadline config set settings.allow_environment_hooks true ``` 1. Imposta `DEADLINE_HOOKS_DIR` nello script di avvio di ogni applicazione: ``` # blender_launcher.sh export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender exec blender "$@" ``` 1. Crea gli hook nella posizione specificata: ``` /studio/pipeline/hooks/blender/ ├── hooks.yaml └── validate_scene.py ``` ## Gestione degli errori Quando un hook di pre-invio o precedente alla GUI fallisce, l'output di errore include le seguenti informazioni: + Quale hook non è riuscito + Codice di uscita + output stdout e stderr + Durata del timeout (se il timeout è scaduto) Il mittente blocca l'invio finché non risolvi il problema. Post-submission gli errori degli hook vengono registrati come avvisi ma non influiscono sul lavoro inviato. ## Best practice + **Mantieni i ganci veloci.** Imposta i timeout appropriati ed evita operazioni di lunga durata negli hook. + **Accedi a stderr.** Riserva lo stdout per l'output JSON negli hook pre-GUI e di pre-invio. + **Gestisci gli errori con garbo.** Fornisci messaggi di errore chiari su stderr in modo che gli utenti possano identificare cosa è andato storto. + **Prova prima con la CLI.** L'invio della CLI è più facile da eseguire il debug rispetto all'invio della GUI. + **Usa percorsi assoluti nell'output.** Quando aggiungete file ai riferimenti delle risorse, utilizzate sempre percorsi assoluti. + **Usa gli hook ambientali per le politiche a livello di studio.** Gli Environment Hook sono più sicuri dei bundle hook perché sono controllati dallo studio piuttosto che dall'autore del bundle. + **Controlla i bundle hook prima di attivarli.** `hooks.yaml`Esamina i bundle provenienti da fonti non attendibili prima di consentire l'esecuzione dei bundle hook. ## Metodi di invio Gli hook funzionano con i seguenti metodi di invio: + `deadline bundle submit`(CLI) — Pre-submission e gli hook successivi all'invio vengono eseguiti. La CLI non ha una fase GUI, quindi gli hook precedenti alla GUI non sono applicabili. + `deadline bundle gui-submit`(GUI autonoma): vengono eseguite tutte le fasi, inclusi gli hook pre-GUI. + In-application (DCC) i mittenti e gli hook successivi all'invio vengono eseguiti. Pre-submission I mittenti DCC non richiamano la fase precedente alla GUI. La GUI autonoma copia nel Job History Bundle e risolve i percorsi degli script che riportano `hooks.yaml` alla directory del bundle originale. ## Risorse aggiuntive Per ulteriori informazioni sui punti di integrazione e sugli argomenti correlati, consulta quanto segue: + [Ganci, eventi e punti di integrazione per le offerte di lavoro](integration-points.md) + [Come inviare un'offerta di lavoro a Deadline Cloud](submit-jobs-how.md) + [Crea lavori da inviare a Deadline Cloud](building-jobs.md) + repository [deadline-cloud sul sito](https://github.com/aws-deadline/deadline-cloud) web GitHub