Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Modèles d'utilisation de base de la AWS SDK for PHP version 3

Cette rubrique se concentre sur les modèles d'utilisation de base du kit AWS SDK for PHP.

Prérequis

Inclure le SDK dans votre code

Quelle que soit la technique que vous avez utilisée pour installer leSDK, vous pouvez l'inclure SDK dans votre code avec une seule require instruction. Consultez le tableau suivant pour connaître le PHP code le mieux adapté à votre technique d'installation. Remplacez toutes les occurrences de /path/to/ par le chemin d'accès sur votre système.

Dans cette rubrique, nous partons de la méthode d'installation de Composer. Si vous utilisez une autre méthode d'installation, vous pouvez revenir à cette section pour trouver le code require approprié à utiliser.

Résumé de l'utilisation

Pour utiliser le SDK pour interagir avec un AWS service, instanciez un objet client. Les objets clients ont des méthodes qui correspondent aux opérations du serviceAPI. Pour exécuter une opération spécifique, appelez sa méthode correspondante. Cette méthode renvoie un objet Result de type tableau en cas de réussite ou lève une Exception en cas d’échec.

Création d'un client

Vous pouvez créer un client en transmettant un tableau associatif d'options au constructeur d'un client.

Importations

require 'vendor/autoload.php';

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

Exemple de 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'.

Les informations relatives au paramètre optionnel « version » sont disponibles dans la rubrique des options de configuration.

Notez que nous n’avons pas explicitement fourni d’informations d’identification au client. En effet, ils SDK doivent détecter les informations d'identification provenant des variables d'environnement, des informations d'identification présentes Partage config et credentials fichiers dans votre HOME répertoire AWS Identity and Access Management (IAM), des informations d'identification du profil d'instance ou des fournisseurs d'informations d'identification.

Toutes les options générales de configuration du client sont décrites en détail dansConfiguration pour la AWS SDK for PHP version 3. Les options fournies peuvent varier selon le type de client que vous créez. Ces options de configuration client personnalisées sont décrites dans la APIdocumentation de chaque client.

Utilisation de la Sdk classe

La classe Aws\Sdk fonctionne comme une fabrique de clients. Elle permet de gérer des options de configuration partagées sur plusieurs clients. La plupart des options qui peuvent être fournies à un constructeur client spécifique peuvent également être fournies à la Aws\Sdk classe. Ces options sont ensuite appliquées à chaque constructeur client.

Importations

require 'vendor/autoload.php';

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

Exemple de 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();

Les options partagées entre tous les clients sont placées dans des paires clé-valeur au niveau racine. Les données de configuration spécifiques au service peuvent être fournies dans une clé identique à l'espace de noms d'un service (par exemple, « S3 », « DynamoDb », etc.).

$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();

Les valeurs de configuration spécifiques au service comprennent les valeurs spécifiques au service et les valeurs de niveau racine (les valeurs spécifiques au service sont fusionnées de manière superficielle dans les valeurs de niveau racine).

Exécution des opérations de service

Vous pouvez exécuter une opération de service en appelant la méthode du même nom sur un objet client. Par exemple, pour effectuer l'PutObjectopération Amazon S3, vous devez appeler la Aws\S3\S3Client::putObject() méthode.

Importations

require 'vendor/autoload.php';

use Aws\S3\S3Client;

Exemple de 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'];

Les opérations disponibles pour un client, ainsi que la structure de l'entrée et de la sortie, sont définies au moment de l'exécution en fonction d'un fichier de description du service. Lorsque vous créez un client, vous devez spécifier une version (par exemple, « 2006-03-01 » ou « latest »). Il SDK trouve le fichier de configuration correspondant en fonction de la version fournie.

Toutes les méthodes d'opération telles que putObject() acceptent un seul argument : un tableau associatif qui représente les paramètres de l'opération. La structure de ce tableau (et la structure de l'objet de résultat) est définie pour chaque opération dans SDK la API documentation (par exemple, voir la API documentation pour l'putObjectopération).

HTTPoptions du gestionnaire

Vous pouvez également affiner la façon dont le HTTP gestionnaire sous-jacent exécute la demande à l'aide du paramètre spécial. @http Vous pouvez inclure dans le paramètre @http les mêmes options que celles définies lors de l'instanciation du client à l'aide de l'option client « http ».

// 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'
    ]
]);

Requêtes asynchrones

Vous pouvez envoyer des commandes simultanément à l'aide des fonctionnalités asynchrones du. SDK Vous pouvez envoyer des requêtes de manière asynchrone en ajoutant Async à la fin du nom d'une opération. Cette méthode lance la requête et renvoie une promesse. La promesse est exécutée avec l'objet de résultat en cas de réussite ou rejetée avec une exception en cas d'échec. Cela vous permet de créer plusieurs promesses et de leur faire envoyer des HTTP demandes simultanément lorsque le HTTP gestionnaire sous-jacent transfère les demandes.

Importations

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

Exemple de 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();

Vous pouvez forcer une promesse à exécuter les opérations de manière synchrone à l'aide de la méthode wait de la promesse. L'exécution forcée de la promesse « débloque » l'état de la promesse par défaut : le résultat de la promesse est renvoyé ou l'exception rencontrée est levée. Lors de l'wait()appel d'une promesse, le processus se bloque jusqu'à ce que la HTTP demande soit terminée et que le résultat soit renseigné ou qu'une exception soit émise.

Lorsque vous utilisez la bibliothèque SDK avec une boucle d'événements, ne bloquez pas les résultats. Utilisez plutôt la méthode then() d'un résultat pour accéder à une promesse résolue ou rejetée une fois l'opération terminée.

Importations

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

Exemple de 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();
    });

Utilisation des objets de résultat

L'exécution d'une opération réussie renvoie un objet Aws\Result. Au lieu de renvoyer le brut XML ou JSON les données d'un service, il SDK contraint les données de réponse dans une structure de tableau associatif. Cette approche normalise certains aspects des données en fonction des connaissances du service spécifique et de la structure de réponse sous-jacente.

Vous pouvez accéder aux données de l' AWSResult objet sous la forme d'un PHP tableau associatif.

Importations

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

Exemple de 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();

Le contenu de l'objet de résultat dépend de l'opération qui a été exécutée et de la version du service. La structure des résultats de chaque API opération est documentée dans la API documentation de chaque opération.

SDKIl est intégré JMESPath, DSLutilisé pour rechercher et manipuler JSON des données ou, dans notre cas, des PHP tableaux. L'objet de résultat contient une méthode search() que vous pouvez utiliser pour extraire des données par déclaration du résultat.

Exemple de code

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

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

Gestion des erreurs

Gestion des erreurs synchrones

Si une erreur se produit lors de l'exécution d'une opération, une exception est levée. Aussi, si vous devez gérer des erreurs dans votre code, utilisez des blocs try/catch autour de vos opérations. Le SDK renvoie des exceptions spécifiques au service lorsqu'une erreur se produit.

L'exemple suivant repose sur Aws\S3\S3Client. Si une erreur se produit, l'exception levée sera du type Aws\S3\Exception\S3Exception. Toutes les exceptions spécifiques au service auxquelles les SDK lancements s'étendent proviennent de la Aws\Exception\AwsException classe. Cette classe contient des informations utiles sur l'échec, y compris l'ID de la requête, le code d'erreur et le type d'erreur. Notez que pour certains services qui le prennent en charge, les données de réponse sont regroupées dans une structure de tableau associatif (similaire aux Aws\Result objets), accessible comme un tableau associatif normalPHP. La méthode toArray() renvoie tous ces données, si elles existent.

Importations

require 'vendor/autoload.php';

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

Exemple de 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());
}

Gestion asynchrone des erreurs

Aucune exception n'est levée lors de l'envoi de requêtes asynchrones. Vous devez utiliser la méthode then() ou otherwise() de la promesse renvoyée pour recevoir le résultat ou l'erreur.

Importations

require 'vendor/autoload.php';

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

Exemple de 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);
});

Vous pouvez également « débloquer » la promesse et forcer la levée de l'exception.

Importations

require 'vendor/autoload.php';

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

Exemple de code

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

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