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à.
# Migrazione dalla versione 2 di AWS SDK per PHP
Questo argomento mostra come migrare il codice per utilizzare la versione 3 dell' AWS SDK per 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 di AWS SDK per PHP rappresenta uno sforzo significativo per migliorare le funzionalità dell'SDK, incorporare oltre due anni di feedback dei clienti, aggiornare le nostre dipendenze, migliorare le prestazioni e adottare gli standard PHP più recenti.
## Cosa c'è di nuovo nella versione 3?
La versione 3 AWS SDK per PHP segue gli standard [PSR-4 e PSR-7 e seguirà lo standard](http://php-fig.org) in futuro [SemVer](http://semver.org/).
Altre nuove funzionalità includono:
+ Sistema middleware per la personalizzazione del comportamento del client di servizio
+ *Impaginatori* flessibili per navigare attraverso i risultati impaginati
+ Possibilità di interrogare i dati dagli *oggetti risultato* e *impaginatore* con *JMESPath*
+ Debug semplice tramite l'opzione di configurazione `'debug'`
### Livello HTTP disassociato
+ [Guzzle 6](http://guzzlephp.org) 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 c'è di diverso dalla versione 2?
### Le dipendenze del progetto vengono aggiornate
Le dipendenze dell'SDK sono state modificate in questa versione.
+ L'SDK ora richiede PHP 8.1\$1. Utilizziamo [generatori](http://php.net/manual/en/language.generators.overview.php) liberamente all'interno del codice SDK.
+ Abbiamo aggiornato l'SDK per utilizzare [Guzzle 6](http://guzzlephp.org) (o 5), che fornisce l'implementazione del client HTTP sottostante utilizzata dall'SDK per inviare richieste ai servizi. AWS 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 le interfacce per la rappresentazione di richieste HTTP, risposte HTTP e flussi. URLs 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\$1](https://promisesaplus.com) di Guzzle (`guzzlehttp/promises`) viene utilizzata nell'SDK e in Guzzle per fornire interfacce per la gestione delle richieste e delle coroutine asincrone. Sebbene il gestore HTTP Multi-CURL di Guzzle implementi in ultima analisi il I/O modello non bloccante che consente le richieste asincrone, questo pacchetto offre la possibilità di programmare all'interno di quel paradigma. [Vedi Promises nella versione 3 per maggiori dettagli. AWS SDK per PHP](guide_promises.md)
+ L'implementazione PHP di [JMESPath](http://jmespath.org/)(`mtdowling/jmespath.php`) viene utilizzata nell'SDK per fornire la capacità di interrogazione dei dati dei metodi and. `Aws\Result::search()` `Aws\ResultPaginator::search()` Vedi [JMESPath Expressions nella AWS SDK per PHP versione 3 per maggiori dettagli](guide_jmespath.md).
### Le opzioni relative alla regione e alla versione sono ora obbligatorie
Quando si creano istanze per un client per qualsiasi servizio, specificare le opzioni `'region'` e `'version'`. Nella versione 2 di AWS SDK per PHP, `'version'` era completamente opzionale e talvolta `'region'` era opzionale. Nella versione 3, entrambe le opzioni sono sempre obbligatorie. Essere espliciti su entrambe queste opzioni ti consente di concentrarti sulla versione dell'API e sulla AWS regione in cui stai codificando. Quando vengono create nuove versioni dell'API o diventano disponibili nuove AWS regioni, sarai isolato da modifiche potenzialmente irreversibili finché non sarai pronto ad aggiornare esplicitamente la tua 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 tutte le AWS regioni. Un elenco delle regioni disponibili è presente nel riferimento [Regioni ed endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html).
Per i servizi disponibili solo tramite un singolo endpoint globale (ad esempio Amazon Route 53 e Amazon CloudFront) AWS Identity and Access Management, crea un'istanza dei client con la regione configurata impostata su. `us-east-1`
**Importante**
L'SDK include anche client multiregionali, che possono inviare richieste a diverse AWS regioni in base a 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'istanziazione del client utilizza il costruttore
Nella versione 3 di AWS SDK per PHP, il modo in cui si crea un'istanza di un client è cambiato. 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 è cambiata
Le opzioni di configurazione del client nella versione 3 di AWS SDK per PHP sono leggermente cambiate rispetto alla versione 2. Vedi la pagina [Configurazione per la AWS SDK per PHP versione 3](guide_configuration.md) per 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 per cui l'abbiamo fatto è stato quello di scoraggiare gli sviluppatori dall'inserire le proprie AWS credenziali nei loro progetti.
#### L'oggetto Sdk
La versione 3 di AWS SDK per PHP introduce l'oggetto in sostituzione di`Aws\Sdk`. `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](configuring-service-clients-code.md#sdk-class).
### Alcuni risultati dell'API sono stati modificati
Per garantire la coerenza nel modo in cui l'SDK analizza il risultato di un'operazione API, Amazon, ElastiCache Amazon RDS e Amazon Redshift ora dispongono di un elemento di wrapping aggiuntivo su alcune risposte API.
Ad esempio, la chiamata al [DescribeEngineDefaultParameters](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeEngineDefaultParameters.html)risultato di Amazon RDS nella versione 3 ora include un elemento 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 (Istantanea)
+ CreateCacheCluster (CacheCluster)
+ CreateCacheParameterGroup (CacheParameterGroup)
+ CreateCacheSecurityGroup (CacheSecurityGroup)
+ CreateCacheSubnetGroup (CacheSubnetGroup)
+ CreateReplicationGroup (ReplicationGroup)
+ CreateSnapshot (Istantanea)
+ DeleteCacheCluster (CacheCluster)
+ DeleteReplicationGroup (ReplicationGroup)
+ DeleteSnapshot (Istantanea)
+ DescribeEngineDefaultParameters (EngineDefaults)
+ ModifyCacheCluster (CacheCluster)
+ ModifyCacheSubnetGroup (CacheSubnetGroup)
+ ModifyReplicationGroup (ReplicationGroup)
+ PurchaseReservedCacheNodesOffering (ReservedCacheNode)
+ RebootCacheCluster (CacheCluster)
+ RevokeCacheSecurityGroupIngress (CacheSecurityGroup)
+ Amazon RDS
+ AddSourceIdentifierToSubscription (EventSubscription)
+ Autorizza DBSecurity GroupIngress (gruppo) DBSecurity
+ Copia DBParameter gruppo (DBParametergruppo)
+ Copia DBSnapshot (DBSnapshot)
+ CopyOptionGroup (OptionGroup)
+ Crea DBInstance (DBInstance)
+ Crea DBInstance ReadReplica (DBInstance)
+ Crea DBParameter gruppo (DBParametergruppo)
+ Crea DBSecurity gruppo (DBSecuritygruppo)
+ Crea DBSnapshot (DBSnapshot)
+ Crea DBSubnet gruppo (DBSubnetgruppo)
+ CreateEventSubscription (EventSubscription)
+ CreateOptionGroup (OptionGroup)
+ Elimina DBInstance (DBInstance)
+ Elimina DBSnapshot (DBSnapshot)
+ DeleteEventSubscription (EventSubscription)
+ DescribeEngineDefaultParameters (EngineDefaults)
+ Modifica DBInstance (DBInstance)
+ Modifica DBSubnet gruppo (DBSubnetgruppo)
+ ModifyEventSubscription (EventSubscription)
+ ModifyOptionGroup (OptionGroup)
+ PromoteReadReplica (DBInstance)
+ PurchaseReservedDBInstancesOfferta (riservataDBInstance)
+ Riavvio DBInstance () DBInstance
+ RemoveSourceIdentifierFromSubscription (EventSubscription)
+ Ripristina DBInstance da DBSnapshot () DBInstance
+ Ripristina DBInstance ToPointInTime (DBInstance)
+ Revoca DBSecurity GroupIngress (gruppo) DBSecurity
+ Amazon Redshift
+ AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)
+ AuthorizeSnapshotAccess (Istantanea)
+ CopyClusterSnapshot (Istantanea)
+ CreateCluster (Cluster)
+ CreateClusterParameterGroup (ClusterParameterGroup)
+ CreateClusterSecurityGroup (ClusterSecurityGroup)
+ CreateClusterSnapshot (Istantanea)
+ CreateClusterSubnetGroup (ClusterSubnetGroup)
+ CreateEventSubscription (EventSubscription)
+ CreateHsmClientCertificate (HsmClientCertificate)
+ CreateHsmConfiguration (HsmConfiguration)
+ DeleteCluster (Cluster)
+ DeleteClusterSnapshot (Istantanea)
+ DescribeDefaultClusterParameters (DefaultClusterParameters)
+ DisableSnapshotCopy (Cluster)
+ EnableSnapshotCopy (Grappolo)
+ ModifyCluster (Grappolo)
+ ModifyClusterSubnetGroup (ClusterSubnetGroup)
+ ModifyEventSubscription (EventSubscription)
+ ModifySnapshotCopyRetentionPeriod (Grappolo)
+ PurchaseReservedNodeOffering (ReservedNode)
+ RebootCluster (Grappolo)
+ RestoreFromClusterSnapshot (Grappolo)
+ RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)
+ RevokeSnapshotAccess (Istantanea)
+ RotateEncryptionKey (Cluster)
### Le classi Enum sono state rimosse
Abbiamo rimosso le classi `Enum` (ad esempio, `Aws\S3\Enum\CannedAcl`) presenti nella versione 2 dell' AWS SDK per 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'`).
### Le 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 di facciata statiche sono state rimosse
Nella versione 2 di AWS SDK per PHP, c'era una funzionalità oscura ispirata a Laravel che permetteva di `enableFacades()` richiamare la `Aws` classe per abilitare l'accesso statico ai vari client di servizio. 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 di AWS SDK per PHP aveva una funzionalità denominata \$1 iteratori\$1. 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](guide_paginators.md). 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' => '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";
}
}
```
Gli oggetti Paginator dispongono di un `search()` metodo che consente di utilizzare [JMESPath](guide_jmespath.md)le espressioni per estrarre più facilmente i dati dal set di risultati.
```
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-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 superiore 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:**
+ Il modo in cui usi il [caricamento in più parti di Amazon S3](s3-multipart-upload.md) è cambiato. Amazon Glacier Multipart Upload è stato modificato in modo simile.
+ Il modo di creare [Amazon S3 prefirmato URLs](s3-presigned-url.md) è cambiato.
+ Lo spazio dei nomi `Aws\S3\Sync` è stato sostituito dalla classe `Aws\S3\Transfer`. I metodi `S3Client::uploadDirectory()` e `S3Client::downloadBucket()` sono ancora disponibili, ma hanno opzioni diverse. Consulta la documentazione per [Amazon S3 Transfer Manager con AWS SDK per PHP versione](s3-transfer.md) 3.
+ `Aws\S3\Model\ClearBucket` e `Aws\S3\Model\DeleteObjectsBatch` sono stati sostituiti da `Aws\S3\BatchDelete` e `S3Client::deleteMatchingObjects()`.
+ Le opzioni e i comportamenti per [Using the DynamoDB Session Handler AWS SDK per PHP con](service_dynamodb-session-handler.md) la versione 3 sono leggermente cambiati.
+ Lo spazio dei nomi `Aws\DynamoDb\Model\BatchRequest` è stato sostituito da `Aws\DynamoDb\WriteRequestBatch`. Consulta la documentazione per [DynamoDB. WriteRequestBatch](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.DynamoDb.WriteRequestBatch.html)
+ `Aws\Ses\SesClient` gestisce ora la codifica base64 di `RawMessage` quando si usa l'operazione `SendRawEmail`.
+
**Rimosso>**
+ [Amazon `Item` DynamoDB `Attribute``ItemIterator` e classi: erano precedentemente obsolete nella versione 2.7.0.](https://github.com/aws/aws-sdk-php/blob/3.0.0/CHANGELOG.md#270===2014-10-08)
+ Amazon SNS Message Validator: ora si tratta di [un progetto separato e leggero](https://github.com/aws/aws-php-sns-message-validator) che non richiede l'SDK come dipendenza. Questo progetto è tuttavia incluso nelle distribuzioni Phar e ZIP dell'SDK. Puoi trovare una guida introduttiva [sul](https://aws.amazon.com/blogs/developer/receiving-amazon-sns-messages-in-php/) blog PHP Development. AWS
+ Amazon S3 `AcpBuilder` e gli oggetti correlati sono stati rimossi.
## Confronto di esempi di codice di entrambe le versioni dell'SDK
Gli esempi seguenti mostrano alcuni dei modi in cui l'utilizzo della versione 3 di AWS SDK per PHP differisce dalla versione 2.
### Esempio: funzionamento di Amazon S3 `ListObjects`
#### Dalla versione 2 dell'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";
}
```
#### 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.
```
'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";
}
```
### Esempio: creazione di un'istanza di un client con configurazione globale
#### Dalla versione 2 dell'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.
```
#### 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()` anziché `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.
```