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á.

# Código
<a name="actions-code"></a>

As ações de código no Quick Automate permitem que você implemente uma lógica personalizada usando blocos de código Python, indo além do que as ações de automação padrão suportam. Eles são adequados para cálculos e transformações de dados complexos e são executados em um ambiente Python restrito para manter a segurança.

**Dois tipos de ações de código:**
+ **Expressões de linha única:** operações rápidas de uma linha que modificam variáveis sem retornar valores
+ **Blocos de código personalizados:** funções Multi-line Python para lógica complexa com parâmetros e valores de retorno

**Quando usar ações de código:**

Use blocos de código quando precisar:
+ Execute transformações de dados complexas que não estão disponíveis em ações padrão
+ Implemente cálculos ou lógica de negócios personalizados
+ Processar ou manipular estruturas de dados (listas, dicionários, JSON)
+ Trabalhe com datas, horários e fusos horários de maneiras personalizadas
+ Analise ou formate cadeias de caracteres com padrões complexos
+ Otimize o desempenho da automação consolidando várias ações em um bloco de código

**Quando não usar ações de código:**

Evite blocos de código quando:
+ Já existe uma ação de automação padrão para seu caso de uso
+ A operação é simples o suficiente para ações integradas
+ Você precisa interagir com APIs externas (em vez disso, use a integração da API REST)
+ Você precisa acessar sistemas de arquivos ou bancos de dados (usar integrações apropriadas)

**Como acessar as ações do código:**

Os blocos de código estão disponíveis por meio de várias interfaces:
+ **Painel de ações (recomendado):**
  + Abra sua automação no criador de automação
  + Clique no Painel de ações no lado direito
  + Localize “Bloco de código personalizado” na seção Ações de código
  + Arraste e solte o bloco de código em seu fluxo de trabalho de automação
+ **Crie com o Assistant:**
  + Disponível durante a geração do plano, quando o assistente determina que o código personalizado é necessário
  + O assistente sugere automaticamente blocos de código para operações complexas
  + Você pode solicitar blocos de código descrevendo suas necessidades lógicas personalizadas

**Ações disponíveis:**

## Expressões de linha única
<a name="single-line-expressions"></a>

As expressões de linha única executam instruções Python de uma linha que realizam operações sem retornar um valor. Eles são ideais para modificações rápidas em variáveis existentes, como anexar listas, atualizar dicionários ou realizar cálculos simples que modificam o estado.

**Propriedades:**
+ Expressão (obrigatória): a expressão Python a ser executada (por exemplo, “my\_list.append ('new item')”)

**Exemplos:**
+ **Anexando à lista**

  ```
  my_list.append("1")
  my_list.append(new_item)
  ```
+ **Removendo itens da lista**

  ```
  task_list.remove(completed_task)
  ```

## Bloco de código personalizado
<a name="custom-code-block"></a>

Os blocos de código personalizados são funções Python de várias linhas que executam lógica complexa, aceitam parâmetros e retornam valores. Eles são a opção alternativa quando ações de automação padrão e expressões de linha única não são suficientes para suas necessidades.

**Propriedades:**
+ **Título da função (obrigatório)**: identificador de nome para o bloco de código (por exemplo, "Calculate\_Total“)
+ **Função (obrigatório):** bloco de código Python que contém sua lógica personalizada.
  + Etapa 1: Definir parâmetros
    + Clique no botão “Editar” para abrir o editor de código
    + No painel Parâmetros, clique em “Adicionar” para criar novos parâmetros
    + Insira nomes de parâmetros que correspondam às suas variáveis de automação
    + Os parâmetros estão disponíveis como argumentos de função
  + Etapa 2: escreva seu código Python
+ **Valor de retorno (opcional):** nome da variável para armazenar a saída da função
  + Siga a estrutura de blocos de código necessária (veja abaixo)
  + Implemente sua lógica personalizada dentro da função
  + Use somente bibliotecas aprovadas e funções integradas
  + Inclua uma declaração de retorno se você precisar gerar dados

**Estrutura do bloco de código**

Todos os blocos de código devem seguir esse formato específico:

```
@code_block()
def your_function_name(parameter1, parameter2, parameter3):
-------------------------------------------------------------------------------------
    """
    Optional: Add a docstring describing what your function does
    """
    # Your custom logic here
    result = parameter1 + parameter2 + parameter3

    return result
```

**Built-in Funções e importações do Python**

Todas as funções incorporadas padrão do Python estão disponíveis sem importações (len, str, int, etc.)

**Bibliotecas padrão aprovadas (segurança restrita)**

Os blocos de código SÓ podem importar essas bibliotecas padrão:
+ `base64`- Base 64 encoding/decoding
+ `datetime`- Operações de data e hora
+ `json`- Análise e geração de JSON
+ `math`- Funções matemáticas
+ `re`- Expressões regulares
+ `zoneinfo`- Tratamento de fuso horário

**nota**  
Não é possível importar bibliotecas padrão diferentes das listadas acima.
Não é possível instalar ou importar bibliotecas de terceiros. `pip install`não é suportado em blocos de código.

**Limitações**
+ Ambiente Python restrito com acesso limitado à biblioteca. O ambiente de execução é baseado em RestrictedPython, um subconjunto do Python 3.10.
+ Os blocos de código não podem invocar outros blocos de código ou ações

**Práticas recomendadas**
+ Mantenha os blocos de código simples e focados
+ Use nomes de funções descritivos
+ Sempre prefira ações pré-criadas quando disponíveis
+ Teste seus blocos de código minuciosamente, pois as opções de depuração focadas são limitadas)

**Exemplo ** de casos de uso do 
+ Operações matemáticas (Calcular propriedades do círculo - raio como parâmetro)

  ```
  def function
  (radius):
  
      return {
          "radius": radius,
          "diameter": 2 * radius,
          "circumference": round(2 * math.pi * radius, 2),
          "area": round(math.pi * radius ** 2, 2)
      }
  ```
+ Obtendo a atualidade date/time

  ```
  def function
  ():
  
      now = datetime.datetime.now()
  
      return {
          "current_date": now.strftime("%Y-%m-%d"),
          "current_time": now.strftime("%H:%M:%S"),
          "formatted": now.strftime("%B %d, %Y at %I:%M %p"),
          "iso_format": now.isoformat(),
          "timestamp": now.timestamp()
      }
  ```
+ Calculando diferenças de datas - Data de início e data de término como parâmetros

  ```
  def function
  _(start_date_str, end_date_str):
  
  # Parse date strings (format: YYYY-MM-DD)_
      start = datetime.datetime.strptime(start_date_str, "%Y-%m-%d")
      end = datetime.datetime.strptime(end_date_str, "%Y-%m-%d")
  
      _# Calculate difference_
      difference = end - start
      return {
          "days": difference.days,
          "weeks": difference.days // 7,
          "start": start_date_str,
          "end": end_date_str    }
  ```
+ Correspondência de padrões e manipulação de texto usando expressões regulares (validação de endereços de e-mail, números de telefone etc.)

  ```
  def function
  (email, phone, zip_code):
  
      email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
      phone_pattern = r'^\d{3}-\d{3}-\d{4}$'
      zip_pattern = r'^\d{5}(-\d{4})?$'
  
      return {
          "email_valid": bool(re.match(email_pattern, email)),
          "phone_valid": bool(re.match(phone_pattern, phone)),
          "zip_valid": bool(re.match(zip_pattern, zip_code))
      }
  ```
+ Operações de lista (filtrar e transformar lista)

  ```
  def function
  (numbers, threshold):
  
      # Filter numbers above threshold and calculate statistics
      filtered = [n for n in numbers if n > threshold]
  
      if filtered:
          return {
              "filtered_numbers": filtered,
              "count": len(filtered),
              "sum": sum(filtered),
              "average": sum(filtered) / len(filtered),
              "min": min(filtered),
              "max": max(filtered)
          }
      else:
          return {
              "filtered_numbers": [],
              "count": 0,
              "message": "No numbers above threshold"
          }
  ```