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.

Grundlegende Nutzungsmuster der AWS SDK for PHP Version 3

Dieses Thema konzentriert sich auf grundlegende Nutzungsmuster von AWS SDK for PHP

Voraussetzungen

Das SDK in Ihren Code einbeziehen

Unabhängig davon, mit welcher Technik Sie das SDK installiert haben, können Sie das SDK mit nur einer require-Anweisung in den Code einfügen. In der folgenden Tabelle finden Sie den PHP-Code, der am besten zu Ihrer Installationstechnik passt. Ersetzen Sie alle Instances von /path/to/ durch den tatsächlichen Pfad auf Ihrem System.

In diesem Thema gehen wir von der Composer-Installationsmethode aus. Wenn Sie eine andere Installationsmethode verwenden, können Sie in diesem Abschnitt nach dem richtigen require-Code suchen.

Zusammenfassung der Nutzung

Um das SDK für die Interaktion mit einem AWS Dienst zu verwenden, instanziieren Sie ein Client-Objekt. Client-Objekte verfügen über Methoden, die den Vorgängen in der API des Dienstes entsprechen. Um eine bestimmte Operation auszuführen, rufen Sie die entsprechende Methode auf. Diese Methode gibt bei Erfolg entweder ein arrayähnliches Result-Objekt oder bei einem Fehler eine Exceptionzurück.

Erstellen eines Clients

Sie können einen Client erstellen, indem Sie dem Konstruktor eines Clients ein assoziatives Array von Optionen übergeben.

Importe

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Beispiel-Code

//Create an S3Client
$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-2'  // Since version 3.277.10 of the SDK,
]);                          // the 'version' parameter defaults to 'latest'.

Informationen zum optionalen Parameter „Version“ finden Sie im Thema Konfigurationsoptionen.

Beachten Sie, dass wir nicht explizit Anmeldeinformationen für den Client angegeben haben. Das liegt daran, dass das SDK die Anmeldeinformationen anhand von Umgebungsvariablen, den Anmeldeinformationen Freigegebene - config und -credentialsDateien in Ihrem HOME-Verzeichnis, den Anmeldeinformationen für das Instanzprofil AWS Identity and Access Management (IAM) oder den Anmeldeinformationsanbietern ermitteln sollte.

Alle allgemeinen Client-Konfigurationsoptionen werden unter ausführlich beschrieben. Konfiguration für AWS SDK for PHP Version 3 Die Anzahl der Optionen, die einem Client zur Verfügung gestellt werden, kann je nach Client, den Sie erstellen, variieren. Diese benutzerdefinierten Clientkonfigurationsoptionen sind in der API-Dokumentation für jeden Client beschrieben.

Verwendung der Sdk Klasse

Die Klasse Aws\Sdk fungiert als Client-Factory und wird verwendet, um gemeinsame Konfigurationsoptionen für mehrere Clients zu verwalten. Viele der Optionen, die einem bestimmten Client-Konstruktor zur Verfügung gestellt werden können, können auch der Aws\Sdk Klasse zur Verfügung gestellt werden. Diese Optionen werden dann auf jeden Client-Konstruktor angewendet.

Importe

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Beispiel-Code

// The same options that can be provided to a specific client constructor can also be supplied to the Aws\Sdk class.
// Use the us-west-2 region and latest version of each client.
$sharedConfig = [
    'region' => 'us-west-2'
];
// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);
// Create an Amazon S3 client using the shared configuration data.
$client = $sdk->createS3();

Optionen, die für alle Clients freigegeben sind, werden in Schlüssel/Wert-Paaren auf Stammebene platziert. Dienstspezifische Konfigurationsdaten können in einem Schlüssel bereitgestellt werden, der dem Namespace eines Dienstes entspricht (z. B. „S3“, „DynamoDb“ usw.).

$sdk = new Aws\Sdk([
    'region'   => 'us-west-2',
    'DynamoDb' => [
        'region' => 'eu-central-1'
    ]
]);

// Creating an Amazon DynamoDb client will use the "eu-central-1" AWS Region
$client = $sdk->createDynamoDb();

Servicespezifische Konfigurationswerte sind eine Vereinigung der servicespezifischen Werte und der Werte auf Stammebene (d. h. servicespezifische Werte werden flach auf Werte auf Stammebene zusammengeführt).

Ausführung von Serviceoperationen

Sie können eine Serviceoperation ausführen, indem Sie die Methode mit demselben Namen für ein Clientobjekt aufrufen. Um beispielsweise den Amazon S3 PutObjectS3-Vorgang auszuführen, müssen Sie die Aws\S3\S3Client::putObject() Methode aufrufen.

Importe

require 'vendor/autoload.php';

use Aws\S3\S3Client;

Beispiel-Code

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2'
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

// Send a PutObject request and get the result object.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key',
    'Body' => 'this is the body!'
]);

// Download the contents of the object.
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key'
]);

// Print the body of the result by indexing into the result object.
echo $result['Body'];

Operationen, die für einen Client verfügbar sind, und die Struktur der Eingabe und Ausgabe werden zur Laufzeit basierend auf einer Servicebeschreibungsdatei definiert. Wenn Sie einen Client erstellen, müssen Sie eine Version angeben (z. B. „2006-03-01“ oder „letzte“). Das SDK findet die entsprechende Konfigurationsdatei basierend auf der bereitgestellten Version.

Operationsmethoden wie putObject() akzeptieren alle ein einzelnes Argument, ein assoziatives Array, das die Parameter der Operation darstellt. Die Struktur dieses Arrays (und die Struktur des Ergebnisobjekts) wird für jede Operation in der API-Dokumentation des SDK definiert (siehe z. B. die API-Dokumentation für die putObject-Operation).

HTTP-Handler-Optionen

Sie können auch genau festlegen, wie der zugrunde liegende HTTP-Handler die Anforderung ausführt, indem Sie den speziellen Parameter @http verwenden. Die Optionen, die Sie in den Parameter @httpaufnehmen können, entsprechen denen, die Sie beim Initialisieren des Clients mit der Client-Option „http“ festlegen können.

// Send the request through a proxy
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

Asynchrone Anfragen

Sie können Befehle gleichzeitig mit den asynchronen Funktionen des SDKs senden. Sie können Anfragen asynchron senden, indem Sie einen Operationsnamen mit Async suffizieren. Dies initiiert die Anfrage und gibt ein Promise zurück. Das Promise wird mit dem Ergebnisobjekt bei Erfolg erfüllt oder mit einer Ausnahme bei einem Fehler abgelehnt. Auf diese Weise können Sie mehrere Promises erstellen und veranlassen, dass HTTP-Anforderungen gleichzeitig gesendet werden, wenn der zugrunde liegende HTTP-Handler die Anforderungen überträgt.

Importe

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Beispiel-Code

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();
//Listing all S3 Bucket
$CompleteSynchronously = $s3Client->listBucketsAsync();
// Block until the result is ready.
$CompleteSynchronously = $CompleteSynchronously->wait();

Sie können die Versprechung eines Promises erzwingen, indem Sie die Methode wait des Promises synchron ausführen. Das Erzwingen des Promises zum Vervollständigen „packt“ auch standardmäßig den Status des Promises „aus“, was bedeutet, dass es entweder das Ergebnis des Promises zurückgibt oder die aufgetretene Ausnahme auslöst. Beim Aufruf von wait() bei einem Promise blockiert der Prozess, bis die HTTP-Anfrage abgeschlossen ist und das Ergebnis gefüllt ist oder eine Ausnahme ausgelöst wird.

Wenn Sie das SDK mit einer Ereignisschleifenbibliothek verwenden, blockieren Sie keine Ergebnisse. Verwenden Sie stattdessen die Methode then() eines Ergebnisses, um auf eine Zusage zuzugreifen, die nach Abschluss der Operation aufgelöst oder zurückgewiesen wird.

Importe

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Beispiel-Code

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

$promise = $s3Client->listBucketsAsync();
$promise
    ->then(function ($result) {
        echo 'Got a result: ' . var_export($result, true);
    })
    ->otherwise(function ($reason) {
        echo 'Encountered an error: ' . $reason->getMessage();
    });

Mit Ergebnisobjekten arbeiten

Ausführen einer erfolgreichen Operation gibt ein Aws\Result Objekt zurück. Anstatt die XML- oder JSON-Rohdaten eines Service zurückzugeben, konvertiert das SDK die Antwortdaten in eine assoziative Array-Struktur. Es normalisiert einige Aspekte der Daten auf der Grundlage seiner Kenntnisse des spezifischen Services und der zugrunde liegenden Antwortstruktur.

Sie können auf Daten aus dem AWSResult Objekt wie auf ein assoziatives PHP-Array zugreifen.

Importe

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

Beispiel-Code

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2',
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3 = $sdk->createS3();
$result = $s3->listBuckets();
foreach ($result['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}

// Convert the result object to a PHP array
$array = $result->toArray();

Der Inhalt des Ergebnisobjekts hängt von der ausgeführten Operation und der Version eines Service ab. Die Ergebnisstruktur jeder API-Operation ist in den API-Dokumenten für jede Operation dokumentiert.

Das SDK ist mit JMESPath, einem DSL integriert, mit dem JSON-Daten oder in unserem Fall PHP-Arrays gesucht und manipuliert werden können. Das Ergebnisobjekt enthält eine search()-Methode, mit der Sie deklarativer Daten aus dem Ergebnis extrahieren können.

Beispiel-Code

$s3 = $sdk->createS3();
$result = $s3->listBuckets();

$names = $result->search('Buckets[].Name');

Fehlerbehandlung

Synchrone Fehlerbehandlung

Wenn beim Ausführen einer Operation ein Fehler auftritt, wird eine Ausnahme ausgelöst. Aus diesem Grund verwenden Sie zur Behandlung von Fehlern in Ihrem Code try/catch-Blöcke um Ihre Operationen herum. Das SDK löst servicespezifische Ausnahmen aus, wenn ein Fehler auftritt.

Das folgende Beispiel verwendet die Aws\S3\S3Client. Wenn ein Fehler vorliegt, wird die ausgelöste Ausnahme vom Typ Aws\S3\Exception\S3Exception sein. Alle servicespezifischen Ausnahmen, die das SDK auslöst, erstrecken sich von der Klasse Aws\Exception\AwsException. Diese Klasse enthält nützliche Informationen zum Fehler einschließlich der Anforderungs-ID, des Fehlercodes und des Fehlertyps. Für einige Services, die diese Klasse unterstützen, werden Antwortdaten in eine assoziative Array-Struktur (ähnelt Aws\Result-Objekten) umgewandelt, auf die wie auf normale assoziative PHP-Arrays zugegriffen werden kann. Die Methode toArray() gibt Daten dieser Art zurück (sofern vorhanden).

Importe

require 'vendor/autoload.php';

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

Beispiel-Code

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

try {
    $s3Client->createBucket(['Bucket' => 'my-bucket']);
} catch (S3Exception $e) {
    // Catch an S3 specific exception.
    echo $e->getMessage();
} catch (AwsException $e) {
    // This catches the more generic AwsException. You can grab information
    // from the exception using methods of the exception object.
    echo $e->getAwsRequestId() . "\n";
    echo $e->getAwsErrorType() . "\n";
    echo $e->getAwsErrorCode() . "\n";

    // This dumps any modeled response data, if supported by the service
    // Specific members can be accessed directly (e.g. $e['MemberName'])
    var_dump($e->toArray());
}

Asynchrone Fehlerbehandlung

Ausnahmen werden nicht ausgelöst, wenn das Senden von asynchronen Anforderungen. Stattdessen müssen Sie die Methode then() oder otherwise() des zurückgegebenen Promise verwenden, um das Ergebnis oder den Fehler zu erhalten.

Importe

require 'vendor/autoload.php';

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

Beispiel-Code

//Asynchronous Error Handling
$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);
$promise->otherwise(function ($reason) {
    var_dump($reason);
});

// This does the same thing as the "otherwise" function.
$promise->then(null, function ($reason) {
    var_dump($reason);
});

Sie können das Promise „auspacken“ und stattdessen die Ausnahme auslösen.

Importe

require 'vendor/autoload.php';

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

Beispiel-Code

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

//throw exception
try {
    $result = $promise->wait();
} catch (S3Exception $e) {
    echo $e->getMessage();
}