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á. # Migrando da versão 2 do AWS SDK para PHP Este tópico mostra como migrar o código para usar a versão 3 do AWS SDK para 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 para PHP representa um esforço significativo para melhorar os recursos do SDK, incorporar mais de dois anos de feedback de clientes, atualizar nossas dependências, melhorar o desempenho e adotar os padrões PHP mais recentes. ## O que há de novo na versão 3? A versão 3 do AWS SDK para PHP segue os padrões [PSR-4 e PSR-7 e seguirá o [SemVer](http://semver.org/)padrão](http://php-fig.org) daqui para frente. Outros atributos novos 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 *resultados* e *paginadores* com *JMESPath* + Depuração fácil por meio da opção de configuração `'debug'` ### Camada HTTP separada + O [Guzzle 6](http://guzzlephp.org) é 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 foram atualizadas As dependências do SDK foram alteradas nesta versão. + O SDK agora requer o PHP 8.1\$1. Usamos [geradores](http://php.net/manual/en/language.generators.overview.php) de forma liberal no código do SDK. + Atualizamos o SDK para usar o [Guzzle 6](http://guzzlephp.org) (ou 5), que fornece a implementação subjacente do cliente HTTP usada pelo SDK para enviar solicitações aos serviços. 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, URLs respostas HTTP e fluxos. 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\$1](https://promisesaplus.com) 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, em última análise, implemente o I/O modelo sem bloqueio que permite solicitações assíncronas, esse pacote fornece a capacidade de programar dentro desse paradigma. Consulte [Promessas na AWS SDK para PHP versão 3](guide_promises.md) para obter mais detalhes. + A implementação PHP de [JMESPath](http://jmespath.org/)(`mtdowling/jmespath.php`) é usada no SDK para fornecer a capacidade de consulta de dados dos métodos `Aws\Result::search()` e. `Aws\ResultPaginator::search()` Consulte [JMESPath Expressões na AWS SDK para PHP versão 3](guide_jmespath.md) para obter mais detalhes. ### As opções de região e 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 para PHP, `'version'` era totalmente opcional e`'region'`, às vezes, opcional. Na versão 3, as duas são sempre obrigatórias. Ser explícito sobre essas duas opções permite que você bloqueie a versão da API e a AWS região na qual você está codificando. Quando novas versões da API forem criadas ou novas AWS regiões forem disponibilizadas, você ficará isolado de possíveis alterações significativas até que esteja 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 AWS regiões. Você pode localizar uma lista de regiões disponíveis usando a referência de [Regiões e endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). Para serviços que estão disponíveis somente por meio de um único endpoint global (por exemplo, Amazon Route 53 e Amazon CloudFront) AWS Identity and Access Management, instancie clientes com a região configurada definida como. `us-east-1` **Importante** O SDK também inclui clientes multirregionais, que podem enviar solicitações para diferentes AWS regiões com base em um parâmetro (`@region`) fornecido como 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 para PHP, a forma como você instancia um cliente mudou. 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 do cliente na versão 3 do AWS SDK para PHP mudaram um pouco em relação à versão 2. Consulte a página [Configuração da AWS SDK para PHP Versão 3](guide_configuration.md) para obter uma descrição de todas as opções suportadas. **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 desencorajar os desenvolvedores de codificar suas AWS credenciais em seus projetos. #### O objeto Sdk A versão 3 do AWS SDK para PHP apresenta o `Aws\Sdk` objeto como substituto `Aws\Common\Aws` do. 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](configuring-service-clients-code.md#sdk-class). ### Alguns resultados da API foram alterados Para fornecer consistência na forma como o SDK analisa o resultado de uma operação de API, a Amazon, o Amazon RDS e o ElastiCache Amazon Redshift agora têm um elemento de empacotamento adicional em algumas respostas da API. Por exemplo, chamar o [DescribeEngineDefaultParameters](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeEngineDefaultParameters.html)resultado do Amazon RDS na versão 3 agora inclui um elemento de empacotamento “EngineDefaults”. 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 (Instantâneo) + CreateCacheCluster (CacheCluster) + CreateCacheParameterGroup (CacheParameterGroup) + CreateCacheSecurityGroup (CacheSecurityGroup) + CreateCacheSubnetGroup (CacheSubnetGroup) + CreateReplicationGroup (ReplicationGroup) + CreateSnapshot (Instantâneo) + DeleteCacheCluster (CacheCluster) + DeleteReplicationGroup (ReplicationGroup) + DeleteSnapshot (Instantâneo) + DescribeEngineDefaultParameters (EngineDefaults) + ModifyCacheCluster (CacheCluster) + ModifyCacheSubnetGroup (CacheSubnetGroup) + ModifyReplicationGroup (ReplicationGroup) + PurchaseReservedCacheNodesOffering (ReservedCacheNode) + RebootCacheCluster (CacheCluster) + RevokeCacheSecurityGroupIngress (CacheSecurityGroup) + Amazon RDS + AddSourceIdentifierToSubscription (EventSubscription) + Autorizar DBSecurity GroupIngress (DBSecurityGrupo) + DBParameterGrupo de cópias (DBParameterGrupo) + Copiar DBSnapshot (DBSnapshot) + CopyOptionGroup (OptionGroup) + Criar DBInstance (DBInstance) + Criar DBInstance ReadReplica (DBInstance) + Criar DBParameter grupo (DBParameterGrupo) + Criar DBSecurity grupo (DBSecurityGrupo) + Criar DBSnapshot (DBSnapshot) + Criar DBSubnet grupo (DBSubnetGrupo) + CreateEventSubscription (EventSubscription) + CreateOptionGroup (OptionGroup) + Excluir DBInstance (DBInstance) + Excluir DBSnapshot (DBSnapshot) + DeleteEventSubscription (EventSubscription) + DescribeEngineDefaultParameters (EngineDefaults) + Modificar DBInstance (DBInstance) + Modificar DBSubnet grupo (DBSubnetGrupo) + ModifyEventSubscription (EventSubscription) + ModifyOptionGroup (OptionGroup) + PromoteReadReplica (DBInstance) + PurchaseReservedDBInstancesOferta (reservadaDBInstance) + Reinicializar DBInstance () DBInstance + RemoveSourceIdentifierFromSubscription (EventSubscription) + Restaurar DBInstance de DBSnapshot (DBInstance) + Restaurar DBInstance ToPointInTime (DBInstance) + Revoke DBSecurity GroupIngress (DBSecurityGrupo) + banco de dados de origem + AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup) + AuthorizeSnapshotAccess (Instantâneo) + CopyClusterSnapshot (Instantâneo) + CreateCluster (Cluster) + CreateClusterParameterGroup (ClusterParameterGroup) + CreateClusterSecurityGroup (ClusterSecurityGroup) + CreateClusterSnapshot (Instantâneo) + CreateClusterSubnetGroup (ClusterSubnetGroup) + CreateEventSubscription (EventSubscription) + CreateHsmClientCertificate (HsmClientCertificate) + CreateHsmConfiguration (HsmConfiguration) + DeleteCluster (Cluster) + DeleteClusterSnapshot (Instantâneo) + DescribeDefaultClusterParameters (DefaultClusterParameters) + DisableSnapshotCopy (Cluster) + EnableSnapshotCopy (Cluster) + ModifyCluster (Cluster) + ModifyClusterSubnetGroup (ClusterSubnetGroup) + ModifyEventSubscription (EventSubscription) + ModifySnapshotCopyRetentionPeriod (Cluster) + PurchaseReservedNodeOffering (ReservedNode) + RebootCluster (Cluster) + RestoreFromClusterSnapshot (Cluster) + RevokeClusterSecurityGroupIngress (ClusterSecurityGroup) + RevokeSnapshotAccess (Instantâneo) + 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 para 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 para PHP, havia um recurso obscuro inspirado no Laravel que permitia que você `enableFacades()` chamasse a `Aws` classe para permitir o acesso estático aos vários clientes de serviço. 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 para PHP tinha um recurso chamado \$1 iterators\$1. 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](guide_paginators.md). 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' => 'amzn-s3-demo-bucket']); foreach ($objects as $object) { echo $object['Key'] . "\n"; } ``` ``` // Version 3 $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-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 `search()` método que permite usar [JMESPath](guide_jmespath.md)expressões para extrair dados mais facilmente do conjunto de resultados. ``` $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-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](s3-multipart-upload.md) foi alterada. O Multipart Upload do Amazon Glacier foi alterado de maneira semelhante. + A forma de criar o [Amazon S3 pré-assinado mudou URLs](s3-presigned-url.md). + O namespace `Aws\S3\Sync` foi substituído pela classe `Aws\S3\Transfer`. Os métodos `S3Client::uploadDirectory()` e `S3Client::downloadBucket()` ainda estão disponíveis, mas têm diferentes opções. Consulte a documentação do [Amazon S3 Transfer Manager com a AWS SDK para PHP versão](s3-transfer.md) 3. + `Aws\S3\Model\ClearBucket` e `Aws\S3\Model\DeleteObjectsBatch` foram substituídos por `Aws\S3\BatchDelete` e `S3Client::deleteMatchingObjects()`. + As opções e os comportamentos do [Using the DynamoDB Session Handler AWS SDK para PHP com a versão](service_dynamodb-session-handler.md) 3 mudaram um pouco. + O namespace `Aws\DynamoDb\Model\BatchRequest` foi substituído por `Aws\DynamoDb\WriteRequestBatch`. Consulte a documentação do [DynamoDB. WriteRequestBatch](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.DynamoDb.WriteRequestBatch.html) + O `Aws\Ses\SesClient` agora lida com a codificação em base64 de `RawMessage` usando a operação `SendRawEmail`. + **Removidos:** + Classes `Item`, `Attribute` e `ItemIterator` do Amazon DynamoDB: essas classes foram descontinuadas previamente na [Versão 2.7.0](https://github.com/aws/aws-sdk-php/blob/3.0.0/CHANGELOG.md#270===2014-10-08). + Validador de mensagens do Amazon SNS: esse agora é [um projeto leve e separado](https://github.com/aws/aws-php-sns-message-validator) 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 introdução [no blog de desenvolvimento de AWS PHP](https://aws.amazon.com/blogs/developer/receiving-amazon-sns-messages-in-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 pelas quais o uso da versão 3 do AWS SDK para PHP difere da versão 2. ### Exemplo: operação `ListObjects` do Amazon S3 #### Na versão 2 do SDK ``` 'my-credential-profile', 'region' => 'us-east-1' ]); try { $result = $s3->listObjects([ 'Bucket' => 'amzn-s3-demo-bucket', '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 de `factory()` para instanciar o cliente. + As opções `'version'` e `'region'` são obrigatórias durante a instanciação. ``` 'my-credential-profile', 'region' => 'us-east-1', 'version' => '2006-03-01' ]); try { $result = $s3->listObjects([ 'Bucket' => 'amzn-s3-demo-bucket', '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 ``` 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' ) ), ) ); ``` ``` 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 da `Aws\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()` em vez de `get('')`. ``` '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. ```