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

# Trabalhando com parâmetros em modelos PySpark de análise
<a name="pyspark-parameter-handling"></a>

Os parâmetros aumentam a flexibilidade de seus modelos de PySpark análise, permitindo que valores diferentes sejam fornecidos no momento do envio do trabalho. Os parâmetros são acessíveis por meio do objeto de contexto passado para sua função de ponto de entrada.

**nota**  
Os parâmetros são cadeias de caracteres fornecidas pelo usuário que podem conter conteúdo arbitrário.  
Revise o código para garantir que os parâmetros sejam tratados com segurança para evitar comportamentos inesperados em sua análise.
Projete o manuseio de parâmetros para funcionar com segurança, independentemente dos valores dos parâmetros fornecidos no momento do envio.

## Acessando parâmetros
<a name="accessing-parameters"></a>

Os parâmetros estão disponíveis no `context['analysisParameters']` dicionário. Todos os valores dos parâmetros são cadeias de caracteres.

**Example Acessando parâmetros com segurança**  

```
def entrypoint(context):
    # Access parameters from context
    parameters = context['analysisParameters']
    threshold = parameters['threshold']
    table_name = parameters['table_name']
    
    # Continue with analysis using parameters
    spark = context['sparkSession']
    input_df = context['referencedTables'][table_name]
    
    # Convert threshold value
    threshold_val = int(threshold)
    
    # Use parameter in DataFrame operation
    filtered_df = input_df.filter(input_df.amount > threshold_val)
    
    return {
        "results": {
            "output": filtered_df
        }
    }
```

## Práticas recomendadas de segurança de parâmetros
<a name="parameter-security-best-practices"></a>

**Atenção**  
Os parâmetros são cadeias de caracteres fornecidas pelo usuário que podem conter conteúdo arbitrário. Você deve manipular os parâmetros com segurança para evitar vulnerabilidades de segurança em seu código de análise.

**Padrões inseguros de manipulação de parâmetros a serem evitados:**
+ **Executando parâmetros como código** — Nunca use `eval()` ou `exec()` em valores de parâmetros

  ```
  # UNSAFE - Don't do this
  eval(parameters['expression'])  # Can execute arbitrary code
  ```
+ **Interpolação de strings SQL** — Nunca concatene parâmetros diretamente em strings SQL

  ```
  # UNSAFE - Don't do this
  sql = f"SELECT * FROM table WHERE column = '{parameters['value']}'"  # SQL injection risk
  ```
+ **Operações inseguras de caminho de arquivo** — nunca use parâmetros diretamente nas operações do sistema de arquivos sem validação

  ```
  # UNSAFE - Don't do this
  file_path = f"/data/{parameters['filename']}"  # Path traversal risk
  ```

**Padrões seguros de manipulação de parâmetros:**
+ **Use parâmetros em DataFrame operações** — O Spark DataFrames manipula os valores dos parâmetros com segurança

  ```
  # SAFE - Use parameters in DataFrame operations
  threshold = int(parameters['threshold'])
  filtered_df = input_df.filter(input_df.value > threshold)
  ```
+ **Validar valores de parâmetros** — Verifique se os parâmetros atendem aos formatos esperados antes de usar

  ```
  # SAFE - Validate parameters before use
  def validate_date(date_str):
      try:
          from datetime import datetime
          datetime.strptime(date_str, '%Y-%m-%d')
          return True
      except ValueError:
          return False
  
  date_param = parameters['date_filter'] or '2024-01-01'
  if not validate_date(date_param):
      raise ValueError(f"Invalid date format: {date_param}")
  ```
+ **Use listas de permissões para valores de parâmetros** — Quando possível, valide os parâmetros em relação a valores válidos conhecidos

  ```
  # SAFE - Use allowlists
  allowed_columns = ['column1', 'column2', 'column3']
  column_param = parameters['column_name']
  if column_param not in allowed_columns:
      raise ValueError(f"Invalid column: {column_param}")
  ```
+ **Conversão de tipo com tratamento de erros** — Converta parâmetros de string em tipos esperados com segurança

  ```
  # SAFE - Convert with error handling
  try:
      batch_size = int(parameters['batch_size'] or '1000')
      if batch_size <= 0 or batch_size > 10000:
          raise ValueError(f"Batch size must be between 1 and 10000")
  except ValueError as e:
      print(f"Invalid parameter: {e}")
      raise
  ```

**Importante**  
Lembre-se de que os parâmetros ignoram a revisão de código quando os executores de tarefas fornecem valores diferentes. Projete seu tratamento de parâmetros para funcionar com segurança, independentemente dos valores de parâmetros fornecidos.

## Exemplo completo de parâmetro
<a name="parameter-examples"></a>

**Example Usando parâmetros com segurança em um PySpark script**  

```
def entrypoint(context):
    try:
        # Access Spark session and tables
        spark = context['sparkSession']
        input_table = context['referencedTables']['sales_data']
        
        # Access parameters - fail fast if analysisParameters missing
        parameters = context['analysisParameters']
        
        # Validate and convert numeric parameter (handles empty strings with default)
        try:
            threshold = int(parameters['threshold'] or '100')
            if threshold <= 0:
                raise ValueError("Threshold must be positive")
        except (ValueError, TypeError) as e:
            print(f"Invalid threshold parameter: {e}")
            raise
        
        # Validate date parameter (handles empty strings with default)
        date_filter = parameters['start_date'] or '2024-01-01'
        from datetime import datetime
        try:
            datetime.strptime(date_filter, '%Y-%m-%d')
        except ValueError:
            raise ValueError(f"Invalid date format: {date_filter}")
        
        # Use parameters safely in DataFrame operations
        filtered_df = input_table.filter(
            (input_table.amount > threshold) &
            (input_table.date >= date_filter)
        )
        
        result_df = filtered_df.groupBy("category").agg(
            {"amount": "sum"}
        )
        
        return {
            "results": {
                "filtered_results": result_df
            }
        }
    
    except Exception as e:
        print(f"Error in analysis: {str(e)}")
        raise
```