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 méthode que vous avez utilisée pour installer le kit SDK, vous pouvez inclure ce dernier dans votre code à l'aide d'une seule déclaration require. Consultez le tableau suivant pour savoir quel code PHP convient le mieux à votre installation technique. 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 afin d'interagir avec un AWS service, instanciez un objet client. Les objets clients ont des méthodes qui correspondent aux opérations de l'API du service. 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, le SDK doit détecter les informations d'identification provenant des variables d'environnement, des informations d'identification de votre répertoire HOME, des informations d'identification du Partage config et credentials fichiers profil d'instance AWS Identity and Access Management (IAM) 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 documentation sur l’API 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 »). Le kit SDK détecte 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 la documentation sur l'API du SDK (par exemple, consultez les documents sur l'API pour de plus amples informations sur l'opération putObject).

Options du gestionnaire HTTP

Vous pouvez également ajuster la manière dont le gestionnaire HTTP sous-jacent exécute la requête à 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' => 'my-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 fonctions asynchrones du kit 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 requêtes HTTP simultanément lorsque le gestionnaire HTTP sous-jacent transfère les requêtes.

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. Lorsque vous appelez wait() sur une promesse, le processus se bloque jusqu'à ce que la requête HTTP soit terminée et que le résultat soit renseigné ou qu'une exception soit levée.

Lorsque vous utilisez le kit SDK avec une bibliothèque de boucles 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. Plutôt que de renvoyer des données brutes XML ou JSON d'un service, le kit SDK renseigne 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 tableau PHP 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 du résultat de chaque opération d'API est détaillée dans la documentation sur l'API.

Le kit SDK comprend JMESPath, un langage spécifique au domaine utilisé pour examiner et manipuler des données JSON ou, dans notre cas, des tableaux PHP. 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 kit SDK lève des exceptions spécifiques au service en cas d'erreur.

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 levées par le kit SDK sont dérivées de la classe Aws\Exception\AwsException. 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 prennent cela en charge, les données de réponse sont converties dans une structure de tableau associatif (similaire à des objets Aws\Result), à laquelle il est possible d’accéder comme à un tableau associatif PHP normal. 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();
}