Aggiornamento dalla versione 2 dell'AWS SDK for PHP - AWS SDK for PHP

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Aggiornamento dalla versione 2 dell'AWS SDK for PHP

Questo argomento mostra come migrare il codice per utilizzare la versione 3 dell'AWS SDK for PHP e come la nuova versione differisce dalla versione 2 dell'SDK.

Nota

Il modello di utilizzo di base dell'SDK (ad esempio, $result = $client->operation($params);) non ha subito modifiche dalla versione 2 alla versione 3, pertanto la migrazione dovrebbe risultare agevole.

Introduzione

La versione 3 dell'AWS SDK for PHP rappresenta un notevole sforzo per migliorare le funzionalità dell'SDK, integrare più di due anni di feedback dei clienti, aggiornare le nostre dipendenze, migliorare le prestazioni e adottare i più recenti standard PHP.

Novità della versione 3

La versione 3 dell'AWS SDK for PHP segue gli standard PSR-4 e PSR-7 e in futuro seguirà lo standard SemVer.

Altre nuove caratteristiche includono

  • Sistema middleware per la personalizzazione del comportamento del client di servizio

  • Impaginatori flessibili per navigare attraverso i risultati impaginati

  • Possibilità di eseguire query sui dati da oggetti risultato e impaginatore con JMESPath

  • Debug semplice tramite l'opzione di configurazione 'debug'

Livello HTTP disassociato

  • Guzzle 6 viene utilizzato per impostazione predefinita per l'invio di richieste, ma è supportato anche Guzzle 5.

  • L'SDK funzionerà in ambienti in cui cURL non è disponibile.

  • Sono supportati anche i gestori HTTP personalizzati.

Richieste asincrone

  • Caratteristiche come waiters e uploader in più parti possono essere utilizzate anche in modo asincrono.

  • I flussi di lavoro asincroni possono essere creati utilizzando promesse e coroutine.

  • Le prestazioni delle richieste simultanee o in batch sono migliorate.

Cosa cambia rispetto alla versione 2

Le dipendenze di progetto sono aggiornate

Le dipendenze dell'SDK sono state modificate in questa versione.

  • L'SDK ora richiede PHP 5.5+. Utilizziamo generatori liberamente all'interno del codice SDK.

  • Abbiamo aggiornato l'SDK per l'utilizzoGuzzle 6(o 5), che fornisce l'implementazione del client HTTP sottostante utilizzato dall'SDK per inviare le richieste alAWSServizi . La versione più recente di Guzzle offre una serie di miglioramenti, tra cui richieste asincrone, gestori HTTP commutabili, conformità PSR-7, prestazioni migliori e molto altro.

  • Il pacchetto PSR-7 di PHP-FIG (psr/http-message) definisce interfacce per rappresentare richieste HTTP, risposte HTTP, URL e flussi. Queste interfacce vengono nell'SDK e in Guzzle, che offre interoperabilità con altri pacchetti conformi a PSR-7.

  • L'implementazione PSR-7 di Guzzle (guzzlehttp/psr7) fornisce un'implementazione delle interfacce in PSR-7 e diverse utili classi e funzioni. Sia l'SDK che Guzzle 6 fanno molto affidamento su questo pacchetto.

  • L'implementazione di Promesse/A+ di Guzzle (guzzlehttp/promises) viene utilizzata nell'SDK e in Guzzle per fornire interfacce per la gestione delle richieste e delle coroutine asincrone. Mentre il gestore HTTP multi-cURL di Guzzle in ultima analisi implementa il modello di I/O senza blocchi che consente le richieste asincrone, questo pacchetto offre la possibilità di programmare all'interno di tale paradigma. Consulta .Promesse inAWS SDK for PHPVersione 3per ulteriori dettagli.

  • L'implementazione PHP di JMESPath (mtdowling/jmespath.php) viene utilizzata nell'SDK per fornire l'abilità di query sui dati dei metodi Aws\Result::search() e Aws\ResultPaginator::search(). Consulta .Espressioni JMESPath inAWS SDK for PHPVersione 3per ulteriori dettagli.

Le opzioni di regione e versione (Region e Version) sono ora obbligatorie

Quando si creano istanze per un client per qualsiasi servizio, specificare le opzioni 'region' e 'version'. Nella versione 2 dell'AWS SDK for PHP, 'version' era completamente facoltativa e 'region'era talvolta facoltativa. Nella versione 3, entrambe le opzioni sono sempre obbligatorie. Essere espliciti su entrambe le opzioni consente di rimanere nella versione dell'API eAWSRegione contro cui stai codificando. Quando vengono create nuove versioni API o nuoveAWSLe regioni diventano disponibili, sarai isolato dalle modifiche potenzialmente di rottura fino a quando non sei pronto ad aggiornare in modo esplicito la configurazione.

Nota

Se non sei interessato alla versione API che usi, puoi semplicemente impostare l'opzione 'version' su 'latest'. Tuttavia, ti consigliamo di impostare i numeri di versione dell'API in modo esplicito per il codice di produzione.

Non tutti i servizi sono disponibili in tuttiAWSRegioni. Un elenco delle regioni disponibili è presente nel riferimento Regioni ed endpoint.

Per i servizi che sono disponibili solo tramite un singolo endpoint globale (ad es. Amazon Route 53,AWS Identity and Access Managemente Amazon CloudFront), crea un'istanza dei client con la regione configurata impostata suus-east-1.

Importante

L'SDK include anche client multi-regione, che possono inviare richieste a diversiAWSRegioni basate su un parametro (@region) fornito come parametro di comando. La regione utilizzata per impostazione predefinita da questi client è specificata con l'opzione region fornita al costruttore del client.

L'istanza del client usa il costruttore

Nella versione 3 dell'AWS SDK for PHP, è stato modificato il modo in cui si creano le istanze di un client. Anziché utilizzare i metodi factory nella versione 2, è possibile creare con facilità un'istanza di un client utilizzando la parola chiave 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

La creazione dell'istanza di un client utilizzando il metodo factory() funziona ancora. Tuttavia, questa azione è considerata obsoleta.

La configurazione del client è stata modificata

Le opzioni di configurazione del client nella versione 3 dell'AWS SDK for PHP sono state leggermente modificate rispetto alla versione 2. Consulta ilConfigurazione per l'AWS SDK for PHPVersione 3per una descrizione di tutte le opzioni supportate.

Importante

Nella versione 3 'key' e 'secret' non sono più opzioni valide al livello radice, ma è possibile passarle come parte dell'opzione 'credentials'. Uno dei motivi che ci hanno portato a fare questo è scoraggiare gli sviluppatori dal codificare in modo rigido i loroAWScredenziali nei loro progetti.

L'oggetto Sdk

Nella versione 3 dell'AWS SDK for PHP viene introdotto l'oggetto Aws\Sdk come sostituto di Aws\Common\Aws. L'oggetto Sdk agisce come un client factory e viene utilizzato per gestire le opzioni di configurazione condivise da più client.

Anche se la classe Aws nella versione 2 dell'SDK funzionava come localizzatore di servizio (restituiva sempre la stessa istanza di un client), la classe Sdk nella versione 3 restituisce una nuova istanza di un client ogni volta che viene utilizzata.

L'oggetto Sdk, inoltre, non supporta lo stesso formato di file di configurazione dalla versione 2 dell'SDK. Questo formato di configurazione era specifico per Guzzle 3 ed è ora obsoleto. La configurazione può essere eseguita più semplicemente con gli array di base ed è documentata in Utilizzo della classe Sdk.

Alcuni risultati delle API sono cambiati

Per offrire coerenza nel modo in cui l'SDK analizza il risultato di un'operazione API, Amazon ElastiCache, Amazon RDS e Amazon Redshift dispongono di un ulteriore elemento di wrapping su alcune risposte API.

Ad esempio, chiamando Amazon RDSDescribeEngineDefaultParametersil risultato nella versione 3 ora include un elemento di wrapping «EngineDefaults». Nella versione 2, questo elemento non era 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'];

Le seguenti operazioni sono interessate e ora contengono un elemento di wrapping nell'output del risultato (fornito di seguito tra parentesi):

  • 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)

Classi di enumerazione che sono state rimosse

Abbiamo rimosso le classi Enum (ad esempio, Aws\S3\Enum\CannedAcl) presenti nella versione 2 dell'AWS SDK for PHP. Le enumerazioni erano classi concrete all'interno dell'API pubblica dell'SDK che conteneva costanti che rappresentano gruppi di validità i valori dei parametri. Poiché queste enumerazioni sono specifiche per le versioni dell'API, possono cambiare nel tempo, possono entrare in conflitto con parole riservate PHP e non sono risultate molto utili, le abbiamo rimosse nella versione 3. Questo supporta la natura agnostica della versione API basato su dati della versione 3.

Invece di utilizzare i valori di oggetti Enum, utilizza i valori letterali direttamente (ad esempio CannedAcl::PUBLIC_READ'public-read').

Classi di eccezioni granulari sono state rimosse

Abbiamo rimosso le classi di eccezione granulari esistenti negli spazi dei nomi di ciascun servizio (ad esempio, Aws\Rds\Exception\{SpecificError}Exception) per motivi molto simili a quelli per cui abbiamo rimosso le enumerazioni. Le eccezioni generate da un servizio o operazione dipendono da quale versione dell'API viene utilizzata (possono variare da una versione all'altra). Inoltre, l'elenco completo delle eccezioni che possono essere generate da una determinata operazione non è disponibile, il che rendeva le classi di eccezione granulari della versione 2 incomplete.

Gestire gli errori ricevendo la classe di eccezione root per ciascun servizio (ad esempio, Aws\Rds\Exception\RdsException). È possibile utilizzare il metodo di eccezione getAwsErrorCode() per verificare la presenza di codici di errore specifici. Questo è funzionalmente equivalente a catturare diverse classi di eccezioni, ma prevede che funzionino senza aggiungere dimensioni all'SDK.

Le classi Facade statiche sono state rimosse

Nella versione 2 dell'AWS SDK for PHP, era presente una caratteristica oscura ispirata da Laravel che consentiva di chiamare enableFacades() sulla classe Aws per abilitare l'accesso ai vari servizi client. Questa caratteristica va contro le best practice di PHP e abbiamo smesso di documentarla più di un anno fa. Nella versione 3, questa caratteristica è stata completamente rimossa. Recuperare gli oggetti client dall'oggetto Aws\Sdk e utilizzarli come istanze di oggetti, non classi statiche.

Gli impaginatori sostituiscono gli iteratori

La versione 2 dell'AWS SDK for PHP aveva una funzionalità denominata *iteratori*. Questi oggetti sono stati utilizzati per reiterare i risultati impaginati in modo eccessivo. Un reclamo che abbiamo ricevuto su questi oggetti era che non erano sufficientemente flessibili, perché l'iteratore emetteva solo valori specifici da ciascun risultato. Se avevi bisogno di altri valori dai risultati, potevi recuperarli solo tramite listener di eventi.

Nella versione 3, gli iteratori sono stati sostituiti con Impaginatori. Lo scopo è simile, ma gli impaginatori sono più flessibili. Questo è dovuto al fatto che restituiscono gli oggetti di risultato anziché i valori da una risposta.

I seguenti esempi mostrano come gli impaginatori differiscono dagli iteratori, dimostrando come recuperare i risultati impaginati per l'operazione S3 ListObjects sia nella versione 2 che nella versione 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"; } }

Gli oggetti impaginatore dispongono di un metodo search() che consente di utilizzare espressioni JMESPath per estrarre i dati in modo più semplice dal set di risultati.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results->search('Contents[].Key') as $key) { echo $key . "\n"; }
Nota

Il metodo getIterator() è ancora supportato per consentire una transizione agevole alla versione 3, ma ti consigliamo di migrare il codice per l'utilizzo degli impaginatori.

Molte astrazioni di livello più elevato sono cambiate

In generale, molte delle astrazioni di livello più elevato (oggetti helper specifici per il servizio, tranne i client) sono state migliorate o aggiornate. Alcune sono state rimosse.

  • Aggiornato:
  • Rimosso>
    • Amazon DynamoDBItem,Attribute, eItemIteratorclassi - Queste sono state precedentemente deprecate inVersione 2.7.0.

    • Validatore messaggi Amazon SNS - Questo è oraun progetto separato e leggeroche non richiede SDK come dipendenza. Questo progetto è tuttavia incluso nelle distribuzioni Phar e ZIP dell'SDK. Puoi trovare una guida alle operazioni di basesulAWSBlog sullo sviluppo PHP.

    • Amazon S3AcpBuildere gli oggetti correlati sono stati rimossi.

Confronto tra gli esempi di codice da parte di entrambe le versioni dell'SDK

I seguenti esempi mostrano alcuni dei modi in cui l'utilizzo della versione 3 dell'AWS SDK for PHP potrebbe differire dalla versione 2.

Esempio: Operazione Amazon S3 ListObjects

Dalla versione 2 dell'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"; }

Dalla versione 3 dell'SDK

Differenze principali:

  • Usa new invece di factory() per creare un'istanza del client.

  • Le opzioni 'version' e 'region' sono obbligatorie durante la creazione dell'istanza.

<?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"; }

Esempio: Istanza di un client con configurazione globale

Dalla versione 2 dell'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.

Dalla versione 3 dell'SDK

Differenze principali:

  • Utilizza la classe Aws\Sdk anziché Aws\Common\Aws.

  • Non c'è un file di configurazione. Utilizza un array per la configurazione.

  • L'opzione 'version' è obbligatoria durante la creazione dell'istanza.

  • Utilizza i metodi create<Service>() anziché get('<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.