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á.
Atualize a partir da versão 2 do AWS SDK for PHP
Este tópico mostra como migrar o código para usar a versão 3 do AWS SDK for PHP e como a nova versão difere da versão 2 do SDK.
nota
O padrão de uso básico do SDK (ou seja, $result = $client->operation($params);
) não foi alterado da versão 2 para a versão 3, o que deve resultar em uma migração suave.
Introdução
A versão 3 do AWS SDK for PHP representa um esforço significativo para melhorar os recursos do SDK, incorporar mais de dois anos de comentários dos clientes, atualizar nossas dependências, melhorar o desempenho e adotar os padrões de PHP mais recentes.
O que há de novo na versão 3?
A versão 3 do AWS SDK for PHP segue os padrões PSR-4 e PSR-7
Outros novos recursos incluem
-
Sistema de middleware para personalizar o comportamento do cliente de serviço
-
Paginadores flexíveis para percorrer resultados paginados
-
Capacidade de consultar dados de objetos de resultado e de paginador com o JMESPath
-
Depuração fácil por meio da opção de configuração
'debug'
Camada HTTP separada
-
O Guzzle 6
é usado por padrão para enviar solicitações, mas o Guzzle 5 também é compatível. -
O SDK funcionará em ambientes em que o cURL não está disponível.
-
Manipuladores HTTP personalizados também são suportados.
Solicitações assíncronas
-
Recursos como waiters e carregamentos fracionados também podem ser usados de forma assíncrona.
-
Fluxos de trabalho assíncronos podem ser criados usando promessas e corrotinas.
-
O desempenho de solicitações simultâneas ou em lotes está melhorado.
O que há de diferente da versão 2?
As dependências do projeto estão atualizadas
As dependências do SDK foram alteradas nesta versão.
-
O SDK agora requer o PHP 5.5+. Usamos geradores
de forma liberal no código do SDK. -
Atualizamos o SDK para usar o Guzzle
6 (ou 5), que fornece a implementação do cliente HTTP subjacente usado pelo SDK para enviar solicitações aos serviços da AWS. A versão mais recente do Guzzle fornece várias melhorias, incluindo solicitações assíncronas, manipuladores HTTP intercambiáveis, conformidade com o PSR-7, melhor desempenho e muito mais. -
O pacote PSR-7 do PHP-FIG (
psr/http-message
) define interfaces para representar solicitações HTTP, respostas HTTP, URLs e streamings. Essas interfaces são usadas em todo o SDK e o Guzzle, o que fornece interoperabilidade com outros pacotes compatíveis do PSR-7. -
A implementação do Guzzle PSR-7 (
guzzlehttp/psr7
) fornece uma implementação das interfaces no PSR-7 e várias classes e funções úteis. O SDK e o Guzzle 6 dependem intensamente desse pacote. -
A implementação do Promises/A+
do Guzzle ( guzzlehttp/promises
) é usada em todo o SDK e no Guzzle para fornecer interfaces de gerenciamento de solicitações assíncronas e corrotinas. Embora o manipulador HTTP multi-cURL do Guzzle implemente o modelo de E/S sem bloqueio que permite solicitações assíncronas, esse pacote fornece a capacidade de programar dentro desse paradigma. Consulte Promessas no AWS SDK for PHP versão 3 para obter mais detalhes. -
A implementação do PHP do JMESPath
( mtdowling/jmespath.php
) é usada no SDK para fornecer a capacidade de consulta de dados doAws\Result::search()
e dos métodosAws\ResultPaginator::search()
. Consulte Expressões do JMESPath no AWS SDK for PHP Versão 3 para obter mais detalhes.
As opções de região e de versão agora são obrigatórias
Ao instanciar um cliente para qualquer serviço, especifique as opções 'region'
e 'version'
. Na versão 2 do AWS SDK for PHP, a 'version'
era totalmente opcional, e a 'region'
era opcional às vezes. Na versão 3, as duas são sempre obrigatórias. Ser explícito quanto a essas duas opções permite bloquear a versão da API e a região da AWS na qual você está codificando. Quando novas versões da API forem criadas ou novas regiões da AWS se tornarem disponíveis, você estará potencialmente isolado de alterações que potencialmente causam interrupções até estar pronto para atualizar explicitamente sua configuração.
nota
Se não estiver preocupado com a versão da API que está usando, basta definir a opção 'version'
como 'latest'
. No entanto, recomendamos que você defina os números da versão da API explicitamente para o código de produção.
Nem todos os serviços estão disponíveis em todas as regiões da AWS. Você pode localizar uma lista de regiões disponíveis usando a referência de Regiões e endpoints.
Para serviços que estão disponíveis somente por meio de um único endpoint global (por exemplo, o Amazon Route 53, o AWS Identity and Access Management e o Amazon CloudFront), instancie clientes com a respectiva região configurada definindo-a como us-east-1
.
Importante
O SDK também inclui clientes com várias regiões, que podem enviar solicitações para diferentes regiões da AWS com base em um parâmetro (@region
) fornecido como um parâmetro de comando. A região usada por padrão por esses clientes é especificada com a opção region
fornecida para o construtor do cliente.
A instanciação do cliente usa o construtor
Na versão 3 do AWS SDK for PHP, a maneira como você instancia um cliente foi alterada. Em vez dos métodos de factory
na versão 2, você pode simplesmente instanciar um cliente usando a palavra-chave new
.
use Aws\DynamoDb\DynamoDbClient; // Version 2 style $client = DynamoDbClient::factory([ 'region' => 'us-east-2' ]); // Version 3 style $client = new DynamoDbClient([ 'region' => 'us-east-2', 'version' => '2012-08-10' ]);
nota
A instanciação de um cliente usando o método factory()
ainda funciona. No entanto, ela é considerada obsoleta.
A configuração do cliente foi alterada
As opções de configuração de clientes na versão 3 do AWS SDK for PHP foram alteradas um pouco em relação à versão 2. Consulte a página Configuração do AWS SDK for PHP Versão 3 para obter uma descrição de todas as opções compatíveis.
Importante
Na versão 3, 'key'
e 'secret'
não são mais opções válidas no nível raiz, mas você pode passá-las como parte da opção 'credentials'
. Um dos motivos pelos quais fizemos isso foi para desencorajar os desenvolvedores de usarem codificação rígida em suas credenciais da AWS em seus projetos.
O objeto Sdk
A versão 3 do AWS SDK for PHP apresenta o objeto Aws\Sdk
como uma substituição do Aws\Common\Aws
. O objeto Sdk
atua como uma fábrica de cliente e é usado para gerenciar as opções de configuração compartilhadas entre vários clientes.
Embora a classe Aws
na versão 2 do SDK funcionasse como um localizador de serviço (ela sempre retornava a mesma instância de um cliente), a classe Sdk
na versão 3 retorna uma nova instância de um cliente sempre que é usada.
O objeto Sdk
também não é compatível com o mesmo formato de arquivo de configuração da versão 2 do SDK. Esse formato de configuração era específico ao Guzzle 3 e agora está obsoleto. A configuração pode ser feita de forma mais simples com matrizes básicas e está documentada em Uso da classe Sdk.
Alguns resultados da API foram alterados
Para fornecer consistência na forma como o SDK analisa o resultado de uma operação da API, o Amazon ElastiCache, o Amazon RDS e o Amazon Redshift agora têm um elemento de encapsulamento adicional em algumas respostas da API.
Por exemplo, a chamada do resultado DescribeEngineDefaultParameters do Amazon RDS na versão 3 agora inclui um elemento "EngineDefaults" de encapsulamento. Na versão 2, esse elemento não estava presente.
$client = new Aws\Rds\RdsClient([ 'region' => 'us-west-1', 'version' => '2014-09-01' ]); // Version 2 $result = $client->describeEngineDefaultParameters(); $family = $result['DBParameterGroupFamily']; $marker = $result['Marker']; // Version 3 $result = $client->describeEngineDefaultParameters(); $family = $result['EngineDefaults']['DBParameterGroupFamily']; $marker = $result['EngineDefaults']['Marker'];
As operações a seguir são afetadas e agora contêm um elemento de encapsulamento na saída do resultado (fornecido abaixo entre parênteses):
-
Amazon ElastiCache
-
AuthorizeCacheSecurityGroupIngress (CacheSecurityGroup)
-
CopySnapshot (Snapshot)
-
CreateCacheCluster (CacheCluster)
-
CreateCacheParameterGroup (CacheParameterGroup)
-
CreateCacheSecurityGroup (CacheSecurityGroup)
-
CreateCacheSubnetGroup (CacheSubnetGroup)
-
CreateReplicationGroup (ReplicationGroup)
-
CreateSnapshot (Snapshot)
-
DeleteCacheCluster (CacheCluster)
-
DeleteReplicationGroup (ReplicationGroup)
-
DeleteSnapshot (Snapshot)
-
DescribeEngineDefaultParameters (EngineDefaults)
-
ModifyCacheCluster (CacheCluster)
-
ModifyCacheSubnetGroup (CacheSubnetGroup)
-
ModifyReplicationGroup (ReplicationGroup)
-
PurchaseReservedCacheNodesOffering (ReservedCacheNode)
-
RebootCacheCluster (CacheCluster)
-
RevokeCacheSecurityGroupIngress (CacheSecurityGroup)
-
-
Amazon RDS
-
AddSourceIdentifierToSubscription (EventSubscription)
-
AuthorizeDBSecurityGroupIngress (DBSecurityGroup)
-
CopyDBParameterGroup (DBParameterGroup)
-
CopyDBSnapshot (DBSnapshot)
-
CopyOptionGroup (OptionGroup)
-
CreateDBInstance (DBInstance)
-
CreateDBInstanceReadReplica (DBInstance)
-
CreateDBParameterGroup (DBParameterGroup)
-
CreateDBSecurityGroup (DBSecurityGroup)
-
CreateDBSnapshot (DBSnapshot)
-
CreateDBSubnetGroup (DBSubnetGroup)
-
CreateEventSubscription (EventSubscription)
-
CreateOptionGroup (OptionGroup)
-
DeleteDBInstance (DBInstance)
-
DeleteDBSnapshot (DBSnapshot)
-
DeleteEventSubscription (EventSubscription)
-
DescribeEngineDefaultParameters (EngineDefaults)
-
ModifyDBInstance (DBInstance)
-
ModifyDBSubnetGroup (DBSubnetGroup)
-
ModifyEventSubscription (EventSubscription)
-
ModifyOptionGroup (OptionGroup)
-
PromoteReadReplica (DBInstance)
-
PurchaseReservedDBInstancesOffering (ReservedDBInstance)
-
RebootDBInstance (DBInstance)
-
RemoveSourceIdentifierFromSubscription (EventSubscription)
-
RestoreDBInstanceFromDBSnapshot (DBInstance)
-
RestoreDBInstanceToPointInTime (DBInstance)
-
RevokeDBSecurityGroupIngress (DBSecurityGroup)
-
-
Amazon Redshift
-
AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)
-
AuthorizeSnapshotAccess (Snapshot)
-
CopyClusterSnapshot (Snapshot)
-
CreateCluster (Cluster)
-
CreateClusterParameterGroup (ClusterParameterGroup)
-
CreateClusterSecurityGroup (ClusterSecurityGroup)
-
CreateClusterSnapshot (Snapshot)
-
CreateClusterSubnetGroup (ClusterSubnetGroup)
-
CreateEventSubscription (EventSubscription)
-
CreateHsmClientCertificate (HsmClientCertificate)
-
CreateHsmConfiguration (HsmConfiguration)
-
DeleteCluster (Cluster)
-
DeleteClusterSnapshot (Snapshot)
-
DescribeDefaultClusterParameters (DefaultClusterParameters)
-
DisableSnapshotCopy (Cluster)
-
EnableSnapshotCopy (Cluster)
-
ModifyCluster (Cluster)
-
ModifyClusterSubnetGroup (ClusterSubnetGroup)
-
ModifyEventSubscription (EventSubscription)
-
ModifySnapshotCopyRetentionPeriod (Cluster)
-
PurchaseReservedNodeOffering (ReservedNode)
-
RebootCluster (Cluster)
-
RestoreFromClusterSnapshot (Cluster)
-
RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)
-
RevokeSnapshotAccess (Snapshot)
-
RotateEncryptionKey (Cluster)
-
As classes de Enum foram removidas
Removemos as classes de Enum
(por exemplo, Aws\S3\Enum\CannedAcl
) que existiam na versão 2 do AWS SDK for PHP. As Enums eram classes concretas dentro da API pública do SDK que continham constantes que representavam grupos de valores de parâmetros válidos. Como essas enums são específicas às versões da API, podem mudar ao longo do tempo, podem entrar em conflito com palavras reservadas do PHP e acabaram não sendo muito úteis, elas foram removidas da versão 3. Isso oferece suporte ao controle por dados e à natureza agnóstica à versão da API da versão 3.
Em vez de usar valores de objetos Enum
, use os valores literais diretamente (por exemplo, CannedAcl::PUBLIC_READ
→ 'public-read'
).
As classes de exceção refinada foram removidas
Removemos as classes de exceção refinada que existiam nos namespaces de cada serviço (por exemplo, Aws\Rds\Exception\{SpecificError}Exception
) por motivos muito semelhantes aos da remoção das Enums. As exceções geradas por um serviço ou operação dependem de qual versão da API é usada (elas podem mudar de versão para a versão). Além disso, a lista completa das exceções que podem ser geradas por uma operação não está disponível, o que tornou as classes de exceção refinada da versão 2 incompletas.
Lide com erros capturando a classe da exceção raiz de cada serviço (por exemplo, Aws\Rds\Exception\RdsException
). Você pode usar o método getAwsErrorCode()
da exceção para verificar se há códigos de erro específicos. Isso é funcionalmente equivalente à captura de classes de diferentes exceções, mas fornece essa função sem sobrecarregar o SDK.
As classes de fachada estática foram removidas
Na versão 2 do AWS SDK for PHP, havia um recurso obscuro inspirado pelo Laravel que permitia chamar enableFacades()
na classe Aws
para habilitar o acesso estático a vários clientes de serviços. Esse recurso viola as melhores práticas do PHP e interrompemos sua documentação há mais de um ano. Na versão 3, esse recurso foi completamente removido. Recupere seus objetos de cliente do objeto Aws\Sdk
e use-os como instâncias do objetos, não como classes estáticas.
Os paginadores substituem o iteradores
A versão 2 do AWS SDK for PHP tinha um recurso chamado * iterators*. Esses recursos eram objetos que eram usados para iterar sobre resultados paginados. Uma reclamação que tivemos sobre eles foi que não eram suficientemente flexíveis, porque o iterador só emitia valores específicos de cada resultado. Se houvesse outros valores necessários nos resultados, só era possível recuperá-los por meio de ouvintes de eventos.
Na versão 3, os iteradores foram substituídos por Paginadores. O objetivo é semelhante, mas os paginadores são mais flexíveis. Isso ocorre porque eles geram objetos de resultados em vez de valores de uma resposta.
Os exemplos a seguir mostram como os paginadores são diferentes dos iteradores, demonstrando como recuperar os resultados paginados para a operação S3 ListObjects
na versão 2 e na versão 3.
// Version 2 $objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($objects as $object) { echo $object['Key'] . "\n"; }
// Version 3 $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results as $result) { // You can extract any data that you want from the result. foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } }
Os objetos do paginador têm um método search()
que permite que você use expressões do JMESPath mais facilmente para extrair dados do conjunto de resultados.
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results->search('Contents[].Key') as $key) { echo $key . "\n"; }
nota
O método getIterator()
ainda é suportado para permitir uma transição suave para a versão 3, mas recomendamos que você migre seu código para usar paginadores.
Muitas abstrações de nível superior foram alteradas
Em geral, muitas das abstrações de nível superior (objetos auxiliares específicos ao serviço, além dos clientes) foram aprimorados ou atualizados. Alguns foram até removidos.
-
- Atualizado:
-
-
A maneira como você usa o carregamento fracionado do Amazon S3 foi alterada. O carregamento fracionado do Amazon S3 Glacier foi alterado de forma semelhante.
-
A maneira de criar Pre-signed URLs do Amazon S3 foi alterada.
-
O namespace
Aws\S3\Sync
foi substituído pela classeAws\S3\Transfer
. Os métodosS3Client::uploadDirectory()
eS3Client::downloadBucket()
ainda estão disponíveis, mas têm diferentes opções. Consulte a documentação do Gerenciador de transferências do Amazon S3 com o AWS SDK for PHP versão 3. -
Aws\S3\Model\ClearBucket
eAws\S3\Model\DeleteObjectsBatch
foram substituídos porAws\S3\BatchDelete
eS3Client::deleteMatchingObjects()
. -
As opções e comportamentos do Uso do manipulador de sessão do DynamoDB com o AWS SDK for PHP Versão 3 foram levemente alterados.
-
O namespace
Aws\DynamoDb\Model\BatchRequest
foi substituído porAws\DynamoDb\WriteRequestBatch
. Consulte a documentação do DynamoDB WriteRequestBatch. -
O
Aws\Ses\SesClient
agora lida com a codificação em base64 deRawMessage
usando a operaçãoSendRawEmail
.
-
-
- Removidos:
-
-
As classes Amazon DynamoDB
Item
,Attribute
eItemIterator
- essas classes foram reprovadas previamente na Versão 2.7.0. -
Validador de mensagens do Amazon SNS - esse agora é um projeto leve e separado
que não requer o SDK como uma dependência. No entanto, esse projeto está incluído nas distribuições de Phar e ZIP do SDK. Você pode encontrar um guia de conceitos básicos no blog de desenvolvimento do AWS PHP . -
O
AcpBuilder
do Amazon S3 e os objetos relacionados foram removidos.
-
Comparação dos códigos de exemplo das duas versões do SDK
Os exemplos a seguir mostram algumas das maneiras nas quais o uso da versão 3 do AWS SDK for PHP pode diferir do uso da versão 2.
Exemplo: Operação de ListObjects do Amazon S3
Na versão 2 do SDK
<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = S3Client::factory([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }
Na versão 3 do SDK
Principais diferenças:
-
Use
new
em vez defactory()
para instanciar o cliente. -
As opções
'version'
e'region'
são obrigatórias durante a instanciação.
<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = new S3Client([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1', 'version' => '2006-03-01' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }
Exemplo: instanciação de um cliente com configuração global
Na versão 2 do SDK
<?php return array( 'includes' => array('_aws'), 'services' => array( 'default_settings' => array( 'params' => array( 'profile' => 'my_profile', 'region' => 'us-east-1' ) ), 'dynamodb' => array( 'extends' => 'dynamodb', 'params' => array( 'region' => 'us-west-2' ) ), ) );
<?php require '/path/to/vendor/autoload.php'; use Aws\Common\Aws; $aws = Aws::factory('path/to/my/config.php'); $sqs = $aws->get('sqs'); // Note: SQS client will be configured for us-east-1. $dynamodb = $aws->get('dynamodb'); // Note: DynamoDB client will be configured for us-west-2.
Na versão 3 do SDK
Principais diferenças:
-
Use a classe
Aws\Sdk
em vez daAws\Common\Aws
. -
Não há nenhum arquivo de configuração. Em vez disso, use uma matriz para configuração.
-
A opção
'version'
é necessária durante a instanciação. -
Use os métodos de
create<Service>()
em vez deget('<service>')
.
<?php require '/path/to/vendor/autoload.php'; $sdk = new Aws\Sdk([ 'profile' => 'my_profile', 'region' => 'us-east-1', 'version' => 'latest', 'DynamoDb' => [ 'region' => 'us-west-2', ], ]); $sqs = $sdk->createSqs(); // Note: Amazon SQS client will be configured for us-east-1. $dynamodb = $sdk->createDynamoDb(); // Note: DynamoDB client will be configured for us-west-2.