Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Upgrade von Version 2 des AWS SDK for PHP

Dieses Thema zeigt, wie Sie Ihren Code auf die Version 3 des AWS SDK for PHP migrieren und wie sich die neue Version von der Version 2 des SDK unterscheidet.

Einführung

Mit Version 3 des AWS SDK for PHP wurde ein enormer Aufwand unternommen, die Fähigkeiten des SDK zu verbessern, über zwei Jahre lang Kundenfeedback zu integrieren, unsere Abhängigkeiten zu aktualisieren, die Leistung zu verbessern und die neuesten PHP-Standards zu übernehmen.

Was ist neu in Version 3?

Version 3 AWS SDK for PHP folgt den Standards PSR-4 und PSR-7 und wird in Zukunft dem SemVerStandard folgen.

Zu den weiteren neuen Funktionen zählen:

Entkoppelte HTTP-Schicht

Asynchrone Anfragen

Was sind die Unterschiede gegenüber Version 2?

Projektabhängigkeiten wurden aktualisiert

Die Abhängigkeiten des SDK wurden in dieser Version geändert.

Regions- und Versionsoptionen sind jetzt erforderlich

Bei der Instanziierung eines Clients für beliebige Services müssen Sie die Optionen 'region' und 'version' angeben. In Version 2 von AWS SDK for PHP war 'version' vollständig optional, und 'region' war mitunter optional. In Version 3 sind beide immer erforderlich. Wenn Sie diese beiden Optionen explizit angeben, können Sie sich auf die API-Version und die AWS Region festlegen, für die Sie codieren. Wenn neue API-Versionen erstellt werden oder neue AWS Regionen verfügbar werden, sind Sie von potenziell wichtigen Änderungen isoliert, bis Sie bereit sind, Ihre Konfiguration explizit zu aktualisieren.

Client-Instanziierung verwendet den Konstruktor

In Version 3 des AWS SDK for PHP hat sich die Art und Weise geändert, wie Sie ein Client instanziiert wird. Anstelle der factory-Methoden in Version 2, können Sie einen Client einfach mithilfe des Schlüsselworts new instanziieren.

use Aws\DynamoDb\DynamoDbClient;

// Version 2 style
$client = DynamoDbClient::factory([
    'region'  => 'us-east-2'
]);

// Version 3 style
$client = new DynamoDbClient([
    'region'  => 'us-east-2',
    'version' => '2012-08-10'
]);

Die Client-Konfiguration hat sich geändert

Die Client-Konfigurationsoptionen in Version 3 des AWS SDK for PHP hat sich gegenüber Version 2 ein wenig geändert. Auf der Seite Konfiguration für AWS SDK for PHP Version 3 finden Sie eine Beschreibung aller unterstützten Optionen.

Das Sdk-Objekt

In Version 3 des AWS SDK for PHP wird das Aws\Sdk-Objekt als Ersatz für Aws\Common\Aws eingeführt. Das Sdk-Objekt fungiert als Client-Factory und wird verwendet, um gemeinsame Konfigurationsoptionen für mehrere Clients zu verwalten.

Obwohl die Aws-Klasse in Version 2 des SDK funktioniert hat wie ein Service Locator (sie gab immer dieselbe Instance eines Clients zurück), gibt die Sdk-Klasse in Version 3 bei jeder Verwendung eine neue Instance eines Clients zurück.

Das Sdk-Objekt unterstützt auch nicht dasselbe Konfigurationsdateiformat wie Version 2 des SDK. Dieses Konfigurationsformat war spezifisch für Guzzle 3 und ist jetzt veraltet. Die Konfiguration kann einfacher mit grundlegenden Arrays erfolgen und ist in Verwendung der Sdk-Klasse dokumentiert.

Einige API-Ergebnisse haben sich geändert

Um die Konsistenz bei der Analyse des Ergebnisses einer API-Operation durch das SDK zu gewährleisten, verfügen AmazonElastiCache, Amazon RDS und Amazon Redshift jetzt über ein zusätzliches Wrapping-Element für einige API-Antworten.

Zum Beispiel enthält der Aufruf des Amazon DescribeEngineDefaultParametersRDS-Ergebnisses in Version 3 jetzt ein umhüllendes „EngineDefaults“ -Element. In Version 2 war dieses Element nicht vorhanden.

$client = new Aws\Rds\RdsClient([
    'region'  => 'us-west-1',
    'version' => '2014-09-01'
]);

// Version 2
$result = $client->describeEngineDefaultParameters();
$family = $result['DBParameterGroupFamily'];
$marker = $result['Marker'];

// Version 3
$result = $client->describeEngineDefaultParameters();
$family = $result['EngineDefaults']['DBParameterGroupFamily'];
$marker = $result['EngineDefaults']['Marker'];

Die folgenden Operationen sind betroffen und enthalten jetzt ein Wrapping-Element in der Ausgabe des Ergebnisses (nachfolgend in Klammern gezeigt):

Aufzählungsklassen wurden entfernt

Wir haben die Enum-Klassen entfernt (z. B. Aws\S3\Enum\CannedAcl), die es in Version 2 des AWS SDK for PHP gab. Aufzählungen waren konkrete Klassen innerhalb der öffentlichen API des SDK, die Konstanten enthielten, die Gruppen von gültigen Parameterwerten darstellten. Da diese Aufzählungen spezifisch für API-Versionen sind, sich im Laufe der Zeit ändern können, mit PHP reservierten Wörtern kollidieren können und letztendlich nicht sehr nützlich sind, haben wir sie in Version 3 entfernt. Dies unterstützt die datengesteuerte und von der API-Version unabhängige Natur von Version 3.

Verwenden Sie anstelle von Werten aus Enum-Objekten direkt die literalen Werte (z. B. CannedAcl::PUBLIC_READ → 'public-read').

Differenzierte Ausnahmeklassen wurden entfernt

Wir haben die differenzierten Ausnahmeklassen entfernt, die es in den Namespaces jedes Services gab (zum Beispiel Aws\Rds\Exception\{SpecificError}Exception). Die Gründe dafür sind sehr ähnlich denjenigen, aus denen wir Enums entfernt haben. Die Ausnahmen, die von einem Service oder einer Operation aufgeworfen werden, sind abhängig davon, welche API-Version verwendet wird (sie können von Version zu Version wechseln). Außerdem ist die vollständige Liste der Ausnahmen, die durch eine bestimmte Operation ausgegeben werden können, nicht verfügbar, wodurch die differenzierten Ausnahmeklassen der Version 2 unvollständig wurden.

Verarbeiten Sie Fehler, indem Sie die Root-Ausnahmeklasse für jeden Service abfangen (z. B. Aws\Rds\Exception\RdsException). Sie können die getAwsErrorCode()-Methode der Ausnahme verwenden, um auf bestimmte Fehlercodes zu prüfen. Dies ist funktional äquivalent zum Abfangen verschiedener Ausnahmeklassen, bietet aber diese Funktion, ohne das SDK aufzublähen.

Statische Fassadenklassen wurden entfernt

In der Version 2 des AWS SDK for PHP gab es eine obskure Funktion, die von Laravel inspiriert worden war, und die es erlaubte, enableFacades() für die Aws-Klasse aufzurufen, um den statischen Zugriff auf die verschiedenen Service-Clients zu ermöglichen. Diese Funktion widerspricht den Best Practices von PHP, und wir haben vor über einem Jahr aufgehört, sie zu dokumentieren. In Version 3 wurde diese Funktion vollständig entfernt. Rufen Sie Ihre Client-Objekte aus dem Aws\Sdk-Objekt ab und verwenden Sie sie als Objekt-Instances, nicht als statische Klassen.

Paginatoren ersetzen Iteratoren

Version 2 von AWS SDK for PHP hatte eine Funktion namens * iterators*. Dies waren Objekte, die zur Iteration paginierter Ergebnisse verwendet wurden. Eine Beschwerde, die wir dazu hatten, war, dass sie nicht flexibel genug waren, da der Iterator nur bestimmte Werte von jedem Ergebnis ausgab. Wenn es andere Werte gab, die Sie aus den Ergebnissen brauchten, konnten Sie diese nur über Ereignis-Listener abrufen.

In Version 3 wurden Iteratoren durch Paginatoren ersetzt. Ihr Zweck ist ähnlich, aber Paginatoren sind viel flexibler. Dies liegt daran, dass sie Ergebnisobjekte anstelle von Werten aus einer Antwort liefern.

Die folgenden Beispiele zeigen, wie sich Paginatoren von Iteratoren unterscheiden, indem demonstriert wird, wie paginierte Ergebnisse für die S3 ListObjects-Operation in Version 2 und Version 3 abgerufen werden.

// Version 2
$objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}

// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($results as $result) {
    // You can extract any data that you want from the result.
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}

Paginator-Objekte haben eine search()-Methode, die Ihnen ermöglicht, JMESPath-Ausdrücke zu verwenden, womit Daten aus der Ergebnismenge einfacher extrahiert werden können.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']);
foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}

Viele übergeordnete Abstraktionen haben sich geändert

Generell wurden viele der übergeordneten Abstraktionen (neben den Clients auch Service-spezifische Helferobjekte) verbessert oder aktualisiert. Einige wurden sogar entfernt.

Vergleich von Codebeispielen aus beiden Versionen des SDK

Die folgenden Beispiele zeigen, wie sich die Verwendung der Version 3 von AWS SDK for PHP von der Version 2 unterscheiden kann.

Beispiel: Amazon ListObjects S3-Betrieb

Aus Version 2 des SDK

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = S3Client::factory([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'my-bucket-name',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

Aus Version 3 des SDK

Wichtigste Unterschiede:

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = new S3Client([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1',
    'version' => '2006-03-01'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'my-bucket-name',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

Beispiel: Instanziieren eines Clients mit globaler Konfiguration

Aus Version 2 des SDK

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'profile' => 'my_profile',
                'region'  => 'us-east-1'
            )
        ),
        'dynamodb' => array(
            'extends' => 'dynamodb',
            'params' => array(
                'region'  => 'us-west-2'
            )
        ),
    )
);

<?php

require '/path/to/vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory('path/to/my/config.php');

$sqs = $aws->get('sqs');
// Note: SQS client will be configured for us-east-1.

$dynamodb = $aws->get('dynamodb');
// Note: DynamoDB client will be configured for us-west-2.

Aus Version 3 des SDK

Wichtigste Unterschiede:

<?php

require '/path/to/vendor/autoload.php';

$sdk = new Aws\Sdk([
    'profile' => 'my_profile',
    'region' => 'us-east-1',
    'version' => 'latest',
    'DynamoDb' => [
        'region' => 'us-west-2',
    ],
]);

$sqs = $sdk->createSqs();
// Note: Amazon SQS client will be configured for us-east-1.

$dynamodb = $sdk->createDynamoDb();
// Note: DynamoDB client will be configured for us-west-2.