Como definir parâmetros de componentes de playbook - Security Center: Central de Documentação do Alibaba Cloud

Categorias de parâmetros

Os parâmetros classificam-se em duas dimensões:

Por função: parâmetros de entrada do playbook, parâmetros de saída do playbook, parâmetros de entrada da ação do componente e parâmetros de saída da ação do componente.
Por origem: parâmetros do sistema e parâmetros do componente.

Nota

Durante a execução da ação do componente, os parâmetros do sistema (parâmetros padrão distintos dos parâmetros do componente) ficam acessíveis em qualquer nó.

Parâmetros de entrada e saída do componente (nó)

A entrada de um nó pode ser um valor fixo (constante) ou a saída de um nó anterior. Para referenciar a saída de um nó precedente, ele deve aparecer antes do nó atual no mesmo caminho de orquestração.

Importante

Em playbooks com múltiplos caminhos, os nomes dos nós devem ser globalmente únicos.

O diagrama a seguir ilustra essa regra. O Nó B acessa as saídas do Nó A (seu predecessor direto) e os parâmetros de entrada do playbook. Ele não acessa o Nó D (ramificação diferente) nem o Nó C (não é um nó precedente do Nó B em nenhum caminho).

Parâmetros do sistema

Parâmetros do sistema no nível do playbook

Use ${event.parameter_name} para acessar esses parâmetros em qualquer nó. event é o nome reservado do nó inicial; não nomeie nenhum componente como event durante a orquestração do playbook.

Parâmetro	Tipo de dados	Expressão	Descrição
`_tenant_id`	String	`${event._tenant_id}`	ID da conta Alibaba Cloud que chama o playbook
`_domain_id`	String	`${event._domain_id}`	Status da função do usuário conectado. `0`: Login de conta única. `1`: Login de conta global.
`_trigger_user`	String	`${event._trigger_user}`	ID da conta Alibaba Cloud que aciona o playbook. Se um usuário RAM acionar o playbook, o sistema retorna o ID desse usuário RAM.
`_region_id`	String	`${event._region_id}`	ID da região
`_req_uuid`	String	`${event._req_uuid}`	Identificador único da execução atual do playbook
`parentTaskUuid`	String	`${event.parentTaskUuid}`	`_req_uuid` do playbook pai. Presente apenas quando este playbook é chamado como playbook filho.
`parentTaskName`	String	`${event.parentTaskName}`	UUID do playbook pai. Presente apenas quando este playbook é chamado como playbook filho.

Parâmetros do sistema na saída da ação do componente

Cada execução de nó gera os seguintes campos de saída padrão. Os parâmetros de saída personalizados do componente ficam armazenados em datalist. Use ${node_name.datalist.*} para recuperar todos os valores de saída.

Parâmetro	Tipo de dados	Descrição
`datalist`	JSONArray	Parâmetros de saída produzidos pela ação. Saídas personalizadas do componente também ficam armazenadas aqui.
`total_data_successful`	Int	Quantidade de entradas de dados processadas com sucesso
`total_data`	Int	Total de entradas de dados processadas
`total_data_with_dup`	Int	Volume de dados processados com sucesso e deduplicados durante a execução da ação
`total_exe_successful`	Int	Número de conclusões bem-sucedidas da ação
`total_exe`	Int	Total de execuções da ação
`status`	Boolean	Status da execução: `true` (sucesso) ou `false` (falha)
`messageForUser`	String	Mensagem de erro exibida ao usuário caso a ação falhe
`message`	String	Mensagem de erro interno do sistema em caso de falha na ação
`failed_exe_detail`	String	Informações detalhadas de erro caso a ação falhe

Formatos de parâmetros

Os parâmetros de entrada do nó aceitam três formatos básicos — constantes, variáveis e expressões — além de combinações entre eles.

Formato	Descrição	Exemplo
Constante	Valor de string fixo	`Ali`
Variável	Extrai um valor dos parâmetros de entrada do playbook ou da saída de um nó anterior	`${event.aliuid}`
Expressão	Avalia uma expressão ou função incorporada. Formato: `<%=expression	function%>`. Apenas a sintaxe Java é suportada. Para funções disponíveis, consulte a lista de funções integradas abaixo.	Expressão: `<%=26060%>`. Função: `<%=currentTime()%>`.
Combinação	Mistura constantes, variáveis e expressões em um único valor	Combinação: `Ali_${event.aliuid}_<%=currentTime()%>_<%=26060%>` — em tempo de execução, variáveis e expressões resolvem para seus valores: `Ali_aliuid_<timestamp>_7200`. Aninhamento (expressões podem incorporar variáveis): `<%=formatTimeStamp(secondstamp_add(${DateTime:event.datalist..gmt_create},-600L),"yyyy-MM-dd'T'HH:mm:ss.SSSXXX")%>` — obtém o valor `gmt_create` de `${DateTime:event.datalist..gmt_create}`, subtrai 600 segundos e formata o resultado como data.

Funções integradas

Função	Descrição	Exemplo	Saída
`currentTime`	Retorna o timestamp atual	`<%=currentTime()%>`	`2025-06-05 10:30:00`
`secondstamp_add`	Adiciona um número especificado de segundos a um timestamp	`<%=secondstamp_add(currentTime(),300L)%>`	`2025-06-05 10:30:09`
`formatTimeStamp`	Formata um timestamp usando um padrão especificado	`<%=formatTimeStamp(currentTime(),"yyyyMMdd")%>`	`20250605`
`timestampToseconds`	Adiciona segundos a um timestamp e converte o resultado para segundos epoch	`<%=timestampToseconds(currentTime(),300L)%>`	`1749099848`
`splitStr`	Divide uma string em uma lista por um delimitador	`<%=splitStr("test,value",",")%>`	`[test,value]`
`parseTimeMs`	Analisa uma string de tempo formatada em milissegundos	`<%=parseTimeMs("2025-06-05 10:30:32","yyyy-MM-ddHH:mm:ss")%>`	`1749090632000`
`currentTimeToMs`	Retorna o timestamp atual em milissegundos	`<%=currentTimeToMs()%>`	`1749091369688`
`currentHourToMs`	Retorna o timestamp em milissegundos correspondente ao início da hora atual	`<%=currentHourToMs()%>`	`1749088800000`
`currentDayToMs`	Retorna o timestamp em milissegundos correspondente ao início do dia atual	`<%=currentDayToMs()%>`	`1749052800000`
`parseTimeMsWDefault`	Converte uma string de tempo para milissegundos. Retorna o valor padrão (parâmetro 2) se a entrada estiver vazia	`<%=parseTimeMsWDefault("2025-06-05 10:30:32",1749091369688L)%>`	`1749090632000`
`splitStrToJsonArray`	Divide uma string em um JSONArray por um delimitador	`<%=splitStrToJsonArray("test,value",",")%>`	`["test","value"]`
`concatListStr`	Concatena elementos de lista com um delimitador. Use com splitStr	`<%=concatListStr("	",splitStr("test,value",","))%>`	`test	value`
`substring`	Extrai uma substring. Parâmetro 1: string de source. Parâmetro 2: índice inicial. Parâmetro 3: índice final	`<%=substring("012345",0,3)%>`	`012`
`remainStrStartEnd`	Mantém os primeiros N e os últimos M caracteres, unidos por cinco underscores. Parâmetro 1: string de source. Parâmetro 2: quantidade de caracteres iniciais. Parâmetro 3: quantidade de caracteres finais	`<%=remainStrStartEnd("012345",2,2)%>`	`01_____45`
`toLong`	Converte um valor para o tipo Long. Parâmetro 1: valor de entrada. Parâmetro 2: valor padrão se a conversão falhar	`<%=toLong("1234",12L)%>`	`1234.0`
`toLowerCase`	Converte todas as letras inglesas de uma string para minúsculas	`<%=toLowerCase("TEST")%>`	`test`
`toUpperCase`	Converte todas as letras inglesas de uma string para maiúsculas	`<%=toUpperCase("test")%>`	`TEST`
`toJSONObject`	Analisa uma string JSON em um JSONObject	`<%=toJSONObject("{\"name\":\"test\",\"age\":12}")%>`	`{"name":"test","age":12}`
`base64encode`	Codifica uma string usando Base64	`<%=base64encode("abc")%>`	`YWJj`
`base64decode`	Decodifica uma string codificada em Base64	`<%=base64decode("YWJj")%>`	`abc`
`replace`	Substitui uma substring. Parâmetro 1: string de source. Parâmetro 2: substring alvo. Parâmetro 3: string de substituição	`<%=replace("abc123","abc","aaa")%>`	`aaa123`
`isNull`	Retorna true se o valor for nulo ou vazio	`<%=isNull("")%>`	`true`

Parâmetros variáveis

Para referenciar a saída de um nó precedente durante a execução do componente do playbook, utilize o formato de parâmetro variável. Para parâmetros de entrada do playbook, use event como nome do nó — trate-o como a saída do nó inicial. Não nomeie nenhum componente como event durante a orquestração do playbook.

Apenas parâmetros de saída de nós podem ser referenciados como variáveis.
Os parâmetros de entrada do playbook equivalem aos parâmetros de saída do nó inicial.
Os parâmetros de entrada do nó atual equivalem aos parâmetros de saída do nó anterior.

Formato de sintaxe

Use ${node_name.parameter_path} para recuperar parâmetros de saída do nó. O caminho segue as convenções JSONPath e suporta aninhamento JSON de qualquer profundidade.

Para estruturas JSONObject, use . para acessar campos aninhados. Para estruturas JSONArray, * recupera todos os itens, e índices numéricos como [0] recuperam um item específico. A tabela a seguir usa os parâmetros de saída da ação como exemplo:

Tipo	Sintaxe	Descrição
Obter um parâmetro de JSON	`${node_name.datalist.*.param1.param2}`. Sintaxe do nó inicial: `${event.param1.param2}`.	Obtém o valor de param2 dentro de param1. param1 deve ser um JSONObject.
Obter todos os itens de um array JSON	`${node_name.datalist..param1..param2}`. Sintaxe do nó inicial: `${event.param1.*.param2}`.	Obtém param2 de todos os JSONObjects dentro de param1. param1 deve ser um JSONArray.
Obter um único item de um array JSON	`${node_name.datalist.*.param1.[0].param2}`. Sintaxe do nó inicial: `${event.param1.[0].param2}`.	Obtém param2 do primeiro JSONObject dentro de param1. param1 deve ser um JSONArray.

Em vez de escrever a sintaxe de variáveis manualmente, utilize a lista suspensa na caixa de entrada para selecionar parâmetros e gerar a sintaxe automaticamente. Essa abordagem é recomendada após concluir a depuração. Por exemplo, na configuração outputFields, clique na área de valor de mapeamento de campo para exibir um menu suspenso de fonte de dados (como InputCheck, dataSetFilter ou SiemEventFormat). Após selecionar uma fonte de dados, os caminhos de campo disponíveis aparecem no lado direito. Clique em um campo alvo para gerar a expressão variável, como ${InputCheck.datalist.*.records.*.hackerIP}.

Exemplos de parâmetros variáveis

Os exemplos a seguir utilizam um nó chamado node1 com esta saída:

{
  "datalist": [
    {
      "person": {
        "weight": "120",
        "age": "12"
      }
    },
    {
      "person": {
        "weight": "121",
        "age": "13"
      }
    }
  ],
  "total_data_successful": 2,
  "total_data": 2,
  "total_exe_successful": 2,
  "total_exe": 2,
  "total_data_with_dup": 2,
  "status": true
}

Sintaxe	Descrição
`${event._req_uuid}`	Obtém o parâmetro do sistema _req_uuid do nó inicial (entrada do playbook).
`${event.parentTaskUuid}`	Em um playbook filho, obtém o _req_uuid do playbook pai (presente apenas quando chamado como playbook filho).
`${node1.total_data_successful}`	Obtém a contagem de dados bem-sucedidos de node1. Saída: 2.
`${node1.datalist.*.person.age}`	Obtém todos os valores person.age da datalist de node1. Saída: {12,13}.
`${node1.datalist.[0].person.age}`	Obtém o primeiro valor person.age da datalist de node1. Saída: 12.

Conversão de tipos de dados

Durante a execução do playbook, a maioria dos dados é tratada como strings. Quando uma ação exigir um tipo específico, use ${data_type:data} para converter.

Tipo alvo	Descrição	Tipos de source suportados
`Boolean`	Converte para `true` ou `false`	Numérico: `1` → `true`, todos os outros valores → `false`. String: `"true"`, `"1"`, `"Y"`, `"T"` → `true`; `"false"`, `"0"`, `"N"`, `"F"` → `false`. Outras strings causam erro.
`Long`	Converte para um inteiro Long	Tipos numéricos; strings contendo apenas dígitos e vírgulas (ex.: `1,000,000`)
`Int`	Converte para um inteiro	Tipos numéricos (Long, Int, Double). Tipos String contendo apenas dígitos e vírgulas (ex.: `1,000,000`).
`Double`	Converte para ponto flutuante de precisão dupla	Tipos numéricos (Long, Int, Double). Tipos String contendo apenas dígitos e vírgulas (ex.: `1,000,000`).
`String`	Converte para string	Todos os tipos
`DateTime`	Converte para data	Tipos numéricos; strings numéricas (ex.: `1696487400000`) ou no formato ISO 8601 (ex.: `2023-10-05 14:30:00`)
`JSONObject`	Extrai pares chave-valor de um JSONObject para um novo JSONObject. Formato de saída: `{"fieldname":"fieldValue",...}`	Apenas JSONObject
`JSONArray`	Extrai pares chave-valor de um JSONObject para um JSONArray. Formato de saída: `[{"fieldname":"fieldValue",...}]`	Apenas JSONObject
`JSONObjectStr`	Converte um JSONObject para sua representação em string	JSONObject
`JSONArrayStr`	Converte um JSONArray para sua representação em string	JSONArray

Exemplos:

Exemplos de JSONObject: Entrada do playbook: {"src_ip":"127.0.0.1","dst_ip":"127.0.0.2","msg":"hello"}

Expressão	Resultado
`${JSONObject:event}`	O evento inteiro como uma string JSON
`${JSONObject:event.src_ip}`	`{"src_ip":"127.0.0.1"}`
`${JSONObject:event.src_ip	msg}`	`{"src_ip":"127.0.0.1","msg":"hello"}`
`${JSONArray:event}`	O evento inteiro como um JSONArray
`${JSONArray:event.src_ip}`	`[{"src_ip":"127.22.22.1"}]`
`${JSONArray:event.src_ip	msg}`	`[{"src_ip":"127.0.0.1","msg":"hello"}]`

Exemplos de JSONArray: Entrada do playbook: {"datalist":[{"src_ip":"127.0.0.1","dst_ip":"127.1.0.1","msg":"hello"},{"src_ip":"127.1.0.1","dst_ip":"127.1.0.1","msg":"hello"}]}

Expressão	Resultado
`${JSONObject:event.datalist.*.src_ip}`	Expande para múltiplas linhas; cada linha: `{"src_ip":"127.x.0.1"}`
`${JSONObject:event.datalist.*.src_ip	msg}`	Expande para múltiplas linhas; cada linha: `{"src_ip":"127.x.0.1","msg":"hello"}`
`${JSONArray:event.datalist.*.src_ip}`	`[{"src_ip":"127.0.0.1"},{"src_ip":"127.1.0.1"}]`
`${JSONArray:event.datalist.*.src_ip	msg}`	`[{"src_ip":"127.0.0.1","msg":"hello"},{"src_ip":"127.1.0.1","msg":"hello"}]`

Processamento de parâmetros e fluxo de execução de nós

Extração de parâmetros do nó: Após a conclusão da execução de todos os nós anteriores necessários, o sistema extrai os dados reais de entrada do nó atual com base em sua configuração de entrada. O processo de extração é descrito em detalhes abaixo.
Execução do nó: Depois que os parâmetros de entrada do nó são montados, o sistema deduplica conjuntos idênticos de parâmetros e executa a ação do componente.

Nota
Quando uma ação aceita múltiplos conjuntos de valores de parâmetros, a ação é executada várias vezes automaticamente.

Por exemplo, para executar a ação "Purge Malicious File" em todos os servidores de um aplicativo comprometido (vários servidores), defina o parâmetro Server IP como ${node1.datalist.*.ip}. O sistema executa automaticamente a ação em cada endereço IP sem exigir um loop.
Agregação e deduplicação de resultados de saída: Após o nó ser executado múltiplas vezes, o sistema agrega e deduplica automaticamente os resultados. Uma entrada é considerada duplicada quando todos os campos são idênticos.

Antes da deduplicação:
```
[
    {
        "a":"11",
        "b":"22"
    },
    {
        "a":"11",
        "b":"22"
    },
    {
        "a":"11",
        "b":"33"
    }
]
```
Após a deduplicação:
```
[
    {
        "a":"11",
        "b":"22"
    },
    {
        "a":"11",
        "b":"33"
    }
]
```

Processo de extração de parâmetros

Fonte de dados única

Uma estrutura JSON complexa de qualquer profundidade pode ser vista como uma árvore. Os princípios para extrair parâmetros de JSON são: relações de irmãos na mesma profundidade são preservadas, nós ancestrais são expandidos e campos que não são nem irmãos nem ancestrais formam um product cartesiano.

Extrai automaticamente dados em qualquer profundidade. Exemplo:
Relações de irmãos são preservadas: Campos no mesmo nível da estrutura JSON permanecem pareados.
Nós ancestrais são expandidos: Quando um nó pai possui múltiplos filhos, ele se expande para corresponder à contagem de filhos.
Nós não irmãos e não ancestrais formam um product cartesiano: Quando dois campos não possuem relação de irmandade ou ancestralidade, todas as combinações são produzidas.

Múltiplas fontes de dados

Aplique um product cartesiano aos resultados de extração de cada fonte de dados individual.