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.
# AWS-Service Anfragen mit der AWS SDK für PHP Version 3 stellen
## Überblick über den Workflow für SDK-Anfragen
Die Arbeit mit AWS SDK für PHP Version 3 folgt in allen Bereichen einem einheitlichen Muster AWS-Services. Der grundlegende Arbeitsablauf umfasst drei Hauptschritte:
1. [**Einen Service-Client erstellen**](#creating-a-client) — Instanziieren Sie ein **Client-Objekt für den Client**, den AWS-Service Sie verwenden möchten.
1. [**Operationen ausführen**](#executing-service-operations) — Rufen Sie Methoden auf dem Client auf, die Operationen in der API des Dienstes entsprechen.
1. [**Ergebnisse verarbeiten**](#result-objects) **— Arbeiten Sie mit dem Array-ähnlichen **Ergebnisobjekt**, das bei Erfolg zurückgegeben wird, oder behandeln Sie jede Ausnahme, die bei einem Fehler ausgelöst wird.**
In den folgenden Abschnitten wird jeder dieser Schritte detailliert beschrieben, beginnend mit der Erstellung und Konfiguration von Service-Clients.
## Einen Basis-Serviceclient erstellen
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](guide_configuration.md#cfg-version).
Beachten Sie, dass wir **nicht** explizit Anmeldeinformationen für den Client angegeben haben. Das liegt daran, dass das SDK die [standardmäßige Anbieterkette für Anmeldeinformationen](guide_credentials_default_chain.md) verwendet, um nach Anmeldeinformationen zu suchen.
Alle allgemeinen Client-Konfigurationsoptionen werden unter ausführlich beschrieben. [Client-Konstruktor-Optionen für die AWS SDK für PHP Version 3](guide_configuration.md) 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](https://docs.aws.amazon.com/aws-sdk-php/latest/) für jeden Client beschrieben.
Das obige Beispiel zeigt zwar die grundlegende Client-Erstellung, Sie können Ihre Service-Clients jedoch an spezifische Anforderungen anpassen. Ausführlichere Informationen zur Konfiguration von Service-Clients mithilfe von Code finden Sie unter[Konfiguration von Service-Clients im Code für die AWS SDK für PHP Version 3](configuring-service-clients-code.md). Informationen zur Konfiguration von Service-Clients mithilfe externer Konfigurationsdateien oder Umgebungsvariablen finden Sie unter[Service-Clients für die AWS SDK für PHP Version 3 extern konfigurieren](configuring-service-clients-ext.md).
## Senden von Anforderungen
Sie können Serviceanfragen stellen, indem Sie die gleichnamige Methode für ein Client-Objekt aufrufen. Um beispielsweise den Amazon S3 [PutObjectS3-Vorgang](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html) auszuführen, rufen Sie die `Aws\S3\S3Client::putObject()` Methode auf.
**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' => 'amzn-s3-demo-bucket',
'Key' => 'my-key',
'Body' => 'this is the body!'
]);
// Download the contents of the object.
$result = $s3Client->getObject([
'Bucket' => 'amzn-s3-demo-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 beim Erstellen eines Clients keinen `version` Parameter (z. B. *„2006-03-01“ oder *„latest“**) des Servicemodells angeben, verwendet der Client standardmäßig die neueste Version. 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](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)).
### Optionen für den HTTP-Handler
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 `@http`aufnehmen können, entsprechen denen, die Sie beim Initialisieren des Clients mit der Client-Option [„http“](guide_configuration.md#config-http) festlegen können.
```
// Send the request through a proxy
$result = $s3Client->putObject([
'Bucket' => 'amzn-s3-demo-bucket',
'Key' => 'my-key',
'Body' => 'this is the body!',
'@http' => [
'proxy' => 'http://192.168.16.1:10'
]
]);
```
## 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 `AWS\Result` 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 in eine [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) integriert [JMESPath](http://jmespath.org/), die zum Suchen und Bearbeiten von JSON-Daten oder in unserem Fall in PHP-Arrays verwendet wird. 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');
```
# Befehlsobjekte in der AWS SDK für PHP Version 3
Die AWS SDK für PHP verwendet das [Befehlsmuster](http://en.wikipedia.org/wiki/Command_pattern), um die Parameter und den Handler zu kapseln, die zu einem späteren Zeitpunkt für die Übertragung einer HTTP-Anfrage verwendet werden.
## Implizite Verwendung von Befehlen
Wenn Sie eine Clientklasse untersuchen, können Sie sehen, dass die den API-Operationen entsprechenden Methoden tatsächlich nicht vorhanden sind. Sie werden mit der magischen Methode `__call()` umgesetzt. Diese Pseudo-Methoden sind eigentlich Verknüpfungen, die die Verwendung von Befehlsobjekten durch das SDK einkapseln.
In der Regel müssen Sie nicht direkt mit Befehlsobjekten interagieren. Wenn Sie Methoden wie `Aws\S3\S3Client::putObject()` aufrufen, erstellt das SDK basierend auf den angegebenen Parametern ein Objekt `Aws\CommandInterface`, führt den Befehl aus und gibt ein ausgefülltes Objekt `Aws\ResultInterface` zurück (oder löst eine Ausnahme aus, wenn ein Fehler auftritt). Ein ähnlicher Ablauf tritt auf, wenn eine der `Async`-Methoden eines Clients (z. B. `Aws\S3\S3Client::putObjectAsync()`) aufgerufen wird: Der Client erstellt einen Befehl basierend auf den bereitgestellten Parametern, serialisiert eine HTTP-Anforderung, initiiert die Anforderung und gibt ein Promise zurück.
Die folgenden Beispiele sind funktional äquivalent.
```
$s3Client = new Aws\S3\S3Client([
'version' => '2006-03-01',
'region' => 'us-standard'
]);
$params = [
'Bucket' => 'amzn-s3-demo-bucket',
'Key' => 'baz',
'Body' => 'bar'
];
// Using operation methods creates a command implicitly
$result = $s3Client->putObject($params);
// Using commands explicitly
$command = $s3Client->getCommand('PutObject', $params);
$result = $s3Client->execute($command);
```
## Befehlsparameter
Alle Befehle unterstützen einige spezielle Parameter, die nicht Teil der API eines Services sind, sondern das Verhalten des SDK steuern.
### `@http`
Mit diesem Parameter können Sie genau festlegen, wie der zugrunde liegende HTTP-Handler die Anfrage ausführt. Die Optionen, die Sie in den Parameter `@http`aufnehmen können, entsprechen denen, die Sie beim Initialisieren des Clients mit der Client-Option [„http“](guide_configuration.md#config-http) festlegen können.
```
// Configures the command to be delayed by 500 milliseconds
$command['@http'] = [
'delay' => 500,
];
```
### `@retries`
Wie auch die Client-Option [„Wiederholungen“](guide_configuration.md#config-retries) steuert `@retries`, wie oft ein Befehl wiederholt werden kann, bevor er als fehlgeschlagen gilt. Setzen Sie es auf `0`, um die Versuche zu deaktivieren.
```
// Disable retries
$command['@retries'] = 0;
```
**Anmerkung**
Wenn Sie Neuversuche auf einem Client deaktiviert haben, können Sie sie nicht selektiv für einzelne Befehle aktivieren, die an diesen Client übergeben werden.
## Befehlsobjekte erstellen
Sie können einen Befehl mit der `getCommand()`-Methode eines Clients erstellen. Diese führt nicht sofort eine HTTP-Anfrage aus oder überträgt sie, sondern sie wird nur ausgeführt, wenn sie an die `execute()`-Methode des Clients übergeben wird. Dies gibt Ihnen die Möglichkeit, das Befehlsobjekt vor der Ausführung des Befehls zu ändern.
```
$command = $s3Client->getCommand('ListObjects');
$command['MaxKeys'] = 50;
$command['Prefix'] = 'foo/baz/';
$result = $s3Client->execute($command);
// You can also modify parameters
$command = $s3Client->getCommand('ListObjects', [
'MaxKeys' => 50,
'Prefix' => 'foo/baz/',
]);
$command['MaxKeys'] = 100;
$result = $s3Client->execute($command);
```
## Befehl `HandlerList`
Wenn ein Befehl von einem Client erstellt wird, erhält er einen Klon des `Aws\HandlerList`-Objekts des Clients. Der Befehl erhält einen **Klon** der Handlerliste des Clients, damit ein Befehl benutzerdefinierte Middleware und Handler verwenden kann, die andere vom Client ausgeführte Befehle nicht beeinflussen.
Dies bedeutet, dass Sie einen anderen HTTP-Client pro Befehl (z. B. `Aws\MockHandler`) verwenden und benutzerdefiniertes Verhalten pro Befehl über Middleware hinzufügen können. Im folgenden Beispiel wird eine `MockHandler` verwendet, um Scheinergebnisse anstelle von tatsächlichen HTTP-Anforderungen zu erstellen.
```
use Aws\Result;
use Aws\MockHandler;
// Create a mock handler
$mock = new MockHandler();
// Enqueue a mock result to the handler
$mock->append(new Result(['foo' => 'bar']));
// Create a "ListObjects" command
$command = $s3Client->getCommand('ListObjects');
// Associate the mock handler with the command
$command->getHandlerList()->setHandler($mock);
// Executing the command will use the mock handler, which returns the
// mocked result object
$result = $client->execute($command);
echo $result['foo']; // Outputs 'bar'
```
Zusätzlich zum Ändern des vom Befehl verwendeten Handlers können Sie dem Befehl auch benutzerdefinierte Middleware hinzufügen. Das folgende Beispiel verwendet die Middleware `tap`, die als Beobachter in der Handlerliste fungiert.
```
use Aws\CommandInterface;
use Aws\Middleware;
use Psr\Http\Message\RequestInterface;
$command = $s3Client->getCommand('ListObjects');
$list = $command->getHandlerList();
// Create a middleware that just dumps the command and request that is
// about to be sent
$middleware = Middleware::tap(
function (CommandInterface $command, RequestInterface $request) {
var_dump($command->toArray());
var_dump($request);
}
);
// Append the middleware to the "sign" step of the handler list. The sign
// step is the last step before transferring an HTTP request.
$list->append('sign', $middleware);
// Now transfer the command and see the var_dump data
$s3Client->execute($command);
```
## `CommandPool`
Mit der `Aws\CommandPool` können Sie Befehle gleichzeitig mit einem Iterator ausführen, der `Aws\CommandInterface`-Objekte liefert. Die `CommandPool` stellt sicher, dass eine konstante Anzahl von Befehlen gleichzeitig ausgeführt wird, während über die Befehle im Pool iteriert wird (wenn Befehle abgeschlossen sind, werden mehr ausgeführt, um eine konstante Poolgröße sicherzustellen).
Hier ist ein sehr einfaches Beispiel, um nur einige Befehle mit einer `CommandPool` zu senden.
```
use Aws\S3\S3Client;
use Aws\CommandPool;
// Create the client
$client = new S3Client([
'region' => 'us-standard',
'version' => '2006-03-01'
]);
$bucket = 'amzn-s3-demo-bucket';
$commands = [
$client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'a']),
$client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'b']),
$client->getCommand('HeadObject', ['Bucket' => $bucket, 'Key' => 'c'])
];
$pool = new CommandPool($client, $commands);
// Initiate the pool transfers
$promise = $pool->promise();
// Force the pool to complete synchronously
$promise->wait();
```
Dieses Beispiel ist für die `CommandPool` ziemlich unterentwickelt. Versuchen wir es mit einem komplexeren Beispiel. Nehmen wir an, Sie möchten Dateien auf der Festplatte in einen Amazon S3 S3-Bucket hochladen. Um eine Liste der Dateien von der Festplatte zu erhalten, können wir `DirectoryIterator` von PHP verwenden. Dieser Iterator liefert `SplFileInfo` Objekte. Der `CommandPool` akzeptiert einen Iterator, der `Aws\CommandInterface`-Objekte liefert, also bilden wir die `SplFileInfo`-Objekte ab, um `Aws\CommandInterface`-Objekte zurückzugeben.
```
'us-standard',
'version' => '2006-03-01'
]);
$fromDir = '/path/to/dir';
$toBucket = 'amzn-s3-demo-bucket';
// Create an iterator that yields files from a directory
$files = new DirectoryIterator($fromDir);
// Create a generator that converts the SplFileInfo objects into
// Aws\CommandInterface objects. This generator accepts the iterator that
// yields files and the name of the bucket to upload the files to.
$commandGenerator = function (\Iterator $files, $bucket) use ($client) {
foreach ($files as $file) {
// Skip "." and ".." files
if ($file->isDot()) {
continue;
}
$filename = $file->getPath() . '/' . $file->getFilename();
// Yield a command that is executed by the pool
yield $client->getCommand('PutObject', [
'Bucket' => $bucket,
'Key' => $file->getBaseName(),
'Body' => fopen($filename, 'r')
]);
}
};
// Now create the generator using the files iterator
$commands = $commandGenerator($files, $toBucket);
// Create a pool and provide an optional array of configuration
$pool = new CommandPool($client, $commands, [
// Only send 5 files at a time (this is set to 25 by default)
'concurrency' => 5,
// Invoke this function before executing each command
'before' => function (CommandInterface $cmd, $iterKey) {
echo "About to send {$iterKey}: "
. print_r($cmd->toArray(), true) . "\n";
},
// Invoke this function for each successful transfer
'fulfilled' => function (
ResultInterface $result,
$iterKey,
PromiseInterface $aggregatePromise
) {
echo "Completed {$iterKey}: {$result}\n";
},
// Invoke this function for each failed transfer
'rejected' => function (
AwsException $reason,
$iterKey,
PromiseInterface $aggregatePromise
) {
echo "Failed {$iterKey}: {$reason}\n";
},
]);
// Initiate the pool transfers
$promise = $pool->promise();
// Force the pool to complete synchronously
$promise->wait();
// Or you can chain the calls off of the pool
$promise->then(function() { echo "Done\n"; });
```
### `CommandPool`-Konfiguration
Der `Aws\CommandPool` Konstruktor akzeptiert verschiedene Konfigurationsoptionen.
**Nebenläufigkeit (aufrufbar\$1int)**
Maximale Anzahl von Befehlen, die gleichzeitig ausgeführt werden. Stellen Sie eine Funktion bereit, um den Pool dynamisch zu skalieren. Der Funktion wird die aktuelle Anzahl der ausstehenden Anforderungen bereitgestellt, und es wird erwartet, dass sie eine Ganzzahl zurückgibt, die die neue Größe des Pools darstellt.
**vor der Aktualisierung (abrufbar)**
Funktion, die vor dem Senden jedes Befehls aufgerufen wird. Die `before` Funktion akzeptiert den Befehl und den Schlüssel des Iterators des Befehls. Sie können den Befehl nach Bedarf in der Funktion `before` mutieren, bevor Sie den Befehl senden.
**erfüllt (aufrufbar)**
Funktion, die aufgerufen wird, wenn ein Promise erfüllt ist. Die Funktion enthält das Ergebnisobjekt, die ID des Iterators, von dem das Ergebnis stammt, und das zusammengefasste Promise, das aufgelöst oder zurückgewiesen werden kann, wenn der Pool kurzgeschlossen werden muss.
**abgelehnt (Callable)**
Funktion, die aufgerufen wird, wenn ein Promise abgelehnt wird. Der Funktion wird ein `Aws\Exception`Objekt zur Verfügung gestellt, die ID des Iterators, von der die Ausnahme kam, und das zusammengefasste Promise, das aufgelöst oder zurückgewiesen werden kann, wenn der Pool kurzgeschlossen werden muss.
### Manuelle Speicherbereinigung zwischen Befehlen
Wenn Sie bei großen Befehlspools das Speicherlimit ausreizen, ist die unter Umstände auf zyklische Referenzen zurückzuführen, die vom SDK konfiguriert wurden und noch nicht von der [PHP-Speicherbereinigung](https://www.php.net/manual/en/features.gc.php) gelöscht wurden, als das Speicherlimit erreicht wurde. Manuelles Aufrufen des Bereinigungsalgorithmus zwischen Befehlen ermöglicht unter Umständen die Löschung der Zyklen, bevor das Limit erreicht wird. Das folgende Beispiel erstellt einen `CommandPool`, der den Bereinigungsalgorithmus mithilfe eines Callbacks aufruft, bevor er die einzelnen Befehle versendet. Beachten Sie, dass das Aufrufen der Speicherbereinigung zulasten der Leistung geht und die optimale Nutzung von Ihrem Anwendungsfall und Ihrer Umgebung abhängt.
```
$pool = new CommandPool($client, $commands, [
'concurrency' => 25,
'before' => function (CommandInterface $cmd, $iterKey) {
gc_collect_cycles();
}
]);
```