Modelli di utilizzo di base dell'AWS SDK for PHPversione 3 - AWS SDK for PHP

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Modelli di utilizzo di base dell'AWS SDK for PHPversione 3

Questo argomento descrive i modelli di utilizzo di base dell'AWS SDK for PHP.

Prerequisiti

Includere l'SDK nel proprio codice

Qualsiasi tecnica abbia utilizzato per installare l'SDK, è possibile includere l'SDK nel tuo codice con una sola istruzione require. Consulta la tabella riportata di seguito per individuare il codice PHP che meglio si adatta alle esigenze della tecnica di installazione. Sostituisci tutte le istanze di /path/to/ con il percorso effettivo sul sistema.

Tecnica di installazione Richiedere istruzione

Utilizzo di Composer

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

Utilizzo del file phar

require '/path/to/aws.phar';

Utilizzo di ZIP

require '/path/to/aws-autoloader.php';

In questo argomento, riportiamo degli esempi che presuppongono il metodo di installazione Composer. Se usi un metodo di installazione diverso, è possibile fare riferimento a questa sezione per trovare il codice require corretto da utilizzare.

Riepilogo di utilizzo

Per utilizzare l'SDK per l'interazione con unaAWSservizio, creazione di un'istanzaClientoggetto. Gli oggetti client dispongono di metodi che corrispondono uno a uno con le operazioni nell'API del servizio. Per eseguire una determinata operazione, è necessario scegliere il metodo corrispondente. Questo metodo restituisce un oggetto risultato del tipo array in caso di esito positivo oppure genera un'eccezione in caso di errore.

Creazione di un client

È possibile creare un client trasferendo un array associativo di opzioni a un costruttore di client.

Importazioni

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

Codice di esempio

//Create an S3Client $s3 = new Aws\S3\S3Client([ 'version' => 'latest', 'region' => 'us-east-2' ]);

Si noti che non abbiamo esplicitamente fornito le credenziali al client. Questo perché l'SDK dovrebbe rilevare le credenziali davariabili di ambiente(tramiteAWS_ACCESS_KEY_IDeAWS_SECRET_ACCESS_KEY), unAWSfile delle credenziali INInella tua directory HOME,AWS Identity and Access Management(IAM)credenziali profilo dell'istanza, oppurefornitori di credenziali.

Tutte le opzioni di configurazione generale del client sono descritte dettagliatamente nella guida alla configurazione. La gamma di opzioni fornite a un client può variare in base a quale client si sta creando. Queste opzioni personalizzate per la configurazione del client sono descritte nella documentazione API per ogni client.

Utilizzo della classe Sdk

La classe Aws\Sdk agisce come un client factory e viene utilizzata per gestire le opzioni di configurazione condivise da più client. Le stesse opzioni che possono essere fornite a un determinato costruttore di client possono essere fornite anche alla classe Aws\Sdk. Queste opzioni vengono poi applicate a ciascun costruttore di client.

Importazioni

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

Codice di esempio

// 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', 'version' => 'latest' ]; // 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();

Le opzioni che sono condivise per tutti i client sono collocate in coppie chiave-valore a livello radice. I dati di configurazione specifici per il servizio possono essere forniti in una chiave che è la stessa dello spazio dei nomi del servizio (ad esempio, "S3", "DynamoDb" ecc.).

$sdk = new Aws\Sdk([ 'region' => 'us-west-2', 'version' => 'latest', 'DynamoDb' => [ 'region' => 'eu-central-1' ] ]); // Creating an Amazon DynamoDb client will use the "eu-central-1" AWS Region $client = $sdk->createDynamoDb();

I valori di configurazione specifici del servizio sono una combinazione di valori specifici del servizio e di valori a livello radice (ad esempio, i valori specifici del servizio sono clonati in valori di livello radice).

Nota

È consigliabile utilizzare la classe Sdk per creare client se nell'applicazione si utilizzano più istanze client. La classe Sdk utilizza automaticamente lo stesso client HTTP per ogni client SDK, consentendo a client SDK per servizi diversi di eseguire richieste HTTP senza blocchi. Se i client SDK non utilizzano lo stesso client HTTP, le richieste HTTP inviate dal client SDK potrebbero bloccare l'orchestrazione della promessa tra i servizi.

Esecuzione delle operazioni di servizio

È possibile eseguire un'operazione di servizio chiamando il metodo con lo stesso nome di un oggetto client. Ad esempio, per eseguire Amazon S3Operazione PutObjectè necessario chiamare ilAws\S3\S3Client::putObject()metodo.

Importazioni

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

Codice di esempio

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

Le operazioni disponibili per un client e la struttura di input e output sono definite in fase di runtime in base a un file di descrizione del servizio. Durante la creazione di un client, è necessario fornire una versione (ad esempio, "2006-03-01" o "più recente"). L'SDK individua il file di configurazione corrispondente in base alla versione fornita.

Tutti i metodi di operazione come putObject() accettano un unico argomento, un array associativo che indica i parametri dell'operazione. La struttura di questo array (e la struttura dell'oggetto risultato) è definita per ciascuna operazione nella documentazione API SDK (ad esempio, consulta la documentazione API per l'operazione putObject).

Opzioni gestore HTTP

È inoltre possibile ottimizzare il modo in cui il gestore HTTP sottostante esegue la richiesta utilizzando il parametro speciale @http. Le opzioni che possono essere incluse nel parametro @http sono le stesse che possono essere impostate quando si crea un'istanza del client con l'opzione 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' ] ]);

Richieste asincrone

È possibile inviare comandi simultaneamente utilizzando le funzionalità asincrone dell'SDK. È possibile inviare le richieste in modo asincrono aggiungendo un suffisso al nome dell'operazione con Async. In questo modo si avvia la richiesta e si restituisce una promessa. La promessa viene soddisfatta con l'oggetto risultato in caso di esito positivo o rifiutata con un'eccezione in caso di errore. In questo modo è possibile creare più promesse e richiedere l'invio simultaneo di richieste HTTP quando il gestore HTTP sottostante trasferisce le richieste.

Importazioni

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

Codice di esempio

// Create an SDK class used to share configuration across clients. $sdk = new Aws\Sdk([ 'region' => 'us-west-2', 'version' => 'latest' ]); // 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();

È possibile forzare il completamento sincrono di una promessa utilizzando il metodo wait della promessa. Forzando il completamento della promessa, inoltre, "si apre" lo stato della promessa per impostazione predefinita, ovvero viene restituito l'esito della promessa oppure viene generata l'eccezione che è stata riscontrata. Quando si richiama wait() su una promessa, il processo si blocca fino a quando la richiesta HTTP non viene completata e il risultato viene popolato, oppure viene creata un'eccezione.

Quando si utilizza l'SDK con una libreria di loop eventi, non bloccare i risultati. Occorre utilizzare invece il metodo then() di un risultato per accedere a una promessa che viene risolta o rifiutata al termine dell'operazione.

Importazioni

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

Codice di esempio

// Create an SDK class used to share configuration across clients. $sdk = new Aws\Sdk([ 'region' => 'us-west-2', 'version' => 'latest' ]); // 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(); }); }

Operazioni con gli oggetti risultato

L'esecuzione di un'operazione corretta restituisce un oggetto Aws\Result. Anziché restituire i dati grezzi XML o JSON di un servizio, l'SDK forza i dati di risposta in una struttura array associativa. Normalizza alcuni aspetti dei dati in base alla sua conoscenza del servizio specifico e la struttura di risposta sottostante.

È possibile accedere ai dati dell' AWSResult come un array associativo PHP.

Importazioni

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

Codice di esempio

// Use the us-east-2 region and latest version of each client. $sharedConfig = [ 'profile' => 'default', 'region' => 'us-east-2', 'version' => 'latest' ]; // 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();

Il contenuto dell'oggetto risultato dipende dall'operazione che è stata eseguita e dalla versione di un servizio. La struttura che risulta da ogni operazione API è documentata nella documentazione API per ciascuna operazione.

L'SDK è integrato con JMESPath, un DSL utilizzato per cercare e modificare i dati JSON o, nel nostro caso, gli array PHP. L'oggetto risultato contiene un metodo search() che è possibile utilizzare per estrarre dati dal risultato in modo più dichiarativo.

Codice di esempio

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

Gestione degli errori

Gestione degli errori sincroni

Se si verifica un errore durante l'esecuzione di un'operazione, viene generata un'eccezione. Per questo motivo, se è necessario gestire gli errori nel codice, utilizza blocchi try/catch intorno alle operazioni. L'SDK genera eccezioni specifiche per il servizio quando si verifica un errore.

Gli esempi seguenti utilizzano Aws\S3\S3Client. Se si verifica un errore, l'eccezione generata sarà del tipo Aws\S3\Exception\S3Exception. Tutte le eccezioni specifiche per il servizio generate dall'SDK si estendono dalla classe Aws\Exception\AwsException. Questa classe contiene informazioni utili sull'errore, tra cui l'id della richiesta, il codice errore e il tipo di errore. Nota per alcuni servizi che la supportano, i dati di risposta vengono convertiti in una struttura array associativa (simile agli oggetti Aws\Result), a cui è possibile accedere come un normale array associativo PHP. Il metodo toArray() restituirà tali dati, se esistenti.

Importazioni

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

Codice di esempio

// Create an SDK class used to share configuration across clients. $sdk = new Aws\Sdk([ 'region' => 'us-west-2', 'version' => 'latest' ]); // 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()); }

Gestione degli errori asincroni

Le eccezioni non vengono generate durante l'invio di richieste asincrone. Al contrario, è necessario utilizzare il metodo then() o otherwise() della promessa restituita per ricevere il risultato o l'errore.

Importazioni

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

Codice di esempio

//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); });

È possibile "aprire" la promessa e causare invece la creazione dell'eccezione.

Importazioni

Importazioni

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

Codice di esempio

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);
//throw exception try { $result = $promise->wait(); } catch (S3Exception $e) { echo $e->getMessage(); }