Gatilhos: comandos da CLI

Gatilhos de alerta CAP

Um gatilho permite que um sistema de notificação de emergência, como Everbridge, Rave, Alertus ou um relé IPAWS, assuma telas com alertas CAP 1.2. Cada gatilho tem sua própria URL, nome de usuário e senha, que você insere no sistema de envio como destino CAP HTTP POST com autenticação HTTP Basic. Uma organização tem no máximo 20 gatilhos em todos os seus projetos.

Os gatilhos são de dois tipos. Um gatilho CAP, descrito aqui, recebe os alertas de um sistema de emergência. Um gatilho de sobreposição mostra o que qualquer remetente publica, como o Home Assistant, um hub de sensores ou uma ferramenta de alertas, como uma faixa sobre o que está sendo exibido ou como uma tomada de controle; triggers create --kind overlay cria um, e triggers update, triggers clear e triggers rotate-secret servem aos dois tipos, enquanto triggers deliveries lê o registro de um gatilho de sobreposição.

Um gatilho mira uma tag, resolvida quando cada alerta chega, ou até 500 ids de tela. Cada Alerta vira uma tomada da playlist do gatilho: um cartão em tela cheia na cor da severidade, com evento, manchete, descrição e instrução. Um Exercício adiciona um banner EXERCISE. A tomada dura até o <expires> do alerta, senão o padrão --for do gatilho (1 minuto a 7 dias, 1 hora se não definido), e nunca passa 7 dias. Uma Atualização redesenha o cartão, e um Cancelar ou AllClear devolve cada tela ao que tocava antes. Um novo Alerta substitui o que está mostrando. Mensagens Test, System e Draft, mensagens Ack e Error e alertas expirados são ignorados, e um remetente e identificador repetidos são duplicados. Uma tela precisa de uma playlist padrão para ser tomada; outras telas são puladas.

A senha, srtg_…, é mostrada somente por triggers create e triggers rotate-secret, com o aviso trigger_password_shown_once. O CLI a mantém fora de sua configuração, log de operação e estado de recuperação. A URL e o nome de usuário não são secretos.

triggers create --name NAME [--kind cap|overlay] (--tag TAG | --screen-id ID...) [--for DURATION] [--pull FILE]
    [--show bar|takeover] [--edge bottom|top] [--style FILE] [--map FILE] [--signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]]
    [--handshake VENDOR]

screenrig triggers create --name "Campus alerts" --tag Campus
screenrig triggers create --name "Campus alerts" --tag Campus --pull pull.json
screenrig triggers create --name "Lobby sensors" --kind overlay --show bar --tag Lobby
screenrig triggers create --name "Doorbell" --kind overlay --show takeover --tag Lobby --for 30s
screenrig triggers create --name "Payments" --kind overlay --show bar --tag Lobby --verify stripe --verify-secret-file stripe.secret --map stripe-map.json
screenrig triggers create --name "Boards" --kind overlay --show bar --tag Lobby --handshake trello

triggers list

screenrig triggers list

triggers show <id>

screenrig triggers show trg_01EXAMPLETRIGGER00

triggers test <id>

screenrig triggers test trg_01EXAMPLETRIGGER00

triggers update <id> [--name NAME] [--tag TAG | --screen-id ID...] [--for DURATION] [--pull FILE | --no-pull]
    [--edge bottom|top] [--style FILE | --clear-style] [--map FILE | --clear-map] [--enable | --disable]
    [--signing | --no-signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS] | --clear-verify]
    [--handshake VENDOR | --clear-handshake] [--expect-rev REVISION]

screenrig triggers update trg_01EXAMPLETRIGGER00 --tag Lobby
screenrig triggers update trg_01EXAMPLETRIGGER00 --edge top --style style.json
screenrig triggers update trg_01EXAMPLETRIGGER00 --map map.json --signing
screenrig triggers update trg_01EXAMPLETRIGGER00 --verify github --verify-secret-file github.secret
screenrig triggers update trg_01EXAMPLETRIGGER00 --clear-verify

triggers deliveries <id> [--limit N]

screenrig triggers deliveries trg_01EXAMPLETRIGGER00 --limit 20

triggers clear <id> [--alert-id ID]

screenrig triggers clear trg_01EXAMPLETRIGGER00
screenrig triggers clear trg_01EXAMPLETRIGGER00 --alert-id front-door

triggers rotate-secret <id> [--signing] [--expect-rev REVISION]

screenrig triggers rotate-secret trg_01EXAMPLETRIGGER00

triggers delete <id> [--expect-rev REVISION]

screenrig triggers delete trg_01EXAMPLETRIGGER00

Gatilhos de sobreposição

Um gatilho de sobreposição mostra o que um sistema externo publica. O Home Assistant, um hub de sensores de porta ou de movimento, um sistema de câmeras ou uma ferramenta de alertas envia poucas palavras com um HTTP POST, e as telas do gatilho as exibem até expirarem ou o remetente as encerrar. É um gatilho como o CAP: triggers create --kind overlay o cria e ele conta no mesmo limite de 20 por organização.

--show bar desenha uma faixa sobre o que está sendo exibido em cada tela de destino, na borda inferior ou, com --edge top, na superior. A faixa entra quando um alerta começa e sai quando o último termina; a playlist, suas páginas e seu tempo não mudam. Uma tela tem uma faixa por borda: um gatilho de sobreposição cuja borda já pertence a outro gatilho em uma tela não aparece ali (triggers show conta essas telas como edge_taken), e uma página que tem a própria faixa com presença nessa borda a mantém. Um cartão de canto ou de ficha nessa borda se desloca para dentro, além da altura da faixa, esteja ela visível ou não. Nenhuma faixa é desenhada em uma página de espaço publicitário nem durante uma tomada de controle. --show takeover exibe o alerta em tela cheia nas telas de destino que têm uma playlist padrão, do primeiro alerta até o fim do último. Um gatilho de tomada de controle nunca substitui uma tomada de controle que já está em uma tela, como a de um operador ou a de um alerta de emergência, e um alerta CAP a substitui.

Um destino por tag é resolvido quando um alerta começa; uma tela marcada depois recebe a faixa com o próximo alerta que começar. Telas sem playlist padrão são ignoradas por uma tomada de controle. Uma tela offline se atualiza ao reconectar.

O remetente envia JSON, um formulário ou multipart/form-data (as partes de arquivo são ignoradas) para data.url com Authorization: Bearer SECRET, ou com HTTP Basic usando o id do gatilho como usuário e o segredo como senha. O segredo nunca vai na URL. Um envio tem estes membros; um membro desconhecido é recusado e nomeado.

Um disparo exige pelo menos um entre label, title, message e note. Texto maior que o limite é recusado, assim como duration fora de 10 segundos a 7 dias, ambos com invalid_request nomeando o membro. Cada disparo ou atualização mantém seu alerta por duration a partir daquele envio; um sensor de movimento que envia a cada poucos segundos mantém a faixa na tela, e ela sai duration depois do último envio. Um gatilho mostra seu alerta mais recente; ao encerrá-lo, o anterior volta a aparecer. Ele mantém dez alertas, e o décimo primeiro substitui o mais antigo. Um alerta termina cerca de dez segundos depois do seu horário. Um encerramento enviado duas vezes encerra o alerta uma só vez, e o encerramento de um alerta que não está ativo não muda nada.

A resposta é um recibo: outcome (shown, updated, unchanged, ended ou ignored), alert_id, until (nulo para um alerta mantido até ser limpo) e active, os alertas que o gatilho mantém após o envio. Um cabeçalho Idempotency-Key de 8 a 200 caracteres responde à nova tentativa de um remetente com o primeiro recibo por 24 horas. Um gatilho aceita 120 envios por minuto. Um envio não conta no limite de solicitações de agente, e uma limpeza nunca é recusada, então um alerta sempre pode ser retirado das telas.

curl -X POST https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay \
  -H "Authorization: Bearer srtg_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"front-door","title":"Front door","message":"The front door is open","duration":"10m"}'

Um endereço errado, um segredo errado, um gatilho desativado, uma assinatura ausente ou errada e qualquer GET dão o mesmo 404 not_found, de modo que um remetente ou a prévia de um link não descobre qual foi. triggers deliveries mostra ao projeto o motivo, dos últimos sete dias, sem o corpo do envio. --style FILE define theme, accent, background, backgroundColor, textColor e align do cartão de texto; use um gatilho por aparência.

--map FILE monta a publicação a partir do corpo que uma ferramenta de alertas envia, com a linguagem de modelos dos webhooks de cartões. Uma string com {{body.title}} é texto, uma string que é exatamente um marcador mantém seu tipo, {"$text": "{{body.message}}", "$max": 400} corta o texto e um caminho começa com body ou query. Este modelo converte um alerta de uma ferramenta de monitoramento e o encerra quando o status é resolved:

{"alert_id": "{{body.groupKey}}", "title": "{{body.title}}", "message": {"$text": "{{body.message}}", "$max": 400}, "state": "{{body.status}}"}

--signing também exige ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, com a chave data.signing_secret (whsec_…, exibido uma só vez), em que t deve estar a no máximo cinco minutos do relógio do servidor. O remetente pode enviar dois valores v1 enquanto troca o segredo.

body='{"alert_id":"front-door","title":"Front door","message":"The front door is open"}'
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST "$URL" -H "Authorization: Bearer $SECRET" -H "ScreenRig-Signature: t=$t,v1=$sig" \
  -H "Content-Type: application/json" -d "$body"

Uma ferramenta de alertas ou um fornecedor que assina as próprias postagens pode ter a assinatura verificada no lugar do segredo, e o handshake de configuração dele respondido, como nos webhooks de cartão: triggers create e triggers update aceitam --verify VENDOR com --verify-secret-file FILE, e --handshake VENDOR, e triggers update aceita --clear-verify e --clear-handshake para remover cada um. Os fornecedores, seus cabeçalhos e as opções de generic_hmac são os listados lá. Uma postagem que traz a assinatura válida do fornecedor é aceita sem a senha srtg_ do gatilho, que continua funcionando ao lado; --verify exclui --signing, e um handshake não altera nenhum alerta. triggers deliveries mostra por que uma assinatura falhou.

Um rest_command do Home Assistant envia ao gatilho. Guarde o segredo em secrets.yaml e dê a cada automação o alerta que ela dispara ou encerra:

# secrets.yaml
screenrig_lobby_overlay: "Bearer srtg_YOUR_SECRET"

# configuration.yaml
rest_command:
  screenrig_lobby:
    url: "https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay"
    method: post
    headers:
      Authorization: !secret screenrig_lobby_overlay
    content_type: "application/json"
    payload: >-
      {{ {"alert_id": alert_id | default(""), "title": title | default(""),
          "message": message | default(""), "duration": duration | default("10m"),
          "clear": clear | default(false)} | tojson }}

# automations.yaml
- alias: Front door open on the lobby screens
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, title: Front door, message: The front door is open, duration: until_cleared}
- alias: Front door closed
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "off"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, clear: true}
- alias: Driveway motion
  triggers:
    - trigger: state
      entity_id: binary_sensor.driveway_motion
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: driveway, title: Driveway, message: Motion at the driveway, duration: 2m}

Dois fatos fazem isto funcionar. Cada envio de movimento mantém a faixa por 2 minutos a partir daquele envio, então ela fica enquanto o movimento continua e sai 2 minutos depois do último evento. E o Home Assistant processa o modelo {{ }} antes de enviar, de modo que o gatilho recebe JSON simples; o modelo --map do próprio gatilho é uma etapa separada que passa cada envio por ele; por isso, deixe --map de fora para um remetente que já envia os membros da sobreposição, como o Home Assistant faz aqui, ou dê a ele um gatilho próprio.