Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Patrones de uso básicos de la AWS SDK for PHP versión 3

Este tema se centra en los patrones de uso básico de AWS SDK for PHP.

Requisitos previos

Incluyendo el SDK en tu código

Independientemente de la técnica que haya utilizado para instalar elSDK, puede incluirlo SDK en su código con una sola require sentencia. Consulte la siguiente tabla para ver el PHP código que mejor se adapte a su técnica de instalación. Sustituya las instancias de /path/to/ por la ruta real de su sistema.

En este tema, utilizamos el método de instalación de Composer. Si utiliza un método de instalación diferente, puede consultar esta sección para encontrar el código require correcto que debe usar.

Resumen de uso

Para usar el SDK para interactuar con un AWS servicio, cree una instancia de un objeto de cliente. Los objetos cliente tienen métodos que se corresponden con las operaciones del servicio. API Para ejecutar una operación determinada, llame al método correspondiente. Este método devuelve un objeto de resultado similar a una matriz cuando se ejecuta correctamente o genera una excepción en caso de error.

Crear un cliente

Puede crear un cliente pasando una matriz asociativa de opciones a un constructor de clientes.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

//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'.

Encontrará información sobre el parámetro opcional "versión" en el temaOpciones de configuración.

Tenga en cuenta que no hemos proporcionado credenciales de forma explícita al cliente. Esto se debe a que SDK deberían detectar las credenciales de las variables de entorno, Archivos config y credentials compartidos las de su HOME directorio, AWS Identity and Access Management las credenciales del perfil de instancia o los proveedores de credenciales. IAM

Todas las opciones de configuración generales del cliente se describen detalladamente en Configuración para la AWS SDK for PHP versión 3. La matriz de opciones proporcionada a un cliente puede variar en función del cliente que esté creando. Estas opciones de configuración de cliente personalizadas se describen en la APIdocumentación de cada cliente.

Utilización de la clase Sdk

La clase Aws\Sdk actúa como una fábrica de clientes y se utiliza para administrar las opciones de configuración compartidas entre varios clientes. Muchas de las opciones que se pueden proporcionar a un constructor de cliente específico también se pueden proporcionar a la clase Aws\Sdk. Estas opciones se aplican después a cada constructor de clientes.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Las opciones que se comparten entre todos los clientes se colocan en pares clave-valor en el nivel de raíz. Los datos de configuración específicos del servicio se pueden proporcionar en una clave que sea igual al espacio de nombres de un servicio (por ejemplo, «S3», «», etc.)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();

Los valores de configuración específicos del servicio son una combinación de los valores específicos del servicio y los valores del nivel de raíz (es decir, los valores específicos del servicio se combinan suavemente con los valores del nivel de raíz).

Ejecutar operaciones de servicio

Puede ejecutar una operación de servicio utilizando el método del mismo nombre en un objeto de cliente. Por ejemplo, para realizar la PutObjectoperación Amazon S3, debe llamar al Aws\S3\S3Client::putObject() método.

Importaciones

require 'vendor/autoload.php';

use Aws\S3\S3Client;

Código de muestra

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

Las operaciones disponibles para un cliente y la estructura de la entrada y la salida se definen en el tiempo de ejecución en función de un archivo de descripción del servicio. Al crear un cliente, debe proporcionar una versión (por ejemplo, "2006-03-01" o "latest" (la más reciente)). SDKBusca el archivo de configuración correspondiente en función de la versión proporcionada.

Todos los métodos de operación del tipo putObject() aceptan un único argumento: una matriz asociativa que representa los parámetros de la operación. La estructura de esta matriz (y la estructura del objeto resultante) se define para cada operación en la SDK API documentación correspondiente (por ejemplo, consulte los API documentos para ver la putObjectoperación).

HTTPopciones de controlador

También puede ajustar la forma en que el HTTP controlador subyacente ejecuta la solicitud mediante el parámetro especial. @http Las opciones que puede incluir en el parámetro @http son las mismas que puede establecer al crear instancias para el cliente con la opción de cliente "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'
    ]
]);

Solicitudes asíncronas

Puede enviar comandos simultáneamente mediante las funciones asíncronas del. SDK Puede enviar solicitudes de forma asíncrona añadiendo el sufijo Async al nombre de la operación. Esto inicia la solicitud y devuelve una promesa. La promesa se cumple cuando el objeto de resultado es correcto o se rechaza con una excepción en caso de error. Esto le permite crear varias promesas y hacer que envíen HTTP solicitudes simultáneamente cuando el controlador subyacente HTTP transfiera las solicitudes.

Importaciones

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

Código de muestra

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

Puede forzar una promesa para que se complete de forma síncrona utilizando el método wait de la promesa. Forzar que se complete la promesa también "desencapsula" el estado de la promesa de forma predeterminada, lo que significa que, o bien devolverá el resultado de la promesa, o lanzará la excepción que se detectó. Cuando se wait() invoca una promesa, el proceso se bloquea hasta que se complete la HTTP solicitud y se complete el resultado o se produzca una excepción.

Cuando lo utilices SDK con una biblioteca de bucles de eventos, no bloquees los resultados. En su lugar, utilice el método then() de un resultado para obtener acceso a una promesa que se resuelve o rechaza cuando se completa la operación.

Importaciones

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

Código de muestra

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

Uso de objetos Result

Si se ejecuta una operación correctamente, se devuelve un objeto Aws\Result. En lugar de devolver los datos sin procesar XML o JSON los datos de un servicio, convierte SDK los datos de respuesta en una estructura de matriz asociativa. El SDK normaliza algunos aspectos de los datos en función de su conocimiento del servicio en concreto y la estructura de respuesta subyacente.

Puede acceder a los datos del AWSResult objeto como una matriz asociativa. PHP

Importaciones

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

Código de muestra

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

El contenido del objeto de resultado depende de la operación que se ha ejecutado y de la versión del servicio. La estructura de resultados de cada API operación está documentada en los API documentos de cada operación.

SDKEstá integrado y DSLse utiliza para buscar y manipular JSON datos o, en nuestro caso, PHP matrices. JMESPath El objeto de resultado contiene un método search() que puede utilizar para extraer datos del resultado de forma más declarativa.

Código de muestra

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

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

Gestión de errores

Gestionar errores síncronos

Si se produce un error al realizar una operación, se genera una excepción. Por este motivo, si necesita administrar errores en el código, utilice bloques try/catch en torno a sus operaciones. Emite excepciones específicas del servicio cuando se SDK produce un error.

El siguiente ejemplo utiliza Aws\S3\S3Client. Si se produce un error, la excepción lanzada será del tipo Aws\S3\Exception\S3Exception. Todas las excepciones específicas del servicio que SDK arrojan provienen de la clase. Aws\Exception\AwsException Esta clase contiene información útil sobre el error, incluido el ID de la solicitud, el código de error y el tipo de error. Tenga en cuenta que para algunos servicios que lo admiten, los datos de respuesta se convierten en una estructura de matriz asociativa (similar a Aws\Result los objetos), a la que se puede acceder como una matriz asociativa normal. PHP El método toArray() devolverá cualquier dato, en caso de que exista.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Gestionar errores asíncronos

Al enviar solicitudes asíncronas no se lanzan excepciones. En lugar de ello, debe utilizar el método then() u otherwise() de la promesa devuelta para recibir el resultado o el error.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Puede "desencapsular" la promesa y hacer que se lance la excepción en su lugar.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

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