Migrieren von der AWS Tools for PowerShell-Version 3.3 zu Version 4

AWS Tools for PowerShell Version 4 ist ein abwärtskompatibles Update auf AWS Tools for PowerShell Version 3.3. Es wurde um erhebliche Verbesserungen ergänzt, gleichzeitig bleibt das vorhandene Cmdlet-Verhalten beibehalten.

Ihre vorhandenen Skripts sollten nach dem Upgrade auf die neue Version weiterhin funktionieren. Wir empfehlen jedoch, sie gründlich zu testen, bevor Sie Ihre Produktionsumgebungen aktualisieren.

In diesem Abschnitt werden die Änderungen beschrieben und wird erläutert, wie sich diese auf Ihre Skripts auswirken können.

Vollständig modularisierte AWS.Tools-Version

Die Pakete AWSPowerShell. NetCore und AWSPowerShell waren „monolithisch“. Dies bedeutete, dass alle AWS-Services im selben Modul unterstützt wurden, wodurch es sehr groß wurde und mit jedem neuen AWS-Service und jeder neuen Funktion noch größer wurde. Das neue AWS.Tools Paket ist in kleinere Module unterteilt, die Ihnen die Flexibilität geben, nur diejenigen herunterzuladen und zu installieren, die Sie für die von Ihnen verwendeten AWS-Services benötigen. Das Paket enthält ein gemeinsames AWS.Tools.Common-Modul, das von allen anderen Modulen benötigt wird, und ein AWS.Tools.Installer-Modul, das das Installieren, Aktualisieren und Entfernen von Modulen bedarfsgerecht vereinfacht.

Dies ermöglicht auch das automatische Importieren von Cmdlets beim ersten Aufruf, ohne dass zunächst Import-module aufgerufen werden muss. Um jedoch vor dem Aufruf eines Cmdlets mit den zugehörigen .NET-Objekten zu interagieren, müssen Sie trotzdem aufrufen, Import-Module um PowerShell über die relevanten .NET-Typen informiert zu werden.

Der folgende Befehl umfasst beispielsweise einen Verweis auf Amazon.EC2.Model.Filter. Dieser Referenztyp kann den automatischen Import nicht auslösen. Damit der Befehl nicht fehlschlägt, müssen Sie zunächst Import-Module aufrufen.

PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
  InvalidOperation: Unable to find type [Amazon.EC2.Model.Filter].

PS > Import-Module AWS.Tools.EC2
PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}
PS > Get-EC2Instance -Filter $filter -Select Reservations.Instances.InstanceId
  i-0123456789abcdefg
  i-0123456789hijklmn

Neues Get-AWSService-Cmdlet

Damit Sie die Namen der Module für jeden AWS-Service in der AWS.Tools Modulsammlung ermitteln können, können Sie das Get-AWSService-Cmdlet verwenden.

PS > Get-AWSService
  Service : ACMPCA
  CmdletNounPrefix : PCA
  ModuleName : AWS.Tools.ACMPCA
  SDKAssemblyVersion : 3.3.101.56
  ServiceName : Certificate Manager Private Certificate Authority

  Service : AlexaForBusiness
  CmdletNounPrefix : ALXB
  ModuleName : AWS.Tools.AlexaForBusiness
  SDKAssemblyVersion : 3.3.106.26
  ServiceName : Alexa For Business
  ...

Neuer -Select-Parameter zum Steuern des von einem Cmdlet zurückgegebenen Objekts

Die meisten Cmdlets der Version 4 unterstützen einen neuen -Select-Parameter. Jedes Cmdlet ruft für Sie mittels AWS SDK for .NET die AWS-Service-APIs auf. Anschließend konvertiert der AWS Tools for PowerShell Client die Antwort in ein Objekt, das Sie in Ihren PowerShell Skripten verwenden können, und Pipe-Befehlen an andere Befehle. Manchmal enthält das endgültige PowerShell Objekt mehr Felder oder Eigenschaften in der ursprünglichen Antwort, als Sie benötigen, und andere Male möchten Sie möglicherweise, dass das Objekt Felder oder Eigenschaften der Antwort enthält, die standardmäßig nicht vorhanden sind. Mit dem -Select-Parameter können Sie angeben, was in dem vom Cmdlet zurückgegebenen NET-Objekt enthalten sein soll.

Beispielsweise ruft das Get-S3Object-Cmdlet die Amazon S3-SDK-Operation aufListObjects. Diese Operation gibt ein -ListObjectsResponseObjekt zurück. Standardmäßig gibt das Get-S3Object Cmdlet jedoch nur das S3Objects Element der SDK-Antwort an den PowerShell Benutzer zurück. Im folgenden Beispiel ist dieses Objekt ein Array mit zwei Elementen.

PS > Get-S3Object -BucketName mybucket

ETag : "01234567890123456789012345678901111"
BucketName : mybucket
Key : file1.txt
LastModified : 9/30/2019 1:31:40 PM
Owner : Amazon.S3.Model.Owner
Size : 568
StorageClass : STANDARD

ETag : "01234567890123456789012345678902222"
BucketName : mybucket
Key : file2.txt
LastModified : 7/15/2019 9:36:54 AM
Owner : Amazon.S3.Model.Owner
Size : 392
StorageClass : STANDARD

In AWS Tools for PowerShell Version 4 können Sie -Select * so definieren, dass das vollständige .NET-Antwortobjekt zurückgegeben wird, das vom SDK-API-Aufruf zurückgegeben wird.

PS > Get-S3Object -BucketName mybucket -Select *
  IsTruncated    : False
  NextMarker     :
  S3Objects      : {file1.txt, file2.txt}
  Name           : mybucket
  Prefix         :
  MaxKeys        : 1000
  CommonPrefixes : {}
  Delimiter      :

Sie können auch den Pfad zu der gewünschten verschachtelten Eigenschaft angeben. Im folgenden Beispiel wird nur die Key-Eigenschaft jedes Elements im S3Objects-Array zurückgegeben.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key
file1.txt
file2.txt

In bestimmten Situationen kann es sinnvoll sein, einen Cmdlet-Parameter zurückzugeben. Sie können dies mit -Select ^ParameterName tun. Diese Funktion ersetzt den -PassThru-Parameter, der zwar noch verfügbar, aber veraltet ist.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key |
>> Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -Tagging_TagSet @{ Key='key'; Value='value'}
  file1.txt
  file2.txt

Das Referenzthema für jedes Cmdlet erkennt, ob es den Parameter -Select unterstützt.

Konsistentere Begrenzung der Anzahl der Elemente in der Ausgabe

In früheren Versionen von AWS Tools for PowerShell konnten Sie mit dem -MaxItems-Parameter die maximale Anzahl von Objekten angeben, die in der endgültigen Ausgabe zurückgegeben werden sollen.

Dieses Verhalten wird aus AWS.Tools entfernt.

Dieses Verhalten ist in und veraltet AWSPowerShellNetCore AWSPowerShellund wird in einer zukünftigen Version aus diesen Versionen entfernt.

Wenn die zugrunde liegende Service-API einen MaxItems-Parameter unterstützt, ist er weiterhin verfügbar und funktioniert wie in der API angegeben. Aber er verfügt nicht mehr über das zusätzliche Verhalten, die Anzahl der Elemente zu begrenzen, die in der Ausgabe des Cmdlets zurückgegeben werden.

Um die Anzahl der Elemente zu begrenzen, die in der endgültigen Ausgabe zurückgegeben werden, übergeben Sie die Ausgabe an das Select-Object-Cmdlet und geben Sie den -First n-Parameter an, wobei n die maximale Anzahl von Elementen ist, die in die endgültige Ausgabe aufgenommen werden sollen.

PS > Get-S3ObjectV2 -BucketName BUCKET_NAME -Select S3Objects.Key | select -first 2
file1.txt
file2.txt

Nicht alle AWS-Services unterstützten -MaxItems auf die gleiche Weise, sodass diese Inkonsistenz und die unerwarteten Ergebnisse, die manchmal vorgekommen sind, damit beseitigt werden. Außerdem konnte -MaxItems in Kombination mit dem neuen -Select-Parameter zuweilen zu irritierenden Ergebnissen führen.

Einfachere Verwendung von Stream-Parametern

Parameter vom Typ Stream oder byte[] können nun string-, string[]- oder FileInfo-Werte übernehmen.

Sie können z. B. eines der folgenden Beispiele verwenden.

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream '{
>> "some": "json"
>> }'

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream (ls .\some.json)

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream @('{', '"some": "json"', '}')

AWS Tools for PowerShell wandelt mittels UTF-8-Codierung alle Zeichenfolgen in byte[] um.

Erweitern der Pipe um den Eigenschaftsnamen

Um die Benutzererfahrung konsistenter zu gestalten, können Sie nun Pipeline-Eingaben übergeben, indem Sie den Eigenschaftsnamen für einen beliebigen Parameter angeben.

Im folgenden Beispiel erstellen wir ein benutzerdefiniertes Objekt mit Eigenschaften, die Namen aufweisen, die mit den Parameternamen des Ziel-Cmdlets übereinstimmen. Wenn das Cmdlet ausgeführt wird, werden diese Eigenschaften automatisch als dessen Parameter verwendet.

PS > [pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get-S3ObjectMetadata

Anmerkung

Einige Eigenschaften unterstützten dies in früheren Versionen von AWS Tools for PowerShell. Mit Version 4 erfolgt dies konsequenter, indem es für alle Parameter aktiviert wird.

Statische gängige Parameter

Um die Konsistenz in Version 4.0 von AWS Tools for PowerShell zu verbessern, sind alle Parameter statisch.

In früheren Versionen von AWS Tools for PowerShell waren einige gängige Parameter wie AccessKey,SecretKey, ProfileName oder Region dynamisch, während alle anderen Parameter statisch waren. Dies könnte zu Problemen führen, da statische Parameter vor dynamischen Parametern PowerShell bindet. Angenommen, Sie haben den folgenden Befehl ausgeführt:

PS > Get-EC2Region -Region us-west-2

Frühere Versionen von PowerShell binden den Wert us-west-2 an den -RegionName statischen Parameter anstelle des -Region dynamischen Parameters an. Dies konnte Benutzer durchaus irritieren.

AWS.Tools deklariert und erzwingt obligatorische Parameter

Die Module AWS.Tools.* deklarieren und erzwingen nun obligatorische Cmdlet-Parameter. Wenn ein -AWSService angibt, dass ein Parameter einer API erforderlich ist, PowerShell fordert Sie auf, den entsprechenden Cmdlet-Parameter einzugeben, wenn Sie ihn nicht angegeben haben. Dies gilt nur für AWS.Tools. Um die Abwärtskompatibilität zu gewährleisten, gilt dies nicht für AWSPowerShell. NetCore oder AWSPowerShell.

Alle Parameter sind löschbar

Sie können nun den Werttyp-Parametern (Zahlen und Daten) $null zuordnen. Diese Änderung sollte sich nicht auf vorhandene Skripte auswirken. Auf diese Weise können Sie die Eingabeaufforderung für einen obligatorischen Parameter umgehen. Obligatorische Parameter werden nur in AWS.Tools erzwungen.

Wenn Sie das folgende Beispiel mit Version 4 ausführen, wird die clientseitige Validierung effektiv umgangen, da Sie für jeden obligatorischen Parameter einen „Wert“ angeben. Der Aufruf des Amazon-EC2-API-Services schlägt jedoch fehl, da der AWS-Service diese Information weiterhin benötigt.

PS > Get-EC2InstanceAttribute -InstanceId $null -Attribute $null
WARNING: You are passing $null as a value for parameter Attribute which is marked as required.
In case you believe this parameter was incorrectly marked as required, report this by opening 
an issue at https://github.com/aws/aws-tools-for-powershell/issues.
WARNING: You are passing $null as a value for parameter InstanceId which is marked as required.
In case you believe this parameter was incorrectly marked as required, report this by opening
an issue at https://github.com/aws/aws-tools-for-powershell/issues.

Get-EC2InstanceAttribute : The request must contain the parameter instanceId

Entfernen von zuvor nicht unterstützten Funktionen

Die folgenden Funktionen wurden in früheren Releases von AWS Tools for PowerShell nicht unterstützt und werden in Version 4 entfernt:

• Der -Terminate-Parameter wurde aus dem Stop-EC2Instance-Cmdlet entfernt. Verwenden Sie stattdessen Remove-EC2Instance.

• Der -ProfileName Parameter wurde aus dem Clear-AWSCredential cmdlet entfernt. Verwenden Sie stattdessen Remove-AWSCredentialProfile.

• Es wurden die Cmdlets Import-EC2Instance und Import-EC2Volume entfernt.