As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Padrões de uso básico do AWS SDK for PHP Versão 3

Este tópico se concentra nos padrões de uso básico do AWS SDK for PHP.

Pré-requisitos

Incluir o SDK em seu código

Independentemente da técnica usada para instalar o SDK, é possível incluir o SDK em seu código com apenas uma única instrução require. Consulte a tabela a seguir para obter o código PHP mais adequado para sua técnica de instalação. Substitua todas as instâncias de /path/to/ pelo caminho real em seu sistema.

Neste tópico, assumimos o método de instalação do Composer. Se estiver usando outro método de instalação, você poderá voltar a esta seção para localizar o código require correto a ser usado.

Resumo de uso

Para usar o SDK para interagir com um serviço da AWS, instancie um objeto de Cliente. Os objetos de Cliente têm métodos que correspondem com operações na API do serviço. Para executar uma determinada operação, chame o método correspondente. Esse método retorna um objeto de Resultado semelhante a uma matriz quando bem-sucedido ou gera uma Exceção em caso de falha.

Criar um cliente

Você pode criar um cliente passando uma matriz associativa de opções para um construtor do cliente.

Importações

require 'vendor/autoload.php';

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

Código de exemplo

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

Informações sobre o parâmetro opcional “versão” estão disponíveis no tópico de opções de configuração.

Observe que não fornecemos explicitamente credenciais ao cliente. Isso ocorre porque o SDK deve detectar as credenciais de variáveis de ambiente, o Arquivos config e credentials compartilhados em seu diretório HOME, credenciais de perfil de instância AWS Identity and Access Management (IAM) ou provedores de credenciais.

Todas as opções de configuração geral do cliente são descritas em detalhes no Configuração do AWS SDK for PHP Versão 3. A matriz de opções fornecidas a um cliente pode variar com base no cliente que você está criando. Essas opções de configuração personalizada de cliente são descritas na documentação da API para cada cliente.

Usando a Classe Sdk

A classe Aws\Sdk atua como uma fábrica de cliente e é usada para gerenciar as opções de configuração compartilhadas entre vários clientes. Muitas das opções que podem ser fornecidas para um determinado construtor de cliente também podem ser fornecidas para a classe Aws\Sdk. Em seguida, essas opções são aplicadas a cada construtor de cliente.

Importações

require 'vendor/autoload.php';

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

Código de exemplo

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

As opções que são compartilhadas entre todos os clientes são colocadas em pares de chave-valor no nível raiz. Os dados de configuração específicos ao serviço podem ser fornecidos em uma chave que é a mesma que o namespace de um serviço (por exemplo, "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();

Os valores de configuração específicos ao serviço são uma união dos valores específicos ao serviço e dos valores em nível raiz (ou seja, os valores específicos ao serviço são mesclados superficialmente com os valores em nível raiz).

Execução de operações do serviço

É possível executar uma operação de serviço chamando o método do mesmo nome em um objeto do cliente. Por exemplo, para executar a operação PutObject do Amazon S3, você deve chamar o método Aws\S3\S3Client::putObject().

Importações

require 'vendor/autoload.php';

use Aws\S3\S3Client;

Código de exemplo

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

As operações disponíveis para um cliente e a estrutura de entrada e saída são definidas em tempo de execução com base em um arquivo de descrição do serviço. Ao criar um cliente, é necessário fornecer uma versão (por exemplo, "2006-03-01" ou "mais recente"). O SDK localiza o arquivo de configuração correspondente com base na versão fornecida.

Todos os métodos de operação, como o putObject(), aceitam um único argumento, uma matriz associativa que representa os parâmetros da operação. A estrutura dessa matriz (e a estrutura do objeto do resultado) é definida para cada operação na Documentação da API do SDK (por exemplo, consulte a documentação da API para a operação putObject).

Opções do manipulador HTTP

Você também pode ajustar como o manipulador HTTP subjacente executa a solicitação usando o parâmetro especial @http. As opções que podem ser incluídas no parâmetro @http são as mesmas que podem ser definidas ao instanciar o cliente com a opção 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'
    ]
]);

Solicitações assíncronas

Você pode enviar comandos simultaneamente usando os recursos assíncronos do SDK. Você pode enviar solicitações de forma assíncrona colocando o sufixo Async no nome de uma operação. Isso inicia a solicitação e retorna uma promessa. A promessa é preenchida com o objeto do resultado em caso de êxito ou rejeitada com uma exceção em caso de falha. Isso permite criar várias promessas e fazer com que elas enviem solicitações HTTP simultaneamente quando o manipulador HTTP subjacente transfere as solicitações.

Importações

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

Código de exemplo

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

Você pode forçar uma promessa a concluir de forma síncrona usando o método wait da promessa. Forçar a promessa a ser concluída também "decodifica" o estado da promessa por padrão, o que significa que ela retornará o resultado da promessa ou gerará a exceção encontrada. Ao chamar wait() em uma promessa, o processo é bloqueado até que a solicitação HTTP seja concluída e o resultado seja preenchido ou que uma exceção seja gerada.

Ao usar o SDK com uma biblioteca de loop de eventos, não bloqueie os resultados. Em vez disso, use o método then() de um resultado para acessar uma promessa que é resolvida ou rejeitada quando a operação é concluída.

Importações

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

Código de exemplo

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

Como trabalhar com objetos de resultados

A execução de uma operação bem-sucedida retorna um objeto Aws\Result. Em vez de retornar os dados brutos XML ou JSON de um serviço, o SDK força os dados da resposta em uma estrutura de matriz associativa. Ele normaliza alguns aspectos dos dados com base em seu conhecimento do serviço específico e da estrutura da resposta subjacente.

Você pode acessar os dados do objeto AWSResult como uma matriz PHP associativa.

Importações

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

Código de exemplo

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

O conteúdo do objeto do resultado depende da operação executada e da versão de um serviço. A estrutura do resultado de cada operação da API é documentada na documentação da API para cada operação.

O SDK é integrado com o JMESPath, um DSL usado para pesquisar e manipular dados JSON ou, em nosso caso, matrizes PHP. O objeto do resultado contém um método search() que você pode usar para extrair dados de forma declarativa do resultado.

Código de exemplo

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

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

Tratamento de erros

Tratamento de erros síncronos

Se ocorrer um erro durante a execução de uma operação, será gerada uma exceção. Por esse motivo, se você precisar tratar de erros em seu código, use blocos try/catch em torno de suas operações. O SDK gera exceções específicas ao serviço quando ocorre um erro.

O exemplo a seguir usa a Aws\S3\S3Client. Se houver um erro, a exceção gerada será do tipo Aws\S3\Exception\S3Exception. Todas as exceções específicas ao serviço que o SDK gera são estendidas da classe Aws\Exception\AwsException. Essa classe contém informações úteis sobre a falha, incluindo o ID da solicitação, o código do erro e o tipo do erro. Observe que, para alguns serviços que oferecem suporte a ele, os dados de resposta são impelidos para uma estrutura de matriz associativa (semelhante a objetos Aws\Result), que pode ser acessada como uma matriz PHP associativa normal. O método toArray() retornará quaisquer dados, se eles existirem.

Importações

require 'vendor/autoload.php';

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

Código de exemplo

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

Tratamento de erros assíncronos

As exceções não são geradas ao enviar solicitações assíncronas. Em vez disso, você deve usar o método then() ou otherwise() da promessa retornada para receber o resultado ou o erro.

Importações

require 'vendor/autoload.php';

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

Código de exemplo

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

Você pode "decodificar" a promessa e fazer com que a exceção seja gerada.

Importações

require 'vendor/autoload.php';

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

Código de exemplo

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

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