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 básicos de uso da 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

Incluindo o SDK em seu código

Não importa qual técnica você usou para instalar oSDK, você pode incluir o SDK em seu código com apenas uma única require instrução. Consulte a tabela a seguir para ver o PHP código que melhor se adequa à 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 AWS serviço, instancie um objeto Client. Os objetos do cliente têm métodos que correspondem às operações no serviçoAPI. 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 porque ele SDK deve detectar as credenciais das variáveis de ambiente, do seu HOME diretório, das Arquivos config e credentials compartilhados credenciais do perfil da instância AWS Identity and Access Management (IAM) ou dos provedores de credenciais.

Todas as opções de configuração geral do cliente estão descritas em detalhes no Configuração para a 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 personalizadas de configuração do cliente estão descritas na APIdocumentação de cada cliente.

Usar 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 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 do serviço podem ser fornecidos em uma chave igual ao 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 realizar a PutObjectoperação do Amazon S3, você deve chamar o Aws\S3\S3Client::putObject() método.

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 encontra 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 resultante) é definida para cada operação na API documentação SDK do (por exemplo, consulte a API documentação da putObjectoperação).

HTTPopções de manipulador

Você também pode ajustar a forma como o HTTP manipulador 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' => 'amzn-s3-demo-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 HTTP solicitações simultaneamente quando o HTTP manipulador 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() uma promessa, o processo é bloqueado até que a HTTP solicitação seja concluída e o resultado seja preenchido ou uma exceção seja lançada.

Ao usar a biblioteca SDK com um 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();
    });

Trabalhar com objetos de resultados

A execução de uma operação bem-sucedida retorna um objeto Aws\Result. Em vez de retornar os JSON dados brutos XML ou de um serviço, ele SDK força os dados de 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 dados do AWSResult objeto como uma PHP matriz 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 de resultados de cada API operação está documentada nos API documentos de cada operação.

SDKÉ integrado com JMESPath, DSLusado para pesquisar e manipular JSON dados ou, no nosso caso, PHP matrizes. 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. SDKEle lança exceções específicas do 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 do serviço que os lançamentos SDK lançam se estendem 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 o suportam, os dados de resposta são coagidos a uma estrutura de matriz associativa (semelhante aos Aws\Result objetos), 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();
}