Migrando da Ferramentas da AWS para PowerShell versão 4 para a versão 5 - Ferramentas da AWS para PowerShell (versão 5)

A versão 5 (V5) do Ferramentas da AWS para PowerShell foi lançada!

Para obter informações sobre mudanças significativas e migrar seus aplicativos, consulte o tópico de migração.

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

Migrando da Ferramentas da AWS para PowerShell versão 4 para a versão 5

Ferramentas da AWS para PowerShell a versão 5 (V5) tem alterações significativas, o que pode fazer com que seus scripts existentes parem de funcionar. Este tópico descreve as mudanças importantes na V5 e o possível trabalho que talvez você precise fazer para migrar seu ambiente ou código da V4.

Para obter informações adicionais sobre mudanças notáveis no, consulte Ferramentas da AWS para PowerShell também os seguintes recursos:

nota

Como Ferramentas da AWS para PowerShell dependem do AWS SDK para .NET, algumas das mudanças relacionadas à V4 do SDK também podem afetar a V5 do Tools for. PowerShell Para ver o que mudou na V4 do AWS SDK para .NET, consulte as informações de migração no Guia do AWS SDK para .NET desenvolvedor.

PowerShell Versão mínima

Para a versão antiga, específica para Windows, de módulo único e grande do Ferramentas da AWS para PowerShell, chamada AWSPowerShell, a versão mínima suportada PowerShell do módulo foi atualizada para 5.1. Isso deve corresponder à AWS SDK para .NET nova versão mínima do.NET Framework 4.7.2.

Para obter mais informações sobre o módulo AWSPower Shell legado, consulteInstalar no Windows.

Instale ou atualize a AWS.Tools V4

Ao instalar ou atualizar a versão modularizada dos Update-AWSToolsModule cmdlets Ferramentas da AWS para PowerShell, chamada, the Install-AWSToolsModule eAWS.Tools, naturalmente, usará a versão 5 do por padrão. AWS.Tools Se, por algum motivo, você precisar instalar ou atualizar a versão 4 doAWS.Tools, poderá fazer isso usando os seguintes comandos, respectivamente:

Install-AWSToolsModule -MaximumVersion '4.9.999' Update-AWSToolsModule -MaximumVersion '4.9.999'

Para obter informações adicionais sobre a instalação e atualização do Tools for PowerShell, consulte Conceitos básicos

Cancelar a execução do cmdlet com CTRL+C e CMD+C

A versão 5 do Ferramentas da AWS para PowerShell permite cancelar a execução do cmdlet usando um atalho de teclado, como CTRL+C ou CMD+C.

Tipos de valores anuláveis

Os tipos adotados do AWS SDK para .NET foram atualizados para usar as novas alterações anuláveis do SDK. Por exemplo, propriedades do tipo int foram alteradas paraNullable[int]. Essa alteração não afeta a forma como os valores dos parâmetros de entrada são especificados para os cmdlets da AWS porque esses parâmetros de tipo de valor já foram modelados como anuláveis. No entanto, os tipos anuláveis para a saída do cmdlet são uma alteração importante porque as propriedades na saída do cmdlet conterão, $null em vez dos vários valores padrão dos tipos.

O exemplo a seguir demonstra o comportamento na V4 do Tools for. PowerShell Neste exemplo, a MissingMeta propriedade é definida como 0 porque esse é o valor padrão do tipoint.

# In V4 PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled ------------ ----------- ------------------------- ---------------- 8/29/2023 10:20:44 PM 0 1/1/0001 12:00:00 AM

O exemplo a seguir demonstra o comportamento na V5 do Tools for. PowerShell Neste exemplo, a MissingMeta propriedade está definida como$null.

# In V5 PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled ------------ ----------- ------------------------- ---------------- 8/29/2023 10:20:44 PM

Na maioria dos casos, nenhuma alteração de código é necessária porque PowerShell tem conversão implícita de tipos de valores anuláveis para tipos de valores não anuláveis. No entanto, essa é uma alteração importante no código de lógica de comparação que verifica explicitamente o valor padrão de um tipo de valor anulável. A lógica de comparação que verifica o valor padrão de um tipo não anulável deve ser modificada para verificação. $null

Para alguns desses tipos, os exemplos a seguir mostram como atualizar o código escrito para a V4 que verifica se nada foi retornado:

#Type int: # In V4, if you were checking whether an int is 0... if($s3Metadata.MissingMeta -eq 0){} # In V5, check if the int is null instead: if($s3Metadata.MissingMeta -eq $null) {} # Type datetime: # In V4, if you were checking whether a datetime is '0001-01-01'... if($s3Metadata.ObjectLockRetainUntilDate -eq '0001-01-01'){} # In V5, check if the datetime is null instead: if($s3Metadata.ObjectLockRetainUntilDate -eq $null){} # Type boolean: # In V4, if you were checking whether a boolean is $false... if($s3Metadata.BucketKeyEnabled -eq $false){} # In V5, check if the boolean is null instead: if($s3Metadata.BucketKeyEnabled -eq $null)

Como Ferramentas da AWS para PowerShell dependem do AWS SDK para .NET, pode ser útil examinar como mudanças semelhantes afetaram a versão 4 do SDK. Para encontrar essas informações, consulte o conteúdo de migração de tipos de valor no Guia do AWS SDK para .NET desenvolvedor.

Coleções

Algumas saídas de cmdlet foram alteradas para retornar $null em vez de coleções vazias do tipo List ou. Dictionary Para obter informações adicionais, incluindo como reverter para o comportamento legado, consulte o conteúdo de migração para Coleções no Guia do AWS SDK para .NET Desenvolvedor.

DateTime versus UTC DateTime

Alguns cmdlets V4 definem DateTime parâmetros que são obsoletos, bem como parâmetros UTC alternativos. DateTime Esses DateTime parâmetros obsoletos foram removidos dos cmdlets V5 e o nome dos parâmetros UTC foi alterado para o nome original dos DateTime parâmetros não UTC. DateTime

A seguir estão alguns exemplos de cmdlets para os quais essa alteração foi implementada.

  • Get-ASScheduledAction(cmdlet V4 e cmdlet V5):

    • O StartTime parâmetro foi removido e o nome do UtcStartTime parâmetro foi alterado para "StartTime”.

    • O EndTime parâmetro foi removido e o nome do UtcEndTime parâmetro foi alterado para "EndTime”.

  • Copy-S3Object(cmdlet V4 e cmdlet V5):

    • O ModifiedSinceDate parâmetro foi removido e o nome do UtcModifiedSinceDate parâmetro foi alterado para "ModifiedSinceDate”.

    • O UnmodifiedSinceDate parâmetro foi removido e o nome do UtcUnmodifiedSinceDate parâmetro foi alterado para "UnmodifiedSinceDate”.

A seguir está uma lista completa dos cmdlets afetados por essa alteração.

Tubulação e $AWSHistory

Nas versões Ferramentas da AWS para PowerShell anteriores à V4, $AWSHistory foi introduzida uma variável de sessão chamada que mantém um registro das invocações de AWS cmdlet e das respostas de serviço recebidas para cada invocação.

Na V4 do Tools for PowerShell, essa variável de sessão foi descontinuada em favor do -Select * parâmetro e do argumento, que podem ser usados para retornar toda a resposta do serviço. O -Select * parâmetro é descrito emPipelining, saída e iteração.

Na V5 do Tools for PowerShell, a variável de $AWSHistory sessão foi removida completamente. Como consequência, os Set-AWSHistoryConfiguration cmdlets Clear-AWSHistory e também foram removidos.

O parâmetro -PassThru

O -PassThru parâmetro foi removido. Quando um cmdlet não retorna nenhuma saída por padrão, os usuários podem solicitar um valor de parâmetro retornado usando. -Select ^ParameterName Para obter mais detalhes e exemplos, consulte a postagem do blog Preview 1 of Ferramentas da AWS para PowerShell V5.

Alguns cmdlets do DynamoDB foram movidos e renomeados

Os Get-DDBStreamList cmdlets Get-DDBStream e foram movidos do módulo Dynamo para um novo DBV2 módulo chamado Dynamo. DBStreams Eles também foram renomeados para Get- DDBSStream e Get- DDBSStream List, respectivamente.

Registro de informações confidenciais

O comportamento de registro foi alterado para que informações potencialmente confidenciais tenham menos probabilidade de serem incluídas na saída do cmdlet, especialmente em CI/CD situações. Para obter mais informações e instruções sobre como reverter para o comportamento V4, consulte. Registro de informações confidenciais

Resolução de perfil e credenciais

Eles Ferramentas da AWS para PowerShell foram atualizados para usar determinadas variáveis de ambiente ao resolver as credenciais de um cmdlet:AWS_PROFILE,,, e. AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN Além disso, houve algumas mudanças na ordem de resolução de credenciais e perfis. Para obter mais informações, consulte Resolução de perfil e credenciais.

Mensagem de erro de credencial

A mensagem de erro que ele Ferramentas da AWS para PowerShell retorna se não conseguir obter as credenciais apropriadas foi alterada.

Na v4 das ferramentas, a mensagem era semelhante à seguinte:

Get-SFNExecutionList -Region us-west-2 Get-SFNExecutionList: No credentials specified or obtained from persisted/shell defaults.

Na V5 das ferramentas, a mensagem é semelhante à seguinte:

Get-SFNExecutionList -Region us-west-2 Get-SFNExecutionList: Failed to resolve AWS credentials. The credential providers used to search for credentials returned the following errors: ... <list of specific exceptions>

Iteração automática consistente

Todos os cmdlets paginados foram atualizados para iterar automaticamente todos os dados por padrão. Você pode reverter esse comportamento usando o AWSAuto IterationMode cmdlet Set-. Se você executarSet-AWSAutoIterationMode -IterationMode v4, as operações que foram iteradas automaticamente na v4 ainda serão iteradas automaticamente, mas o resto será revertido para iteração manual. Para determinar em qual modo a iteração automática está definida, use o cmdlet Get- AWSAuto IterationMode.

Para ver um exemplo de um cmdlet que foi atualizado dessa forma, consulte o cmdlet (cmdlet V4 e Get-CWLLogEvent cmdlet V5).

Para obter detalhes sobre a iteração automática, consulte. Iteração por meio de dados paginados

Cmdlets do S3 obsoletos e substituídos

Para o Amazon S3, os cmdlets Get-S3Acl e Set-S3Acl foram descontinuados. Em vez disso, use os seguintes novos cmdlets: Get-S3BucketACL, ACL, Set-S3BucketACL, Get-S3Object ACL. Set-S3Object

Parâmetros-chave de limpeza e corte do S3

Alguns cmdlets do Amazon S3 aceitam parâmetros chamados e. Key KeyPrefix A V4 do Ferramentas da AWS para PowerShell limparia e cortaria esses parâmetros das seguintes maneiras: removeria espaços iniciais, barras avançadas (“/”) e barras invertidas (“\”), converteria todas as outras barras invertidas em barras e removeria espaços finais. Na V5 do Tools for PowerShell, esse não é mais o comportamento padrão. Você pode reverter esse comportamento especificando o -EnableLegacyKeyCleaning parâmetro.

Essas informações se aplicam aos seguintes cmdlets:

Capacidades de sessão interativa

Os recursos de sessão interativa foram adicionados ao SSMSession cmdlet Start-, que se alinha ao comportamento. AWS CLI Por exemplo:

Start-SSMSession -Target 'i-1234567890abcdef0'

Se você precisar de um comportamento legado, inclua o -DisablePluginInvocation parâmetro no Start-SSMSession comando.

CloudWatch alarmes

O CWAlarm cmdlet Get- foi atualizado para retornar alarmes métricos e compostos da CloudWatch Amazon por padrão. Para limitar a saída a alarmes métricos ou compostos, você deve especificar o -AlarmType parâmetro: Get-CWAlarm -AlarmType 'MetricAlarms' ouGet-CWAlarm -AlarmType 'CompositeAlarms', respectivamente.

LitJson

Eles Ferramentas da AWS para PowerShell foram atualizados para uso System.Text.Json em vez LitJson de serialização. LitJsonfoi removido da V5 das ferramentas.

A propriedade LoggedAt de saída

A propriedade LoggedAt de saída foi removida. Na V4 das ferramentas, essa propriedade foi retornada por padrão em alguns cmdlets (por exemplo Get-SSMCommandInvocationDetail e). Invoke-LMFunction

Se precisar replicar as informações fornecidas pela propriedade de LoggedAt saída, você pode incluir algo semelhante ao seguinte em seus scripts:

$loggedAt = (Get-Date).ToUniversalTime().ToString('s')

Elementos de programação que foram removidos

Vários elementos de programação foram removidos da V5 do Tools for PowerShell. Eles estão listados abaixo, se ainda não foram abordados anteriormente, junto com as possíveis etapas que você pode tomar para acomodar sua remoção, se houver.