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 della AWS SDK for PHP versione 3

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

Prerequisiti

Inclusione dell'SDK nel 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.

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

Riepilogo dell'utilizzo

Per utilizzare l'SDK per interagire con un AWS servizio, crea un'istanza di un oggetto Client. Gli oggetti client hanno metodi che corrispondono alle 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([
    'region' => 'us-east-2'  // Since version 3.277.10 of the SDK,
]);                          // the 'version' parameter defaults to 'latest'.

Le informazioni sul parametro opzionale «version» sono disponibili nell'argomento delle opzioni di configurazione.

Si noti che non abbiamo esplicitamente fornito le credenziali al client. Questo perché l'SDK dovrebbe rilevare le credenziali dalle variabili di ambiente, dalla directory HOME, dalle credenziali del Condivisi e file configcredentialsprofilo di istanza AWS Identity and Access Management (IAM) o dai provider di credenziali.

Tutte le opzioni generali di configurazione del client sono descritte in dettaglio in. Configurazione per la AWS SDK for PHP versione 3 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 Sdk classe

La classe Aws\Sdk agisce come un client factory e viene utilizzata per gestire le opzioni di configurazione condivise da più client. Molte delle opzioni che possono essere fornite a un costruttore client specifico possono essere fornite anche alla Aws\Sdk classe. 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'
];
// 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 del servizio possono essere forniti in una chiave che è la stessa del namespace di un servizio (ad esempio, «S3", «», ecc.). DynamoDb

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

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).

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 l'PutObjectoperazione Amazon S3, è necessario chiamare il Aws\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'
];

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

Lavorare con oggetti di 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 dall' AWSResult oggetto come un array PHP associativo.

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',
];

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

// 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 asincrona degli errori

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

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