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

Includendo il SDK nel codice

Indipendentemente dalla tecnica utilizzata per l'installazioneSDK, è possibile includerla SDK nel codice con una sola require istruzione. Consultate la tabella seguente per il PHP codice più adatto alla vostra tecnica di installazione. Sostituisci tutte le istanze di /path/to/ con il percorso effettivo sul sistema.

In questo argomento, si assume 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 utilizzarlo SDK per interagire con un AWS servizio, crea un'istanza di un oggetto Client. Gli oggetti client hanno metodi che corrispondono alle operazioni del servizio. API 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é SDK dovrebbe rilevare le credenziali dalle variabili di ambiente, dalle credenziali della Condivisi e file configcredentials HOME directory AWS Identity and Access Management (IAM), dalle credenziali del profilo dell'istanza 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 di configurazione client personalizzate sono descritte nella APIdocumentazione di ciascun 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"). SDKTrova 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 ogni operazione nella SDK API documentazione (ad esempio, vedere API i documenti per l'putObjectoperazione).

HTTPopzioni del gestore

È inoltre possibile ottimizzare il modo in cui il HTTP gestore 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' => 'amzn-s3-demo-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

Richieste asincrone

È possibile inviare comandi contemporaneamente utilizzando le funzionalità asincrone di. 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. Ciò consente di creare più promesse e fare in modo che inviino HTTP richieste contemporaneamente quando il gestore sottostante HTTP 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 wait() si richiama una promessa, il processo si blocca fino al completamento della HTTP richiesta e al completamento del risultato o alla generazione di un'eccezione.

Quando utilizzate la libreria SDK with an event loop, non bloccate 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 gli oggetti dei risultati

L'esecuzione di un'operazione corretta restituisce un oggetto Aws\Result. Invece di restituire i dati grezzi XML o JSON i dati di un servizio, SDK costringe i dati di risposta in una struttura di 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 associativoPHP.

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 dei risultati di ogni API operazione è documentata nei API documenti relativi a ciascuna operazione.

SDKÈ integrato con JMESPath, DSLviene utilizzato per cercare e manipolare JSON dati o, nel nostro caso, 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. SDKGenera eccezioni specifiche del 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 del servizio generate si estendono dalla classe. SDK 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 lo supportano, i dati di risposta vengono inseriti in una struttura di array associativa (simile Aws\Result agli oggetti), 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();
}