• O AWS Systems Manager CloudWatch Dashboard não estará mais disponível a partir de 30 de abril de 2026. Os clientes podem continuar usando o console do Amazon CloudWatch para visualizar, criar e gerenciar os painéis do Amazon CloudWatch exatamente como fazem hoje. Para obter mais informações, consulte a [documentação do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # `aws:executeScript` – Executa um script Executa o script do Python ou PowerShell fornecido, usando o runtime e o handler especificados. Cada ação `aws:executeScript` pode ser executada por uma duração máxima de dez minutos (600 segundos). Você pode limitar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:executeScript`. Use instruções de retorno em sua função para adicionar saídas à carga útil da saída. Para obter exemplos de definição de saídas para sua ação `aws:executeScript`, consulte [Exemplo 2: Runbook com script](automation-authoring-runbooks-scripted-example.md). Também é possível enviar o resultado das ações do `aws:executeScript` nos runbooks para o grupo de logs do Amazon CloudWatch Logs especificado. Para obter mais informações, consulte [Registro de saída de ações do Automation em log com o CloudWatch Logs](automation-action-logging.md). Se quiser enviar a saída de ações `aws:executeScript` ao CloudWatch Logs ou se os scripts que você especificar para ações `aws:executeScript` chamarem opções de API da AWS, um perfil de serviço do AWS Identity and Access Management (IAM) (ou uma função de recepção) sempre será necessário para executar o runbook. **nota** A ação `aws:executeScript` não suporta uma nova tentativa automática de controle de utilização. Se o seu script fizer chamadas de API AWS que possam ser limitadas, você deve implementar a sua própria lógica de repetição no código do script. A ação `aws:executeScript` contém os módulos pré-instalados do PowerShell Core a seguir. + Microsoft.PowerShell.Host + Microsoft.PowerShell.Management + Microsoft.PowerShell.Security + Microsoft.PowerShell.Utility + PackageManagement + PowerShellGet Para usar módulos do PowerShell Core que não estão pré-instalados, o script deve instalar o módulo com o sinalizador `-Force`, conforme mostrado no comando a seguir. Não há suporte ao módulo `AWSPowerShell.NetCore`. Substitua *ModuleName* pelo nome do módulo que deseja instalar. ``` Install-Module ModuleName -Force ``` Para usar cmdlets do PowerShell Core em seu script, recomendamos o uso dos módulos `AWS.Tools`, conforme mostrado nos comandos a seguir. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. + Cmdlets do Amazon S3. ``` Install-Module AWS.Tools.S3 -Force Get-S3Bucket -BucketName amzn-s3-demo-bucket ``` + cmdlets do Amazon EC2 ``` Install-Module AWS.Tools.EC2 -Force Get-EC2InstanceStatus -InstanceId instance-id ``` + cmdlets do AWS Tools for Windows PowerShell comuns ou independentes de serviço. ``` Install-Module AWS.Tools.Common -Force Get-AWSRegion ``` Se o script inicializar novos objetos além de usar cmdlets do PowerShell Core, você também deverá importar o módulo conforme mostrado no comando a seguir. ``` Install-Module AWS.Tools.EC2 -Force Import-Module AWS.Tools.EC2 $tag = New-Object Amazon.EC2.Model.Tag $tag.Key = "Tag" $tag.Value = "TagValue" New-EC2Tag -Resource i-02573cafcfEXAMPLE -Tag $tag ``` Para obter exemplos de instalação e importação dos módulos `AWS.Tools` e do uso de cmdlets do PowerShell Core em runbooks, consulte [Experiência de design visual para runbooks de automação](automation-visual-designer.md). **Input** Forneça as informações necessárias para executar o script. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. **nota** O anexo de um script Python pode ser um arquivo .py ou um arquivo .zip contendo o script. É necessário armazenar os scripts do PowerShell em arquivos .zip. ------ #### [ YAML ] ``` action: "aws:executeScript" inputs: Runtime: runtime Handler: "functionName" InputPayload: scriptInput: '{{parameterValue}}' Script: |- def functionName(events, context): ... Attachment: "scriptAttachment.zip" ``` ------ #### [ JSON ] ``` { "action": "aws:executeScript", "inputs": { "Runtime": "runtime", "Handler": "functionName", "InputPayload": { "scriptInput": "{{parameterValue}}" }, "Attachment": "scriptAttachment.zip" } } ``` ------ Runtime A linguagem do runtime a ser usada para executar o script fornecido. O `aws:executeScript` suporta runtimes na tabela a seguir. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/automation-action-executeScript.html) Tipo: String Exigido: sim Para runtimes Python, o ambiente fornece 512 MB de memória e 512 MB de espaço em disco. Para runtimes PowerShell, o ambiente fornece 1024 MB de memória e 512 MB de espaço em disco. Manipulador Escolha o nome da função. É necessário garantir que a função definida no manipulador tenha dois parâmetros, `events` e `context`. O runtime do PowerShell não oferece suporte a este parâmetro. Tipo: string Obrigatório: sim (Python) \$1 sem suporte (PowerShell) InputPayload Um objeto JSON ou YAML que será passado para o primeiro parâmetro do manipulador. Isso pode ser usado para passar dados de entrada para o script. Tipo: string Obrigatório: não ``` description: Tag an instance schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' InstanceId: type: String description: (Required) The ID of the EC2 instance you want to tag. mainSteps: - name: tagInstance action: 'aws:executeScript' inputs: Runtime: "python3.11" Handler: tagInstance InputPayload: instanceId: '{{InstanceId}}' Script: |- def tagInstance(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceId = events['instanceId'] tag = { "Key": "Env", "Value": "ExamplePython" } print(f"Adding tag {tag} to instance id {instanceId}") ec2.create_tags( Resources=[instanceId], Tags=[tag] ) return tag outputs: - Type: String Name: TagKey Selector: $.Payload.Key outputs: - tagInstance.TagKey ``` ``` description: Tag an instance schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: (Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook. InstanceId: type: String description: (Required) The ID of the EC2 instance you want to tag. mainSteps: - name: tagInstance action: aws:executeScript isEnd: true inputs: Runtime: PowerShell 7.4 InputPayload: instanceId: '{{InstanceId}}' Script: |- Install-Module AWS.Tools.EC2 -Force Import-Module AWS.Tools.EC2 $input = $env:InputPayload | ConvertFrom-Json $tag = New-Object Amazon.EC2.Model.Tag $tag.Key = "Env" $tag.Value = "ExamplePowerShell" Write-Information "Adding tag key: $($tag.Key) and value: $($tag.Value) to instance id $($input.instanceId)" New-EC2Tag -Resource $input.instanceId -Tag $tag return $tag outputs: - Type: String Name: TagKey Selector: $.Payload.Key outputs: - tagInstance.TagKey ``` Script Um script incorporado que você precisa executar durante a execução da automação. Tipo: string Obrigatório: não (Python) \$1 sim (PowerShell) Attachment O nome de um arquivo de script autônomo ou arquivo .zip que pode ser invocado pela ação. Especifique o mesmo valor do `Name` do arquivo de anexo de documento especificado no parâmetro de solicitação de `Attachments`. Para obter mais informações, consulte [Anexos](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) na *Referência de API do AWS Systems Manager*. Se você estiver fornecendo um script usando um anexo, você deverá definir uma seção `files` nos elementos de nível superior do seu runbook. Para obter mais informações, consulte [Versão 0.3 do esquema](documents-schemas-features.md#automation-doc-syntax-examples). Para invocar um arquivo para Python, use o formato `filename.method_name` no `Handler`. O anexo de um script Python pode ser um arquivo .py ou um arquivo .zip contendo o script. É necessário armazenar os scripts do PowerShell em arquivos .zip. Ao incluir bibliotecas Python em seu anexo, recomendamos adicionar um arquivo `__init__.py` em cada diretório do módulo. Isso permite que você importe os módulos da biblioteca em seu anexo dentro do conteúdo do script. Por exemplo: `from library import module` Tipo: string Obrigatório: nãoOutput Carga útil A representação JSON do objeto retornado pela função. Até 100 KB é retornado. Se você gerar uma lista, haverá o retorno de no máximo de 100 itens. ## Usar anexos com aws:executeScript Os anexos fornecem uma maneira poderosa de empacotar e reutilizar scripts complexos, vários módulos e dependências externas com suas ações `aws:executeScript`. Use anexos quando precisar: + Empacotar vários módulos Python ou scripts PowerShell juntos. + Reutilizar a mesma lógica de script em vários runbooks. + Incluir bibliotecas ou dependências externas em seus scripts. + Manter a definição do seu runbook limpa separando a lógica complexa do script. + Compartilhar pacotes de scripts entre equipes ou fluxos de trabalho de automação. ### Estrutura e empacotamento de anexos Você pode anexar arquivos únicos ou pacotes zip contendo vários arquivos. A estrutura depende do seu caso de uso: **Anexos de arquivo único** Para scripts simples, você pode anexar um único arquivo `.py` (Python) ou um arquivo `.zip` contendo um único script PowerShell. **Pacotes de vários módulos** Para automação complexa que requer vários módulos, crie um pacote zip com a seguinte estrutura recomendada: ``` my-automation-package.zip ├── main.py # Entry point script ├── utils/ │ ├── __init__.py # Required for Python module imports │ ├── helper_functions.py # Utility functions │ └── aws_operations.py # AWS-specific operations ├── config/ │ ├── __init__.py │ └── settings.py # Configuration settings └── requirements.txt # Optional: document dependencies ``` **Importante** Para pacotes Python, você deve incluir um arquivo `__init__.py` vazio em cada diretório que contém módulos Python. Isso permite importar módulos usando a sintaxe de importação padrão do Python, como `from utils import helper_functions`. **Estrutura do pacote PowerShell** Os anexos PowerShell devem ser empacotados em arquivos zip com a seguinte estrutura: ``` my-powershell-package.zip ├── Main.ps1 # Entry point script ├── Modules/ │ ├── HelperFunctions.ps1 # Utility functions │ └── AWSOperations.ps1 # AWS-specific operations └── Config/ └── Settings.ps1 # Configuration settings ``` ### Criar runbooks com anexos Siga estas etapas para criar runbooks que usam anexos: 1. **Faça o upload do seu anexo para o Amazon S3** Carregue seu arquivo de script ou pacote zip em um bucket do S3 que possa ser acessado por seu perfil de automação. Anote o URI do S3 para uso na próxima etapa. ``` aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/ ``` 1. **Calcule a soma de verificação do anexo** Calcule a soma de verificação SHA-256 do arquivo de anexo para verificação de segurança: ``` # Linux/macOS shasum -a 256 my-automation-package.zip # Windows PowerShell Get-FileHash -Algorithm SHA256 my-automation-package.zip ``` 1. **Defina a seção de arquivos em seu runbook** Adicione uma seção `files` no nível superior do seu runbook para fazer referência ao seu anexo: ``` files: my-automation-package.zip: checksums: sha256: "your-calculated-checksum-here" ``` 1. **Faça referência ao anexo em sua etapa executeScript** Use o parâmetro `Attachment` para fazer referência ao seu arquivo enviado: ``` - name: runMyScript action: aws:executeScript inputs: Runtime: python3.11 Handler: main.process_data Attachment: my-automation-package.zip InputPayload: inputData: "{{InputParameter}}" ``` ## Exemplos de anexos aws:executeScript Os exemplos a seguir demonstram maneiras diferentes de usar anexos com a ação `aws:executeScript`. ### Exemplo 1: anexo de arquivo único Este exemplo mostra como usar um único arquivo Python como anexo para processar dados da instância do EC2. **Arquivo do anexo: process\$1instance.py** Crie um arquivo Python com o seguinte conteúdo: ``` import boto3 import json def process_instance_data(events, context): """Process EC2 instance data and return formatted results.""" try: instance_id = events.get('instanceId') if not instance_id: raise ValueError("instanceId is required") ec2 = boto3.client('ec2') # Get instance details response = ec2.describe_instances(InstanceIds=[instance_id]) instance = response['Reservations'][0]['Instances'][0] # Format the response result = { 'instanceId': instance_id, 'instanceType': instance['InstanceType'], 'state': instance['State']['Name'], 'availabilityZone': instance['Placement']['AvailabilityZone'], 'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])} } print(f"Successfully processed instance {instance_id}") return result except Exception as e: print(f"Error processing instance: {str(e)}") raise ``` **Runbook completo** Aqui está o runbook completo que usa o anexo de arquivo único: ``` description: Process EC2 instance data using single file attachment schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: (Required) IAM role for automation execution InstanceId: type: String description: (Required) EC2 instance ID to process files: process_instance.py: checksums: sha256: "abc123def456..." mainSteps: - name: processInstance action: aws:executeScript inputs: Runtime: python3.11 Handler: process_instance.process_instance_data Attachment: process_instance.py InputPayload: instanceId: '{{InstanceId}}' outputs: - Type: StringMap Name: InstanceData Selector: $.Payload outputs: - processInstance.InstanceData ``` ### Exemplo 2: pacote de vários módulos Este exemplo demonstra o uso de um pacote zip contendo vários módulos Python para operações complexas de bucket do S3. **Estrutura do pacote** Crie um pacote zip com a seguinte estrutura: ``` s3-operations.zip ├── main.py ├── utils/ │ ├── __init__.py │ ├── s3_helper.py │ └── validation.py └── config/ ├── __init__.py └── settings.py ``` **main.py (ponto de entrada)** O script principal que orquestra as operações: ``` from utils.s3_helper import S3Operations from utils.validation import validate_bucket_name from config.settings import get_default_settings def cleanup_s3_bucket(events, context): """Clean up S3 bucket based on specified criteria.""" try: bucket_name = events.get('bucketName') max_age_days = events.get('maxAgeDays', 30) # Validate inputs if not validate_bucket_name(bucket_name): raise ValueError(f"Invalid bucket name: {bucket_name}") # Initialize S3 operations s3_ops = S3Operations() settings = get_default_settings() # Perform cleanup deleted_objects = s3_ops.delete_old_objects( bucket_name, max_age_days, settings['dry_run'] ) result = { 'bucketName': bucket_name, 'deletedCount': len(deleted_objects), 'deletedObjects': deleted_objects[:10], # Return first 10 for brevity 'dryRun': settings['dry_run'] } print(f"Cleanup completed for bucket {bucket_name}") return result except Exception as e: print(f"Error during S3 cleanup: {str(e)}") raise ``` ## Solução de problemas de anexos aws:executeScript Use as diretrizes a seguir para resolver problemas comuns com anexos `aws:executeScript`: **Erros de importação de módulos** Se você receber erros de importação ao usar pacotes com vários módulos: + Certifique-se de ter incluído um arquivo `__init__.py` vazio em cada diretório contendo módulos Python. + Verifique se suas instruções de importação correspondem à estrutura real de arquivos e diretórios em seu pacote zip. + Use importações relativas (por exemplo, `from .utils import helper`) ou importações absolutas (por exemplo, `from utils import helper`) de forma consistente. **Erros de anexo não encontrado** Se sua automação não conseguir encontrar o anexo: + Verifique se o valor do parâmetro `Attachment` corresponde exatamente à chave em sua seção `files`. + Verifique se o caminho e o nome do arquivo do bucket do S3 estão corretos na seção `files`. + Certifique-se de que seu perfil de automação tenha permissão `s3:GetObject` para a localização do anexo do S3. + Verifique se a soma de verificação em seu runbook corresponde à soma de verificação real do arquivo. **Erros de função do manipulador** Se você receber erros relacionados ao manipulador: + Em Python: use o formato `filename.function_name` no parâmetro `Handler` (por exemplo, `main.process_data`). + Certifique-se de que sua função de manipulador aceite exatamente dois parâmetros: `events` e `context`. + Em PowerShell: não especifique um parâmetro `Handler`; o script é executado diretamente. **Falhas de execução de script** Se o script falhar durante a execução: + Verifique o histórico de execução da automação para mensagens de erro detalhadas e rastreamentos de pilha. + Use instruções `print()` (Python) ou `Write-Information` (PowerShell) para adicionar a saída de depuração. + Verifique se todas as permissões AWS necessárias foram concedidas à sua função de automação. + Teste a lógica do seu script localmente antes de empacotá-lo como um anexo. **Tratamento de erros e códigos de saída** Para lidar adequadamente com erros e códigos de saída de retorno: + Em Python: use `raise Exception("error message")` para indicar falha no script. + Em PowerShell: use `throw "error message"` ou `Write-Error` para indicar falha. + Retorne dados estruturados de suas funções para fornecer informações detalhadas de êxito/falha. + Use blocos try-catch para lidar com exceções de forma elegante e fornecer mensagens de erro significativas.