As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Ganchos de envio
Os ganchos de envio permitem que você execute scripts personalizados durante o fluxo de trabalho de envio de trabalhos do Deadline Cloud. Os ganchos são executados localmente na estação de trabalho que está enviando o trabalho, antes que o trabalho chegue ao serviço Deadline Cloud. Os ganchos não funcionam em trabalhadores ou na AWS nuvem. Como os ganchos são executados em sua máquina, eles têm acesso a arquivos locais, variáveis de ambiente e recursos de rede disponíveis para o usuário remetente.
Você pode usar ganchos para validar configurações de tarefas, descobrir ativos adicionais, modificar parâmetros de envio ou integrar-se a sistemas externos, como software de rastreamento de produção. Para outros pontos de integração que são executados em trabalhadores ou na nuvem, consulte[Ganchos, eventos e pontos de integração para trabalhos](integration-points.md).
Há duas maneiras de configurar ganchos:
+ **Ganchos de pacote** — Coloque um `hooks.yaml` (ou`hooks.json`) arquivo no diretório do pacote de tarefas ao lado. `template.yaml` Os ganchos de pacote funcionam bem para fluxos de trabalho de CLI em que o pacote já existe antes do envio.
+ **Ganchos de ambiente** — Aponte a variável de `DEADLINE_HOOKS_DIR` ambiente para um diretório que contém`hooks.yaml`. Os ganchos de ambiente são úteis para estúdios que desejam aplicar restrições em todos os envios sem modificar os pacotes de tarefas.
Ambas as fontes podem estar ativas ao mesmo tempo. Quando ambos estão presentes, os ganchos de ambiente são executados primeiro e depois os ganchos de agrupamento.
**nota**
In-application Os remetentes (DCC), como Maya, Nuke ou Blender, usam ganchos ambientais somente para as fases de pré-envio e pós-envio. A fase pré-GUI não se aplica aos remetentes do DCC. Para obter mais informações, consulte [Pre-GUI ganchos](#submission-hooks-pre-gui).
## Tipos de ganchos
O Deadline Cloud suporta três tipos de ganchos que correspondem a pontos diferentes no fluxo de trabalho de envio.
### Pre-GUI ganchos
Pre-GUI os ganchos são executados antes que a caixa de diálogo de envio seja aberta. Você pode usar ganchos pré-GUI para as seguintes tarefas:
**Importante**
Pre-GUI os ganchos são executados somente com o remetente autônomo da GUI (). `deadline bundle gui-submit` Eles não são executados em remetentes no aplicativo (DCC), como Maya, Nuke ou Blender, porque esses aplicativos criam sua caixa de diálogo de envio diretamente e não invocam a fase pré-GUI. Pre-GUI os ganchos também não se aplicam ao envio da CLI `deadline bundle submit` (), que não tem fase de GUI. Pre-submission e os ganchos de pós-envio funcionam em todos os métodos de envio.
+ Pre-populate nome do trabalho, descrição e prioridade
+ Defina padrões de parâmetros com base na cena atual ou no contexto do pipeline
+ Consulte um sistema de gerenciamento de projetos para obter metadados de tarefas
Pre-GUI os ganchos impedem a abertura da caixa de diálogo se falharem (código de saída diferente de zero ou tempo limite).
Envie JSON para stdout para modificar o estado inicial da caixa de diálogo. O exemplo a seguir mostra o formato de saída:
```
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))
```
A tabela a seguir descreve os campos de saída para ganchos pré-GUI.
| Campo | Tipo | Description |
| --- | --- | --- |
| `name` | String | Pre-fills o campo do nome do trabalho. |
| `description` | String | Pre-fills o campo de descrição do trabalho. |
| `parameters` | Objeto | Pre-fills valores de parâmetros por nome. Os parâmetros do modelo de trabalho usam seus nomes diretamente. As propriedades de trabalho compartilhadas usam o `deadline:` prefixo. |
A tabela a seguir descreve as propriedades da tarefa compartilhada que você pode definir com o `deadline:` prefixo no `parameters` objeto.
| Chave | Tipo | Description |
| --- | --- | --- |
| `deadline:priority` | Inteiro | Prioridade (0—100). |
| `deadline:maxFailedTasksCount` | Inteiro | Máximo de tarefas com falha antes que o trabalho falhe. |
| `deadline:maxRetriesPerTask` | Inteiro | Máximo de tentativas por tarefa com falha. |
| `deadline:maxWorkerCount` | Inteiro | Máximo de trabalhadores simultâneos. |
| `deadline:targetTaskRunStatus` | String | Status inicial da tarefa: `READY` ou`SUSPENDED`. |
**nota**
CLI-supplied `--parameter`os valores têm precedência sobre os fornecidos pelo gancho`parameters`.
### Pre-submission ganchos
Pre-submission os ganchos são executados antes que os anexos do trabalho sejam criptografados e enviados. Você pode usar ganchos de pré-envio para as seguintes tarefas:
+ Validar a configuração do trabalho
+ Descubra e adicione arquivos de entrada adicionais
+ Modifique os parâmetros do trabalho, como prioridade
+ Aplique as políticas do estúdio
Pre-submission os ganchos bloqueiam o envio se falharem (código de saída diferente de zero ou tempo limite).
Envie JSON para stdout para modificar o envio. A saída do gancho substitui as referências de ativos no nível da chave aninhada. Se suas saídas de gancho`inputFilenames`, a saída de gancho substitui a lista inteira`inputFilenames`. O Deadline Cloud preserva as chaves que você não inclui na sua saída.
O exemplo a seguir adiciona arquivos de textura descobertos ao envio:
```
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 os ganchos também podem modificar os valores dos parâmetros do modelo de trabalho emitindo um `parameters` mapa no stdout:
```
print(json.dumps({"parameters": {"SceneFile": "/resolved/scene.ma", "Quality": "high"}}))
```
As chaves de parâmetros são nomes de parâmetros do modelo de trabalho. Os valores de um gancho são aplicados sobre os valores dos parâmetros do pacote, mas os CLI-supplied `--parameter` valores ainda têm precedência sobre os fornecidos pelo gancho.
**Importante**
`PATH`os parâmetros emitidos no stdout devem ser absolutos. Um gancho não é executado a partir do diretório de trabalho do shell de envio, portanto, um `PATH` valor relativo em stdout é ambíguo e é rejeitado com um erro. Em vez disso, emita um caminho absoluto (por exemplo, join with`DEADLINE_JOB_BUNDLE_DIR`) ou grave o valor `parameter_values.json` em`parameter_values.yaml`/no disco, onde um relativo `PATH` é resolvido no diretório do pacote de tarefas.
### Post-submission ganchos
Post-submission os ganchos são executados após o retorno bem-sucedido `CreateJob` da chamada da API. O trabalho foi aceito pela Deadline Cloud neste momento. Você pode usar ganchos de pós-envio para as seguintes tarefas:
+ Enviar notificações (Slack, e-mail)
+ Atualize os sistemas de rastreamento
+ Detalhes do envio do log
Post-submission falhas de gancho são registradas como avisos, mas não afetam o trabalho enviado.
## Configurar ganchos de envio
Defina ganchos em um `hooks.json` arquivo `hooks.yaml` or. Coloque o arquivo no diretório do pacote de tarefas ao lado `template.yaml` ou no diretório especificado por`DEADLINE_HOOKS_DIR`. Se os dois formatos existirem no mesmo diretório, o remetente relatará um erro.
O `version` campo é obrigatório e deve ser`"1.0"`.
O exemplo a seguir mostra uma `hooks.yaml` configuração:
```
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/...
```
### Campos de definição de gancho
Cada entrada de gancho aceita os seguintes campos.
| Campo | Obrigatório | Padrão | Description |
| --- | --- | --- | --- |
| `command` | Sim | – | Executável ou intérprete (por exemplo, `python3` ou`bash`). |
| `args` | Não | `[]` | Command-line argumentos. |
| `timeout` | Não | `60` | Tempo máximo de execução em segundos. |
| `env` | Não | `{}` | Variáveis de ambiente adicionais. Os ganchos herdam o ambiente completo do remetente. As `DEADLINE_*` variáveis e quaisquer `env` valores específicos do gancho são colocados em camadas na parte superior. |
### Resolução de caminho
Os scripts de gancho são resolvidos de acordo com as seguintes regras:
+ **Caminhos absolutos** — usados no estado em que se encontram.
+ **Caminhos relativos** — Resolvidos em relação ao diretório do pacote de tarefas.
+ **Nomes dos comandos** — Pesquisados no PATH do sistema.
## Entrada de gancho
Os ganchos recebem metadados do trabalho por meio de JSON em stdin e por meio de variáveis de ambiente de conveniência.
### Variáveis de ambiente
As seguintes variáveis de ambiente estão disponíveis para todos os ganchos.
| Variável | Description |
| --- | --- |
| `DEADLINE_JOB_NAME` | Nome do trabalho. |
| `DEADLINE_PRIORITY` | Prioridade de trabalho. |
| `DEADLINE_FARM_ID` | ID da fazenda. |
| `DEADLINE_QUEUE_ID` | ID da fila. |
| `DEADLINE_JOB_BUNDLE_DIR` | Caminho para o diretório do pacote de tarefas. |
| `DEADLINE_STORAGE_PROFILE_ID` | ID do perfil de armazenamento (se definido). |
| `DEADLINE_JOB_ID` | Job ID (somente para ganchos de pós-envio). |
### JSON em stdin
Os metadados completos são fornecidos como JSON no stdin. O exemplo a seguir mostra a estrutura:
```
{
"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": {}
}
```
## Segurança
Os ganchos são desativados por padrão. Cada fonte de gancho tem sua própria configuração que você deve habilitar.
### Ativando ganchos de pacote
Para permitir a definição de ganchos `hooks.yaml` nos pacotes de tarefas, ative a configuração de ganchos do pacote.
**Para habilitar ganchos de pacote**
+ Execute este comando: .
```
deadline config set settings.allow_bundle_hooks true
```
### Habilitando ganchos ambientais
Para permitir ganchos de um diretório especificado por`DEADLINE_HOOKS_DIR`, habilite a configuração de ganchos de ambiente e defina o caminho do diretório.
**Para habilitar ganchos de ambiente**
1. Ative a configuração:
```
deadline config set settings.allow_environment_hooks true
```
1. Defina a variável de ambiente, normalmente em um script de inicialização de aplicativos:
```
export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
```
### Prompt de confirmação
Quando você ativa os ganchos, o remetente solicita que você confirme antes que os ganchos sejam executados. Pre-GUI os ganchos mostram o prompt antes que a caixa de diálogo seja aberta. Pre-submission e os ganchos de pós-envio mostram a solicitação quando você escolhe Enviar.
O prompt mostra quais comandos serão executados, permitindo que você revise antes de continuar:
```
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]
```
Para ignorar as solicitações de confirmação dos CI/automation fluxos de trabalho, execute o seguinte comando:
```
deadline config set settings.auto_accept true
```
### Resumo das configurações
| Configuração | Padrão | Description |
| --- | --- | --- |
| `settings.allow_bundle_hooks` | `false` | Especifica se devem ser permitidos ganchos do arquivo do pacote `hooks.yaml` de tarefas. |
| `settings.allow_environment_hooks` | `false` | Especifica se os ganchos do diretório devem ser permitidos. `DEADLINE_HOOKS_DIR` |
| `settings.auto_accept` | `false` | Especifica se as solicitações de confirmação devem ser ignoradas. Use com cuidado em CI/automation ambientes. |
## Implantação do Studio
Os diretores técnicos do Pipeline podem configurar ganchos para serem executados automaticamente para todos os artistas, implantando ganchos de ambiente em todas as estações de trabalho. Use esse procedimento quando seu estúdio tiver um local de rede compartilhado para scripts de gancho e você tiver acesso administrativo para configurar estações de trabalho de artistas.
**Para implantar ganchos de ambiente para um estúdio**
1. Configure estações de trabalho para permitir ganchos ambientais:
```
deadline config set settings.allow_environment_hooks true
```
1. Defina `DEADLINE_HOOKS_DIR` no script de inicialização de cada aplicativo:
```
# blender_launcher.sh
export DEADLINE_HOOKS_DIR=/studio/pipeline/hooks/blender
exec blender "$@"
```
1. Crie os ganchos no local especificado:
```
/studio/pipeline/hooks/blender/
├── hooks.yaml
└── validate_scene.py
```
## Tratamento de erros
Quando um gancho de pré-envio ou pré-GUI falha, a saída de erro inclui as seguintes informações:
+ Qual gancho falhou
+ Código de saída
+ saída stdout e stderr
+ Duração do tempo limite (se o gancho tiver atingido o tempo limite)
O remetente bloqueia o envio até que você resolva o problema. Post-submission falhas de gancho são registradas como avisos, mas não afetam o trabalho enviado.
## Práticas recomendadas
+ **Mantenha os ganchos rápidos.** Defina tempos limite apropriados e evite operações de longa duração em ganchos.
+ **Faça login em stderr.** Reserve stdout para saída JSON em ganchos pré-GUI e pré-envio.
+ **Lide com os erros com elegância.** Forneça mensagens de erro claras no stderr para que os usuários possam identificar o que deu errado.
+ **Teste primeiro com a CLI.** O envio da CLI é mais fácil de depurar do que o envio da GUI.
+ **Use caminhos absolutos na saída.** Ao adicionar arquivos às referências de ativos, sempre use caminhos absolutos.
+ **Use ganchos ambientais para políticas em todo o estúdio.** Os ganchos de ambiente são mais seguros do que os ganchos de pacote porque são controlados pelo estúdio e não pelo autor do pacote.
+ **Revise os ganchos do pacote antes de ativar.** Inspecione pacotes `hooks.yaml` de fontes não confiáveis antes de permitir que os ganchos de pacote sejam executados.
## Métodos de envio
Os ganchos funcionam com os seguintes métodos de envio:
+ `deadline bundle submit`(CLI) — Pre-submission e os ganchos de pós-envio são executados. A CLI não tem fase de GUI, portanto, ganchos pré-GUI não se aplicam.
+ `deadline bundle gui-submit`(GUI autônoma) — Todas as fases são executadas, incluindo ganchos pré-GUI.
+ In-application (DCC) remetentes — Pre-submission e ganchos de pós-envio funcionam. Os remetentes do DCC não invocam a fase pré-GUI.
A GUI autônoma copia `hooks.yaml` para o pacote de histórico de tarefas e resolve os caminhos do script de volta para o diretório original do pacote.
## Recursos adicionais do
Para obter mais informações sobre pontos de integração e tópicos relacionados, consulte o seguinte:
+ [Ganchos, eventos e pontos de integração para trabalhos](integration-points.md)
+ [Como enviar uma vaga para o Deadline Cloud](submit-jobs-how.md)
+ [Crie trabalhos para enviar ao Deadline Cloud](building-jobs.md)
+ repositório de [nuvem de prazos](https://github.com/aws-deadline/deadline-cloud) no site GitHub