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 básicos de uso de la versión 3 de AWS SDK for PHP

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

Requisitos previos

Incluya el SDK en su código

Independientemente de la técnica utilizada para instalar el SDK, puede incluir el SDK en su código con tan solo una única instrucción require. Consulte la siguiente tabla para saber qué código PHP se adapta mejor 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 utilizar el SDK para interactuar con un servicio de AWS cree una instancia de un objeto Client. Los objetos cliente tienen métodos que se corresponden con las operaciones de la API del servicio. 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 el SDK debería detectar las credenciales a partir de las variables de entorno, el Archivos config y credentials compartidos en su directorio HOME, AWS Identity and Access Management las credenciales del perfil de instancia de (IAM) , o los proveedores de credenciales..

Todas las opciones de configuración generales del cliente se describen detalladamente en Configuración de la versión 3 de AWS SDK for PHP. 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 documentación de la API 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 es igual al espacio de nombres de un servicio (por ejemplo, "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();

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 operación PutObject de Amazon S3, debe llamar al método Aws\S3\S3Client::putObject().

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)). El SDK buscará 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 de resultado) se define para cada operación en la documentación de la API del SDK (por ejemplo, consulte la documentación de la API para la operación putObject).

Opciones del controlador HTTP

También puede ajustar la forma en que el controlador HTTP subyacente ejecuta la solicitud mediante el uso del parámetro @http especial. 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' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

Solicitudes asíncronas

Puede enviar comandos de forma simultánea utilizando las características 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 solicitudes HTTP de forma simultánea cuando el controlador HTTP subyacente transfiere 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ó. Al llamar a wait() en una promesa, el proceso se bloquea hasta que se completa la solicitud HTTP y el resultado se rellena o se lanza una excepción.

Si utiliza el SDK con una biblioteca de bucles de evento, no bloquee 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 XML o JSON sin procesar de un servicio, el SDK fuerza que los datos de la respuesta aparezcan 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 obtener acceso a los datos del objeto AWSResult como una matriz PHP asociativa.

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 del resultado de cada operación API se documenta en la documentación de la API de cada operación.

El SDK se integra con JMESPath, un DSL que se utiliza para buscar y manipular los datos JSON o, en nuestro caso, matrices PHP. 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. El SDK lanza excepciones específicas del servicio cuando se produce un error.

El siguiente ejemplo utiliza la Aws\S3\S3Client. Si se produce un error, la excepción lanzada será del tipo Aws\S3\Exception\S3Exception. Todas las excepciones específicas de servicios que lanza el SDK son una extensión 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 compatibles, los datos de respuesta se convierten en una estructura matriz asociativa (similar a los objetos de Aws\Result) que se puede evaluar como una matriz asociativa de PHP normal. 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();
}