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à.
# Configurare l'SDK
Nella AWS SDK per Go V2, è possibile configurare impostazioni comuni per i client di servizio, come il logger, il livello di registro e la configurazione Retry. La maggior parte delle impostazioni è facoltativa. Tuttavia, per ogni client del servizio, è necessario specificare una AWS regione e le proprie credenziali. L'SDK utilizza questi valori per inviare richieste alla regione corretta e firmare le richieste con le credenziali corrette. È possibile specificare questi valori in modo programmatico nel codice o tramite l'ambiente di esecuzione.
## Caricamento di file di AWS configurazione condivisi
Esistono diversi modi per inizializzare un client API di servizio, ma il seguente è lo schema più comune consigliato agli utenti.
Per configurare l'SDK per l'utilizzo dei file di configurazione AWS condivisi, utilizzate il codice seguente:
```
import (
"context"
"log"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Fatalf("failed to load configuration, %v", err)
}
```
`config.LoadDefaultConfig(context.TODO())`costruirà un [AWS.config utilizzando le fonti di configurazione condivise](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config). AWS Ciò include la configurazione di un provider di credenziali, la configurazione della AWS regione e il caricamento della configurazione specifica del servizio. I client di servizio possono essere costruiti utilizzando il file loaded`aws.Config`, che fornisce uno schema coerente per la creazione dei client.
Per ulteriori informazioni sui file di configurazione AWS condivisi, vedere [Configuration](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) nella AWS SDKs and Tools Reference Guide.
## Specificare la regione AWS
Quando si specifica la regione, si specifica dove inviare le richieste, ad esempio `us-west-2` o`us-east-2`. Per un elenco delle regioni per ogni servizio, consulta [Endpoint e quote del servizio](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in. Riferimenti generali di Amazon Web Services
L'SDK non dispone di una regione predefinita. Per specificare una regione:
+ Imposta la variabile di `AWS_REGION` ambiente sulla regione predefinita.
+ Imposta la regione in modo esplicito utilizzando [config. WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127)come argomento per il `config.LoadDefaultConfig` caricamento della configurazione.
RECENSIONE: se imposti una regione utilizzando tutte queste tecniche, l'SDK utilizza la regione specificata in modo esplicito.
### Configura la regione con una variabile d'ambiente
#### Linux, macOS o Unix
```
export AWS_REGION=us-west-2
```
#### Windows
```
set AWS_REGION=us-west-2
```
### Specificare la regione a livello di codice
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## Specifica delle credenziali
AWS SDK per Go Richiede le credenziali (una chiave di accesso e una chiave di accesso segreta) a cui firmare le richieste. AWSÈ possibile specificare le credenziali in diverse posizioni, a seconda del caso d'uso specifico. Per informazioni su come ottenere le credenziali, vedere. [Inizia con AWS SDK per Go](getting-started.md)
Quando inizializzate un'`aws.Config`istanza utilizzando`config.LoadDefaultConfig`, l'SDK utilizza la catena di credenziali predefinita per trovare le credenziali. AWS Questa catena di credenziali predefinita cerca le credenziali nel seguente ordine:
1. Variabili di ambiente.
1. Credenziali statiche (,,) `AWS_ACCESS_KEY_ID` `AWS_SECRET_ACCESS_KEY` `AWS_SESSION_TOKEN`
1. Token di identità Web () `AWS_WEB_IDENTITY_TOKEN_FILE`
1. File di configurazione condivisi.
1. L'SDK utilizza per impostazione predefinita `credentials` il file `.aws` nella cartella principale del computer.
1. L'SDK utilizza come impostazione predefinita `config` il file `.aws` nella cartella principale del computer.
1. Se la tua applicazione utilizza una definizione di attività Amazon ECS o un'operazione RunTask API, ruolo IAM per le attività.
1. Se la tua applicazione è in esecuzione su un'istanza Amazon EC2, ruolo IAM per Amazon EC2.
L'SDK rileva e utilizza automaticamente i provider integrati, senza richiedere configurazioni manuali. Ad esempio, se utilizzi i ruoli IAM per le istanze Amazon EC2, le tue applicazioni utilizzano automaticamente le credenziali dell'istanza. Non è necessario configurare manualmente le credenziali nell'applicazione.
Come procedura ottimale, si AWS consiglia di specificare le credenziali nell'ordine seguente:
1. Usa i ruoli IAM per le attività se la tua applicazione utilizza una definizione di attività Amazon ECS o un'operazione RunTask API.
1. Usa i ruoli IAM per Amazon EC2 (se la tua applicazione è in esecuzione su un'istanza Amazon EC2).
I ruoli IAM forniscono alle applicazioni sull'istanza credenziali di sicurezza temporanee per effettuare chiamate. AWS I ruoli IAM forniscono un modo semplice per distribuire e gestire le credenziali su più istanze Amazon EC2.
1. Usa credenziali o file di configurazione condivisi.
Le credenziali e i file di configurazione sono condivisi tra altri e. AWS SDKs AWS CLI Come best practice di sicurezza, consigliamo di utilizzare il file di credenziali per impostare valori sensibili come la chiave di accesso IDs e le chiavi segrete. Di seguito sono riportati i [requisiti di formattazione](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) per ciascuno di questi file.
1. Usa le variabili di ambiente.
L'impostazione delle variabili di ambiente è utile se stai eseguendo lavori di sviluppo su una macchina diversa da un'istanza Amazon EC2.
### Ruoli IAM per i processi
Se la tua applicazione utilizza una definizione o un'`RunTask`operazione di Amazon ECS, utilizza [IAM Roles for Tasks per](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) specificare un ruolo IAM che può essere utilizzato dai contenitori in un'attività.
### Ruoli IAM per istanze Amazon EC2
Se esegui l'applicazione su un'istanza Amazon EC2, utilizza il [ruolo IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) dell'istanza per ottenere credenziali di sicurezza temporanee a cui effettuare chiamate. AWS
Se hai configurato l'istanza per utilizzare i ruoli IAM, l'SDK utilizza automaticamente queste credenziali per l'applicazione. Non è necessario specificare manualmente queste credenziali.
### Credenziali e configurazione condivise
Le credenziali condivise e i file di configurazione possono essere utilizzati per condividere configurazioni comuni tra altri strumenti AWS SDKs . Se utilizzi credenziali differenti per diversi strumenti o applicazioni, puoi utilizzare *i profili* per configurare più chiavi di accesso nello stesso file di configurazione.
È possibile fornire più posizioni di credenziali o file di configurazione utilizzando`config.LoadOptions`, per impostazione predefinita, l'SDK carica i file archiviati nelle posizioni predefinite menzionate in. [Specifica delle credenziali](#specifying-credentials)
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg , err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedCredentialsFiles(
[]string{"test/credentials", "data/credentials"},
),
config.WithSharedConfigFiles(
[]string{"test/config", "data/config"},
)
)
```
Quando si utilizzano credenziali e file di configurazione condivisi, se vengono specificati profili duplicati, questi vengono uniti per risolvere un profilo. In caso di conflitto di fusione,
1. Se vengono specificati profili duplicati all'interno dello stesso credentials/config file, le proprietà del profilo specificate in quest'ultimo profilo hanno la precedenza.
1. Se vengono specificati profili duplicati su più file di credenziali o su più file di configurazione, le proprietà del profilo vengono risolte secondo l'ordine di immissione del file in. `config.LoadOptions` Le proprietà del profilo in questi ultimi file hanno la precedenza.
1. Se un profilo esiste sia nel file delle credenziali che nel file di configurazione, le proprietà del file delle credenziali hanno la precedenza.
Se necessario, è possibile attivare `config.LoadOptions` e registrare i `LogConfigurationWarnings` passaggi di risoluzione del profilo.
#### Creazione del file delle credenziali
Se non disponi di un file di credenziali condiviso (`.aws/credentials`), puoi utilizzare qualsiasi editor di testo per crearne uno nella tua home directory. Aggiungi il seguente contenuto al file delle credenziali, sostituendo ** e ** con le tue credenziali.
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
L'`[default]`intestazione definisce le credenziali per il profilo predefinito, che verrà utilizzato dall'SDK a meno che non venga configurato per utilizzare un altro profilo.
Puoi anche utilizzare credenziali di sicurezza temporanee aggiungendo i token di sessione al tuo profilo, come mostrato nell'esempio seguente:
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
Il nome di sezione per un profilo non predefinito all'interno di un file di credenziali non deve iniziare con la parola. `profile` Per saperne di più, consulta la Guida [AWS SDKs di riferimento agli strumenti.](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds)
#### Creazione del file Config
Se non disponi di un file di credenziali condiviso (`.aws/config`), puoi utilizzare qualsiasi editor di testo per crearne uno nella tua home directory. Aggiungi il seguente contenuto al tuo file di configurazione, sostituendolo ** con la regione desiderata.
```
[default]
region =
```
L'`[default]`intestazione definisce la configurazione per il profilo predefinito, che verrà utilizzato dall'SDK a meno che non venga configurato per utilizzare un altro profilo.
È possibile utilizzare profili denominati come illustrato nell'esempio seguente:
```
[profile named-profile]
region =
```
Il nome di sezione per un profilo non predefinito all'interno di un file di configurazione deve sempre iniziare con la parola`profile`, seguita dal nome del profilo desiderato. Puoi leggere ulteriori informazioni nella [AWS SDKs and Tools Reference Guide.](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config)
#### Specificazione dei profili
È possibile includere più chiavi di accesso nello stesso file di configurazione associando ogni set di chiavi di accesso a un profilo. Ad esempio, nel file delle credenziali, puoi dichiarare più profili, come segue.
```
[default]
aws_access_key_id =
aws_secret_access_key =
[test-account]
aws_access_key_id =
aws_secret_access_key =
[prod-account]
; work profile
aws_access_key_id =
aws_secret_access_key =
```
Per impostazione predefinita, l'SDK verifica la variabile di ambiente `AWS_PROFILE` per determinare quale profilo utilizzare. Se non è impostata alcuna `AWS_PROFILE` variabile, l'SDK utilizza il profilo. `default`
A volte, potresti voler usare un profilo diverso con la tua applicazione. Ad esempio, desideri utilizzare `test-account` le credenziali con la tua `myapp` applicazione. È possibile utilizzare questo profilo utilizzando il seguente comando:
```
$ AWS_PROFILE=test-account myapp
```
Puoi anche utilizzare istruisci l'SDK per selezionare un profilo chiamando `os.Setenv("AWS_PROFILE", "test-account")` prima della chiamata o passando un profilo esplicito come argomento`config.LoadDefaultConfig`, come mostrato nell'esempio seguente:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**Nota**
Se specificate credenziali nelle variabili di ambiente, l'SDK utilizza sempre tali credenziali, indipendentemente dal profilo specificato.
### Variabili di ambiente
Per impostazione predefinita, l'SDK rileva le AWS credenziali impostate nell'ambiente e le utilizza per firmare le richieste. AWS In questo modo non è necessario gestire le credenziali nelle applicazioni.
L'SDK cerca le credenziali nelle seguenti variabili di ambiente:
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (facoltativo)
Gli esempi seguenti mostrano come configurare le variabili di ambiente.
#### Linux, OS X o Unix
```
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
$ export AWS_SESSION_TOKEN=TOKEN
```
#### Windows
```
> set AWS_ACCESS_KEY_ID=YOUR_AKID
> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
> set AWS_SESSION_TOKEN=TOKEN
```
### Specificare le credenziali a livello di codice
`config.LoadDefaultConfig`[consente di fornire un aws esplicito. CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)durante il caricamento delle fonti di configurazione condivise. [Per passare un provider di credenziali esplicito durante il caricamento della configurazione condivisa, usa config. WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider). Ad esempio, se `customProvider` fa riferimento a un'istanza di `aws.CredentialProvider` implementazione, può essere passato durante il caricamento della configurazione in questo modo:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
Se fornite in modo esplicito le credenziali, come in questo esempio, l'SDK utilizza solo quelle credenziali.
**Nota**
Tutti i provider di credenziali passati o restituiti da `LoadDefaultConfig` vengono inseriti automaticamente in un file. [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache) Ciò consente la memorizzazione nella cache e la rotazione delle credenziali in modo sicuro dalla concorrenza. Se configuri `aws.Config` direttamente un provider in modo esplicito, devi anche inserire in modo esplicito questo tipo di provider utilizzando. [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache)
#### Credenziali statiche
[È possibile codificare le credenziali nell'applicazione utilizzando le credenziali. NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider)fornitore di credenziali per impostare in modo esplicito le chiavi di accesso da utilizzare. Esempio:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**avvertimento**
Non incorporare credenziali all'interno di un'applicazione. Utilizzate questo metodo solo per scopi di test.
#### Credenziali Single Sign-on
L'SDK fornisce un provider di credenziali per il recupero di credenziali temporanee utilizzando. AWS AWS IAM Identity Center Utilizzando AWS CLI, ci si autentica con il portale di accesso e si autorizza l' AWS accesso alle credenziali temporanee. AWS Quindi configuri l'applicazione per caricare il profilo Single Sign-On (SSO) e l'SDK utilizza le tue credenziali SSO per recuperare le credenziali temporanee che verranno rinnovate automaticamente se scadute. AWS Se le tue credenziali SSO scadono, devi rinnovarle esplicitamente accedendo nuovamente al tuo account IAM Identity Center utilizzando il. AWS CLI
Ad esempio, puoi creare un profilo`dev-profile`, autenticarlo e autorizzarlo utilizzando e configurare l'applicazione come illustrato di seguito AWS CLI.
1. Per prima cosa, crea e `profile` `sso-session`
```
[profile dev-profile]
sso_session = dev-session
sso_account_id = 012345678901
sso_role_name = Developer
region = us-east-1
[sso-session dev-session]
sso_region = us-west-2
sso_start_url = https://company-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```
1. Effettua il login utilizzando AWS CLI per autenticare e autorizzare il profilo SSO.
```
$ aws --profile dev-profile sso login
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.us-west-2.amazonaws.com/
Then enter the code:
ABCD-EFGH
Successully logged into Start URL: https://company-sso-portal.awsapps.com/start
```
1. Quindi configura l'applicazione per utilizzare il profilo SSO.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Per ulteriori informazioni sulla configurazione dei profili SSO e sull'autenticazione tramite, AWS CLI consulta la sezione [Configurazione dell'uso nella Guida AWS CLI per l'](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)utente. AWS IAM Identity Center AWS CLI [Per ulteriori informazioni sulla costruzione programmatica del provider di credenziali SSO, consulta la documentazione di riferimento dell'API ssocreds.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds)
#### Credenziali di accesso
È possibile utilizzare le credenziali di accesso esistenti AWS della Console di gestione per l'accesso programmatico ai servizi. AWS Dopo un flusso di autenticazione basato su browser, AWS genera credenziali temporanee che funzionano con strumenti di sviluppo locali come la CLI AWS e. AWS Strumenti per PowerShell AWS SDKs Questa funzionalità semplifica il processo di configurazione e gestione delle credenziali AWS CLI, soprattutto se si preferisce l'autenticazione interattiva alla gestione delle chiavi di accesso a lungo termine.
1. Avvia il flusso di accesso utilizzando la AWS CLI e segui le istruzioni del browser. In questo esempio, salviamo la sessione di accesso su un nuovo profilo**dev-profile**, ma questo è facoltativo.
```
$ aws --profile dev-profile login
```
1. (Facoltativo) Ispeziona il file di configurazione AWS condiviso per verificare che la sessione sia stata stabilita.
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. Quindi configura l'applicazione per utilizzare il profilo di accesso.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
// only necessary if login session is saved to a non-default profile
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Per ulteriori informazioni sulla configurazione dei profili di accesso e sull'autenticazione tramite la AWS CLI, consulta [Accesso per lo sviluppo AWS locale utilizzando le credenziali](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) della console.
#### Altri fornitori di credenziali
[L'SDK fornisce altri metodi per recuperare le credenziali nel modulo delle credenziali.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials) Ad esempio, è possibile recuperare credenziali di sicurezza temporanee o credenziali dall'archivio crittografato. AWS Security Token Service
Fornitori di **credenziali disponibili**:
+ [ec2rolecreds — Recupera le](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds) credenziali dai ruoli delle istanze Amazon EC2 tramite Amazon EC2 IMDS.
+ [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds) — Recupera le credenziali da un endpoint HTTP arbitrario.
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds) — Recupera le credenziali da un processo esterno che verrà richiamato dalla shell dell'ambiente host.
+ [stscreds — Recupera credenziali da](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) AWS STS
# Configurazione dell'autenticazione
AWS SDK per Go Fornisce la possibilità di configurare il servizio di comportamento di autenticazione. Nella maggior parte dei casi, la configurazione predefinita è sufficiente, ma la configurazione dell'autenticazione personalizzata consente di adottare comportamenti aggiuntivi, ad esempio l'utilizzo di funzionalità di servizio precedenti al rilascio.
## Definizioni
Questa sezione fornisce una descrizione di alto livello dei componenti di autenticazione di. AWS SDK per Go
### AuthScheme
An [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)è l'interfaccia che definisce il flusso di lavoro attraverso il quale l'SDK recupera l'identità del chiamante e la allega a una richiesta di operazione.
Uno schema di autenticazione utilizza i seguenti componenti, descritti in dettaglio più avanti:
+ Un ID univoco che identifica lo schema
+ Un risolutore di identità, che restituisce l'identità del chiamante utilizzata nel processo di firma (ad esempio le credenziali) AWS
+ Un firmatario, che esegue l'inserimento effettivo dell'identità del chiamante nella richiesta di trasporto dell'operazione (ad esempio l'intestazione HTTP) `Authorization`
Ogni opzione del client di servizio include un `AuthSchemes` campo, che per impostazione predefinita viene compilato con l'elenco degli schemi di autenticazione supportati da quel servizio.
### AuthSchemeResolver
Ogni opzione del client di servizio include un `AuthSchemeResolver` campo. Questa interfaccia, definita per servizio, è l'API chiamata dall'SDK per determinare le possibili opzioni di autenticazione per ogni operazione.
**Importante**
Il resolver dello schema di autenticazione NON impone quale schema di autenticazione viene utilizzato. [Restituisce un elenco di schemi che *possono* essere utilizzati («opzioni»), lo schema finale viene selezionato tramite un algoritmo fisso descritto qui.](#auth-scheme-resolution-workflow)
### Opzione
Restituita da una chiamata a`ResolverAuthSchemes`, un'[opzione](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) rappresenta una possibile opzione di autenticazione.
Un'opzione è composta da tre set di informazioni:
+ Un ID che rappresenta lo schema possibile
+ Un insieme opaco di proprietà da fornire al risolutore di identità dello schema
+ Un insieme opaco di proprietà da fornire al firmatario dello schema
#### Una nota sulle proprietà
Nel 99% dei casi d'uso, i chiamanti non devono preoccuparsi delle proprietà opache per la risoluzione e la firma delle identità. L'SDK estrarrà le proprietà necessarie per ogni schema e le passerà alle interfacce fortemente tipizzate esposte nell'SDK. [Ad esempio, il resolver di autenticazione predefinito per i servizi codifica l'opzione sigV4 in modo da avere proprietà del firmatario per il nome e l'area della firma, i cui valori vengono passati alla v4 configurata dal client. HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option)implementazione quando è selezionato SigV4.
### Identità
Un'[identità](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) è una rappresentazione astratta di chi è il chiamante dell'SDK.
Il tipo di identità più comune utilizzato nell'SDK è un insieme di. `aws.Credentials` Nella maggior parte dei casi d'uso, il chiamante non deve preoccuparsi di qualcosa `Identity` di astratto e può lavorare direttamente con i tipi concreti.
**Nota**
Per preservare la compatibilità con le versioni precedenti ed evitare confusione tra le API, il tipo di identità AWS specifico dell'SDK `aws.Credentials` non soddisfa direttamente l'interfaccia. `Identity` Questa mappatura viene gestita internamente.
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver)è l'interfaccia attraverso la quale viene recuperato un `Identity` file.
[Nell'SDK `IdentityResolver` esistono versioni concrete in forma fortemente tipizzata (ad esempio aws. CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)), l'SDK gestisce questa mappatura internamente.
Un chiamante dovrà solo implementare direttamente l'`IdentityResolver`interfaccia quando definisce uno schema di autenticazione esterno.
### Signer
[Signer](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) è l'interfaccia attraverso la quale una richiesta viene integrata con il chiamante recuperato. `Identity`
[Nell'SDK `Signer` esistono versioni concrete in forma fortemente tipizzata (ad esempio v4). HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner)), l'SDK gestisce questa mappatura internamente.
Un chiamante dovrà solo implementare direttamente l'`Signer`interfaccia quando definisce uno schema di autenticazione esterno.
### AuthResolverParameters
Ogni servizio accetta un set specifico di input che vengono passati alla sua funzione di risoluzione, definita in ogni pacchetto di servizi come. `AuthResolverParameters`
I parametri del resolver di base sono i seguenti:
| nome | tipo | description |
| --- | --- | --- |
| Operation | string | Il nome dell'operazione che viene richiamata. |
| Region | string | La AWS regione del cliente. Presente solo per i servizi che utilizzano SigV4 [A]. |
Se state implementando il vostro resolver, non dovreste mai aver bisogno di costruire una vostra istanza dei suoi parametri. L'SDK genererà questi valori per ogni richiesta e li passerà all'implementazione.
## Flusso di lavoro per la risoluzione dello schema di autenticazione
Quando si chiama un'operazione AWS di servizio tramite l'SDK, dopo la serializzazione della richiesta si verifica la seguente sequenza di azioni:
1. L'SDK richiama l'`AuthSchemeResolver.ResolveAuthSchemes()`API del client, fornendo i parametri di input necessari, per ottenere un elenco di possibili [opzioni](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) per l'operazione.
1. L'SDK esegue un'iterazione su tale elenco e seleziona il primo schema che soddisfa le seguenti condizioni.
+ Uno schema con ID corrispondente è presente nell'elenco del client `AuthSchemes`
+ Il risolutore di identità dello schema esiste (non è presente`nil`) nelle Opzioni del client (verificato tramite il `GetIdentityResolver` metodo dello schema, la mappatura ai tipi di risolutori di identità concreti descritti sopra viene gestita internamente) (1)
1. Supponendo che sia stato selezionato uno schema valido, l'SDK richiama la sua API per recuperare l'identità del chiamante. `GetIdentityResolver()` Ad esempio, lo schema di autenticazione SigV4 integrato verrà mappato internamente al provider del client. `Credentials`
1. L'SDK chiama i risolutori di identità (ad esempio per SigV4). `GetIdentity()` `aws.CredentialProvider.Retrieve()`
1. L'SDK chiama i resolver degli endpoint per trovare l'endpoint per la richiesta. `ResolveEndpoint()` L'endpoint può includere metadati aggiuntivi che influenzano il processo di firma (ad esempio un nome di firma univoco per S3 Object Lambda).
1. L'SDK chiama l'API dello schema di autenticazione per recuperare il firmatario e utilizza l'`Signer()`API per firmare la richiesta con l'identità del chiamante recuperata in precedenza. `SignRequest()`
(1) Se l'SDK rileva l'opzione anonima (ID`smithy.api#noAuth`) nell'elenco, viene selezionata automaticamente, poiché non esiste un risolutore di identità corrispondente.
## Supportato nativamente s `AuthScheme`
I seguenti schemi di autenticazione sono supportati nativamente da. AWS SDK per Go
| Nome | ID dello schema | Risolutore di identità | Signer | Note |
| --- | --- | --- | --- | --- |
| [SIG V4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | aws.auth\$1sigv4 | [leggi. CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Credentials) | [v4. HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#Signer) | L'impostazione predefinita corrente per la maggior parte delle operazioni AWS di servizio. |
| SigV4a | aws.auth\$1sigv4a | leggi. CredentialsProvider | N/A | L'utilizzo di SigV4a è limitato al momento, l'implementazione del firmatario è interna. Leggete questo [annuncio](https://github.com/aws/aws-sdk-go-v2/discussions/2812) per scoprire un nuovo modulo opt-in aws-http-authche illustra lo scopo generale della firma delle richieste HTTP. APIs |
| SIGV4Express | com.amazonaws.s3\$1sigv4express | [s3. ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4. HTTPSigner | Usato per [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). |
| Portatore HTTP | smithy.api\$1httpBearerAuth | [portatore di fucina. TokenProvider](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#TokenProvider) | [Smithy Bearer. Firmatario](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#Signer) | [Usato da codecatalyst.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst) |
| Anonimo | smithy.api\$1noAuth | N/A | n/a | Nessuna autenticazione: non è richiesta alcuna identità e la richiesta non è firmata o autenticata. |
### Configurazione dell'identità
In AWS SDK per Go, i componenti di identità di uno schema di autenticazione sono configurati nel client SDK. `Options` L'SDK raccoglierà e utilizzerà automaticamente i valori di questi componenti per lo schema selezionato quando viene chiamata un'operazione.
**Nota**
Per motivi di compatibilità con le versioni precedenti, l'SDK consente implicitamente l'uso dello schema di autenticazione anonimo se non sono configurati risolutori di identità. Ciò può essere ottenuto manualmente impostando tutti i resolver di identità su un client (il resolver di identità sigv4 può anche `Options` essere impostato su`nil`). `aws.AnonymousCredentials{}`
### Configurazione del firmatario
In AWS SDK per Go, i componenti firmatari di uno schema di autenticazione sono configurati nel client SDK. `Options` L'SDK raccoglierà e utilizzerà automaticamente i valori di questi componenti per lo schema selezionato quando viene chiamata un'operazione. Non è necessaria alcuna configurazione aggiuntiva.
#### Schema di autenticazione personalizzato
Per definire uno schema di autenticazione personalizzato e configurarlo per l'uso, il chiamante deve eseguire le seguenti operazioni:
1. Definire un'implementazione [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)
1. Registra lo schema nell'elenco dei client SDK `AuthSchemes`
1. Strumenta il client SDK `AuthSchemeResolver` a restituire un'autenticazione `Option` con l'ID dello schema, ove applicabile
**avvertimento**
I seguenti servizi hanno un comportamento di autenticazione unico o personalizzato. Ti consigliamo di delegare all'implementazione predefinita e di eseguire il wrap di conseguenza se hai bisogno di un comportamento di autenticazione personalizzato:
| Servizio | Note |
| --- | --- |
| S3 | Uso condizionale di SigV4a e SigV4Express a seconda dell'input dell'operazione. |
| EventBridge | Uso condizionale di SigV4A in base all'input dell'operazione. |
| Cognito | Alcune operazioni sono solo anonime. |
| SSO | Alcune operazioni sono esclusivamente anonime. |
| STS | Alcune operazioni sono esclusivamente anonime. |
# Configurazione degli endpoint client
**avvertimento**
La risoluzione degli endpoint è un argomento SDK avanzato. Modificando queste impostazioni rischi di violare il codice. Le impostazioni predefinite dovrebbero essere applicabili alla maggior parte degli utenti negli ambienti di produzione.
AWS SDK per Go Offre la possibilità di configurare un endpoint personalizzato da utilizzare per un servizio. Nella maggior parte dei casi, la configurazione predefinita sarà sufficiente. La configurazione degli endpoint personalizzati consente comportamenti aggiuntivi, ad esempio l'utilizzo di versioni precedenti al rilascio di un servizio.
## Personalizzazione
Esistono due «versioni» della configurazione della risoluzione degli endpoint all'interno dell'SDK.
+ v2, rilasciata nel terzo trimestre del 2023, configurata tramite:
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1, rilasciato insieme all'SDK, configurato tramite:
+ `EndpointResolver`
Consigliamo agli utenti con risoluzione degli endpoint v1 di migrare alla versione 2 per ottenere l'accesso a nuove funzionalità di servizio relative agli endpoint.
## V2: \$1 `EndpointResolverV2` `BaseEndpoint`
Nella risoluzione v2, `EndpointResolverV2` è il meccanismo definitivo attraverso il quale avviene la risoluzione degli endpoint. Il `ResolveEndpoint` metodo del resolver viene richiamato come parte del flusso di lavoro per ogni richiesta effettuata nell'SDK. Il nome host del file `Endpoint` restituito dal resolver viene utilizzato così com'**è** quando si effettua la richiesta (i serializzatori operativi possono comunque essere aggiunti al percorso HTTP).
La risoluzione v2 include una configurazione aggiuntiva a livello di client, `BaseEndpoint` che viene utilizzata per specificare un nome host «base» per l'istanza del servizio. Il valore qui impostato non è definitivo: alla fine viene passato come parametro al client `EndpointResolverV2` quando si verifica la risoluzione finale (continua a leggere per ulteriori informazioni sui parametri). `EndpointResolverV2` L'implementazione del resolver ha quindi l'opportunità di ispezionare e potenzialmente modificare quel valore per determinare l'endpoint finale.
Ad esempio, se esegui una `GetObject` richiesta S3 su un determinato bucket con un client in cui hai specificato a`BaseEndpoint`, il resolver predefinito inietterà il bucket nel nome host se è compatibile con l'host virtuale (supponendo che tu non abbia disabilitato l'hosting virtuale nella configurazione del client).
In pratica, molto probabilmente `BaseEndpoint` verrà utilizzato per indirizzare il cliente verso un'istanza di sviluppo o di anteprima di un servizio.
### Parametri di `EndpointResolverV2`
Ogni servizio accetta un set specifico di input che vengono passati alla sua funzione di risoluzione, definita in ogni pacchetto di servizi come`EndpointParameters`.
Ogni servizio include i seguenti parametri di base, utilizzati per facilitare la risoluzione generale degli endpoint all'interno di: AWS
| nome | tipo | description |
| --- | --- | --- |
| Region | string | La regione del cliente AWS |
| Endpoint | string | Il valore impostato per BaseEndpoint nella configurazione del client |
| UseFips | bool | Se gli endpoint FIPS sono abilitati nella configurazione del client |
| UseDualStack | bool | Se gli endpoint dual-stack sono abilitati nella configurazione del client |
I servizi possono specificare parametri aggiuntivi necessari per la risoluzione. Ad esempio, S3 `EndpointParameters` include il nome del bucket e diverse impostazioni di funzionalità specifiche di S3, ad esempio se l'indirizzamento dell'host virtuale è abilitato.
Se ne stai implementando uno tuo`EndpointResolverV2`, non dovresti mai aver bisogno di creare la tua istanza di. `EndpointParameters` L'SDK genererà i valori per ogni richiesta e li passerà all'implementazione.
### Una nota su Amazon S3
Amazon S3 è un servizio complesso con molte delle sue funzionalità modellate attraverso complesse personalizzazioni degli endpoint, come l'hosting virtuale di bucket, S3 MRAP e altro ancora.
Per questo motivo, ti consigliamo di non sostituire l'implementazione nel tuo client S3. `EndpointResolverV2` Se hai bisogno di estenderne il comportamento di risoluzione, magari inviando richieste a uno stack di sviluppo locale con considerazioni aggiuntive sugli endpoint, ti consigliamo di completare l'implementazione predefinita in modo da delegare a quella predefinita come riserva (mostrata negli esempi seguenti).
### Esempi
#### Con `BaseEndpoint`
Il seguente frammento di codice mostra come indirizzare il client S3 verso un'istanza locale di un servizio, che in questo esempio è ospitato sul dispositivo di loopback sulla porta 8080.
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### Con `EndpointResolverV2`
Il seguente frammento di codice mostra come inserire un comportamento personalizzato nella risoluzione degli endpoint di S3 utilizzando. `EndpointResolverV2`
```
import (
"context"
"net/url"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {
// you could inject additional application context here as well
}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
if /* input params or caller context indicate we must route somewhere */ {
u, err := url.Parse("https://custom.service.endpoint/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
// delegate back to the default v2 resolver otherwise
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
// load config...
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.EndpointResolverV2 = &resolverV2{
// ...
}
})
}
```
#### Con entrambi
Il seguente programma di esempio dimostra l'interazione tra `BaseEndpoint` e`EndpointResolverV2`. **Questo è un caso d'uso avanzato:**
```
import (
"context"
"fmt"
"log"
"net/url"
"github.com/aws/aws-sdk-go-v2"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// s3.Options.BaseEndpoint is accessible here:
fmt.Printf("The endpoint provided in config is %s\n", *params.Endpoint)
// fallback to default
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if (err != nil) {
log.Fatal(err)
}
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.BaseEndpoint = aws.String("https://endpoint.dev/")
o.EndpointResolverV2 = &resolverV2{}
})
// ignore the output, this is just for demonstration
client.ListBuckets(context.Background(), nil)
}
```
Quando viene eseguito, il programma precedente emette quanto segue:
```
The endpoint provided in config is https://endpoint.dev/
```
## V1: `EndpointResolver`
**avvertimento**
La risoluzione degli endpoint v1 viene mantenuta per motivi di compatibilità con le versioni precedenti ed è isolata dal comportamento moderno della risoluzione degli endpoint v2. Verrà utilizzato solo se il `EndpointResolver` campo è impostato dal chiamante.
L'uso della v1 probabilmente impedirà di accedere alle funzionalità del servizio relative agli endpoint introdotte con o dopo il rilascio della risoluzione v2. Vedi «Migrazione» per istruzioni su come eseguire l'aggiornamento.
A [EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver)può essere configurato per fornire una logica di risoluzione degli endpoint personalizzata per i client di servizio. È possibile utilizzare un resolver di endpoint personalizzato per sovrascrivere la logica di risoluzione degli endpoint di un servizio per tutti gli endpoint o solo per un endpoint regionale specifico. Un resolver di endpoint personalizzato può attivare la logica di risoluzione degli endpoint del servizio in fallback se un resolver personalizzato non desidera risolvere un endpoint richiesto. [EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc)può essere usato per racchiudere facilmente le funzioni in modo da soddisfare l'interfaccia. `EndpointResolverWithOptions`
A `EndpointResolver` può essere facilmente configurato passando il resolver incluso nella confezione [WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions)a [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), dando la possibilità di sovrascrivere gli endpoint durante il caricamento delle credenziali e configurando il risultato con un resolver endpoint personalizzato. `aws.Config`
Al resolver dell'endpoint vengono assegnati il servizio e la regione sotto forma di stringa, che consente al resolver di determinare dinamicamente il proprio comportamento. Ogni pacchetto client di servizio contiene una `ServiceID` costante esportata che può essere utilizzata per determinare quale client di servizio sta richiamando il resolver dell'endpoint.
Un endpoint resolver può utilizzare il valore di errore [EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError)sentinel per attivare la risoluzione di fallback sulla logica di risoluzione predefinita del client del servizio. Ciò consente di sovrascrivere in modo selettivo uno o più endpoint senza interruzioni senza dover gestire la logica di fallback.
Se l'implementazione del resolver per endpoint restituisce un errore diverso da`EndpointNotFoundError`, la risoluzione degli endpoint si interromperà e l'operazione del servizio restituirà un errore all'applicazione.
### Esempi
#### Con fallback
Il seguente frammento di codice mostra come un singolo endpoint di servizio può essere sovrascritto per DynamoDB con un comportamento di fallback per altri endpoint:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
// returning EndpointNotFoundError will allow the service to fallback to it's default resolution
return aws.Endpoint{}, &aws.EndpointNotFoundError{}
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
#### Senza fallback
Il seguente frammento di codice mostra come un singolo endpoint di servizio può essere sovrascritto per DynamoDB senza un comportamento di fallback per altri endpoint:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
### Endpoint immutabili
**avvertimento**
L'impostazione di un endpoint come immutabile può impedire il corretto funzionamento di alcune funzionalità del client di servizio e potrebbe comportare un comportamento indefinito. È necessario prestare attenzione quando si definisce un endpoint come immutabile.
Alcuni client di servizio, come Amazon S3, possono modificare l'endpoint restituito dal resolver per determinate operazioni di servizio. Ad esempio, Amazon S3 gestirà automaticamente il [Virtual Bucket Addressing](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) modificando l'endpoint risolto. Puoi impedire che l'SDK modifichi i tuoi endpoint personalizzati impostando su. [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)`true` Esempio:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
HostnameImmutable: true,
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
## Migrazione
Durante la migrazione dalla versione v1 alla versione 2 della risoluzione degli endpoint, si applicano i seguenti principi generali:
+ Restituire un [Endpoint](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) con [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)set to `false` equivale all'incirca `BaseEndpoint` a impostare l'URL originariamente restituito dalla v1 e lasciarlo come predefinito. `EndpointResolverV2`
+ Restituire un Endpoint con HostnameImmutable set to `true` equivale all'incirca a implementare un `EndpointResolverV2` che restituisce l'URL originariamente restituito dalla v1.
+ L'eccezione principale riguarda le operazioni con prefissi di endpoint modellati. Una nota al riguardo è riportata più avanti.
Di seguito sono riportati alcuni esempi di questi casi.
**avvertimento**
Gli endpoint immutabili V1 e la risoluzione V2 non hanno un comportamento equivalente. Ad esempio, le sostituzioni di firma per funzionalità personalizzate come S3 Object Lambda sarebbero comunque impostate per gli endpoint immutabili restituiti tramite il codice v1, ma lo stesso non verrà fatto per la v2.
### Nota sui prefissi degli host
Alcune operazioni sono modellate con prefissi host da anteporre all'endpoint risolto. Questo comportamento deve funzionare insieme all'output di ResolveEndpoint V2 e pertanto il prefisso host verrà comunque applicato a quel risultato.
È possibile disabilitare manualmente il prefisso dell'host dell'endpoint applicando un middleware, vedere la sezione degli esempi.
### Esempi
#### Endpoint mutabile
Il seguente esempio di codice mostra come migrare un endpoint resolver v1 di base che restituisce un endpoint modificabile:
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/")
})
// v2
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
// the value of BaseEndpoint is passed to the default EndpointResolverV2
// implementation, which will handle routing for features such as S3 accelerate,
// MRAP, etc.
o.BaseEndpoint = aws.String("https://custom.endpoint.api/")
})
```
#### Endpoint immutabile
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/", func (e *aws.Endpoint) {
e.HostnameImmutable = true
})
})
// v2
import (
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type staticResolver struct {}
func (*staticResolver) ResolveEndpoint(ctx context.Context, params svc.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// This value will be used as-is when making the request.
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolverV2 = &staticResolver{}
})
```
#### Disabilita il prefisso dell'host
```
import (
"context"
"fmt"
"net/url"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/"
smithyendpoints "github.com/aws/smithy-go/endpoints"
"github.com/aws/smithy-go/middleware"
smithyhttp "github.com/aws/smithy-go/transport/http"
)
// disableEndpointPrefix applies the flag that will prevent any
// operation-specific host prefix from being applied
type disableEndpointPrefix struct{}
func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" }
func (disableEndpointPrefix) HandleInitialize(
ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
) (middleware.InitializeOutput, middleware.Metadata, error) {
ctx = smithyhttp.SetHostnameImmutable(ctx, true)
return next.HandleInitialize(ctx, in)
}
func addDisableEndpointPrefix(o *.Options) {
o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error {
return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After)
}))
}
type staticResolver struct{}
func (staticResolver) ResolveEndpoint(ctx context.Context, params .EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{URI: *u}, nil
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
panic(err)
}
svc := .NewFromConfig(cfg, func(o *.Options) {
o.EndpointResolverV2 = staticResolver{}
})
_, err = svc.(context.Background(), &.{ /* ... */ },
addDisableEndpointPrefix)
if err != nil {
panic(err)
}
}
```
# Personalizzazione del client HTTP
AWS SDK per Go Utilizza un client HTTP predefinito con valori di configurazione predefiniti. Sebbene sia possibile modificare alcuni di questi valori di configurazione, il client e il trasporto HTTP predefiniti non sono sufficientemente configurati per i clienti che li utilizzano AWS SDK per Go in un ambiente con requisiti di velocità effettiva elevata e bassa latenza. Per ulteriori informazioni, consulta la sezione in [Domande frequenti](faq-gosdk.md) quanto i consigli di configurazione variano in base a carichi di lavoro specifici. Questa sezione descrive come configurare un client HTTP personalizzato e utilizzarlo per creare AWS SDK per Go chiamate.
Per facilitare la creazione di un client HTTP personalizzato, questa sezione descrive come [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient)configurare impostazioni personalizzate e utilizzare tale client con un client di AWS SDK per Go servizio.
Definiamo cosa vogliamo personalizzare.
## Sovrascrivere durante il caricamento della configurazione
È possibile fornire client HTTP personalizzati durante la chiamata [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig)avvolgendo il client utilizzando [With HTTPClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) e passando il valore risultante a. `LoadDefaultConfig` Ad esempio, per passare `customClient` come nostro cliente:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## Timeout
`BuildableHTTPClient`Può essere configurato con un limite di timeout della richiesta. Questo timeout include il tempo necessario per la connessione, l'elaborazione di eventuali reindirizzamenti e la lettura del corpo completo della risposta. Ad esempio, per modificare il timeout del client:
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## Dialer
`BuildableHTTPClient`[Fornisce una meccanica di costruzione per la creazione di client con opzioni Dialer modificate.](https://golang.org/pkg/net/#Dialer) L'esempio seguente mostra come configurare le impostazioni di un client. `Dialer`
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net"
// ...
httpClient := awshttp.NewBuildableClient().WithDialerOptions(func(d *net.Dialer) {
d.KeepAlive = -1
d.Timeout = time.Millisecond*500
})
```
### Impostazioni
#### Dialer. KeepAlive
Questa impostazione rappresenta il periodo di mantenimento per una connessione di rete attiva.
Imposta su un valore negativo per disabilitare i keep-alive.
Imposta su **0** per abilitare i keep-alive se supportati dal protocollo e dal sistema operativo.
I protocolli di rete o i sistemi operativi che non supportano i keep-alive ignorano questo campo. Per impostazione predefinita, TCP abilita keep alive.
Vedi [https://golang. org/pkg/net/\$1Dialer. KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive)
Imposta `KeepAlive` come **Time.Duration.**
#### Dialer.Timeout
Questa impostazione rappresenta il tempo massimo di attesa di una chiamata per la creazione di una connessione.
L'impostazione predefinita è 30 secondi.
Vedi [https://golang. org/pkg/net/\$1Dialer .Timeout](https://golang.org/pkg/net/#Dialer.Timeout)
**Imposta `Timeout` come time.Duration.**
## Trasporto
`BuildableHTTPClient`[Fornisce una meccanica di costruzione per la costruzione di client con opzioni di trasporto modificate.](https://golang.org/pkg/net/http#Transport)
### Configurazione di un proxy
Se non riesci a connetterti direttamente a Internet, puoi utilizzare le variabili di ambiente supportate da Go (`HTTP_PROXY`/`HTTPS_PROXY`) o creare un client HTTP personalizzato per configurare il proxy. L'esempio seguente configura il client da utilizzare `PROXY_URL` come endpoint proxy:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
proxyURL, err := url.Parse("PROXY_URL")
if err != nil {
log.Fatal(err)
}
tr.Proxy = http.ProxyURL(proxyURL)
})
```
### Altre impostazioni
Di seguito sono riportate alcune altre `Transport` impostazioni che possono essere modificate per ottimizzare il client HTTP. Tutte le impostazioni aggiuntive non descritte qui sono disponibili nella documentazione del tipo di [trasporto](https://golang.org/pkg/net/http/#Transport). Queste impostazioni possono essere applicate come illustrato nell'esempio seguente:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
tr.ExpectContinueTimeout = 0
tr.MaxIdleConns = 10
})
```
#### Trasporto. ExpectContinueTimeout
Se la richiesta ha un'intestazione «Expect: 100-continue», questa impostazione rappresenta il tempo massimo di attesa per le intestazioni della prima risposta di un server dopo aver scritto completamente le intestazioni della richiesta. Questo tempo non include il tempo necessario per inviare l'intestazione della richiesta. Il client HTTP invia il suo payload dopo che questo timeout è scaduto.
Impostazione predefinita: 1 secondo.
Imposta su **0** per non richiedere alcun timeout e invia il payload della richiesta senza attese. Un caso d'uso è quando si verificano problemi con proxy o servizi di terze parti che richiedono una sessione simile all'uso di Amazon S3 nella funzione mostrata più avanti.
[Vedi https://golang. org/pkg/net/http/\$1Transport. ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout)
Imposta `ExpectContinue` come **Time.Duration.**
#### Trasporto. IdleConnTimeout
Questa impostazione rappresenta la quantità massima di tempo per mantenere attiva una connessione di rete inattiva tra le richieste HTTP.
Imposta su **0** per non avere limiti.
Vedi [https://golang. org/pkg/net/http/\$1Transport. IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout)
Imposta `IdleConnTimeout` come **Time.Duration.**
#### Trasporto. MaxIdleConns
Questa impostazione rappresenta il numero massimo di connessioni inattive (keep-alive) su tutti gli host. Un caso d'uso per aumentare questo valore è quando si vedono molte connessioni in un breve periodo dagli stessi client
**0** significa nessun limite.
Vedi [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns)
Imposta `MaxIdleConns` come **int.**
#### Trasporto. MaxIdleConnsPerHost
Questa impostazione rappresenta il numero massimo di connessioni inattive (keep-alive) da mantenere per host. Un caso d'uso per aumentare questo valore è quando si vedono molte connessioni in un breve periodo dagli stessi client
L'impostazione predefinita è di due connessioni inattive per host.
Imposta su **0** per utilizzare DefaultMaxIdleConnsPerHost (2).
Vedi [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost)
Imposta `MaxIdleConnsPerHost` come **int.**
#### Trasporto. ResponseHeaderTimeout
Questa impostazione rappresenta il tempo massimo di attesa che un client legga l'intestazione della risposta.
Se il client non è in grado di leggere l'intestazione della risposta entro questo periodo, la richiesta ha esito negativo e viene generato un errore di timeout.
Fai attenzione a impostare questo valore quando usi funzioni Lambda a esecuzione prolungata, poiché l'operazione non restituisce alcuna intestazione di risposta fino al termine o al timeout della funzione Lambda. Tuttavia, è ancora possibile utilizzare questa opzione con l'operazione API\$1\$1 \$1\$1. InvokeAsync
L'impostazione predefinita è nessun timeout; attendi per sempre.
Vedi [https://golang. org/pkg/net/http/\$1Transport. ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout)
Imposta `ResponseHeaderTimeout` come **Time.Duration.**
#### Trasporto. TLSHandshakeTimeout
Questa impostazione rappresenta il tempo massimo di attesa per il completamento di un handshake TLS.
Il valore predefinito è 10 secondi.
Zero significa nessun timeout.
Vedi [https://golang. org/pkg/net/http/\$1Transport. TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout)
Imposta `TLSHandshakeTimeout` come **Time.Duration**.
# Intercettori HTTP
È possibile utilizzare gli intercettori per agganciarsi all'esecuzione di richieste e risposte API. Gli intercettori sono meccanismi aperti in cui l'SDK richiama il codice scritto dall'utente per inserire il comportamento nel ciclo di vita. request/response In questo modo, puoi modificare una richiesta in corso, eseguire il debug dell'elaborazione delle richieste, visualizzare le eccezioni e altro ancora.
## Interceptors vs. middleware
La versione AWS SDK per Go 2 fornisce sia intercettori che middleware per personalizzare l'elaborazione delle richieste. Sebbene entrambi abbiano scopi simili, sono progettati per destinatari e casi d'uso diversi:
+ Gli **Interceptors** sono progettati per gli utenti SDK che desiderano personalizzare l' request/response elaborazione con una semplice API incentrata su HTTP. Forniscono punti di accesso specifici nel ciclo di vita della richiesta e funzionano direttamente con le richieste e le risposte HTTP.
+ Il **middleware** è un sistema più avanzato, indipendente dal trasporto, utilizzato principalmente internamente dall'SDK. Sebbene potente, il middleware richiede una conoscenza più approfondita degli interni dell'SDK e coinvolge interfacce più complesse.
Principali vantaggi degli intercettori rispetto al middleware per i casi d'uso più comuni:
+ **Incentrato sull'HTTP**: gli intercettori funzionano direttamente con le richieste e le risposte HTTP, eliminando la necessità di controllare il tipo di trasporto richiesto dal middleware.
+ **Interfacce più semplici: ogni hook interceptor** ha un'interfaccia specifica e mirata anziché il modello middleware generico.
+ **Modello di esecuzione più chiaro**: gli intercettori vengono eseguiti in punti ben definiti del ciclo di vita della richiesta senza la necessità di conoscere l'ordinamento degli stack del middleware.
**Nota**
Gli interceptor sono basati sul sistema middleware esistente, quindi entrambi possono coesistere nella stessa applicazione. Il middleware rimane disponibile per casi d'uso avanzati che richiedono un comportamento indipendente dal trasporto o una manipolazione complessa dello stack.
## Ganci intercettori disponibili
La AWS SDK per Go v2 fornisce ganci di intercettazione in varie fasi del ciclo di vita della richiesta. Ogni hook corrisponde a un'interfaccia specifica che puoi implementare:
+ `BeforeExecution`- Primo hook chiamato durante l'esecuzione dell'operazione
+ `BeforeSerialization`- Prima che il messaggio di input venga serializzato nella richiesta di trasporto
+ `AfterSerialization`- Dopo che il messaggio di input è stato serializzato nella richiesta di trasporto
+ `BeforeRetryLoop`- Prima di entrare nel ciclo di riprova
+ `BeforeAttempt`- Primo hook chiamato inside retry loop
+ `BeforeSigning`- Prima della firma della richiesta di trasporto
+ `AfterSigning`- Dopo la firma della richiesta di trasporto
+ `BeforeTransmit`- Prima dell'invio della richiesta di trasporto
+ `AfterTransmit`- Dopo aver ricevuto la risposta di trasporto
+ `BeforeDeserialization`- Prima che la risposta al trasporto venga deserializzata
+ `AfterDeserialization`- Dopo aver riordinato la risposta di trasporto
+ `AfterAttempt`- Ultimo hook chiamato inside retry loop
+ `AfterExecution`- Ultimo hook chiamato durante l'esecuzione dell'operazione
È possibile implementare più interfacce in un unico intercettore per collegarsi a più fasi del ciclo di vita della richiesta.
## Registrazione Interceptor
Gli intercettori vengono registrati quando si costruisce un client di servizio o quando si sostituisce la configurazione per un'operazione specifica. La registrazione varia a seconda che si desideri che l'interceptor si applichi a tutte le operazioni del client o solo a quelle specifiche.
Gli intercettori sono gestiti tramite un registro di intercettori che fornisce metodi per aggiungere e rimuovere gli intercettori. L'esempio seguente mostra un semplice interceptor che aggiunge un'intestazione Trace ID alle richieste in uscita prima del processo di firma: AWS X-Ray
```
type recursionDetection struct{}
func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
}
return nil
}
// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
Il registro degli intercettori viene aggiunto a Client Options, che consente la configurazione degli intercettori per singola operazione:
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## Configurazione globale degli intercettori
È inoltre possibile registrare gli intercettori a livello globale utilizzando la `config.LoadDefaultConfig` funzione con le opzioni appropriate `With*` per ogni tipo di intercettore. Questo applica l'interceptor a tutti i client di servizio creati da quella configurazione: AWS
```
type myExecutionInterceptor struct{}
func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
// Add your custom logic here
return nil
}
cfg, err := config.LoadDefaultConfig(context.Background(),
config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
panic(err)
}
// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)
```
# Registrazione
AWS SDK per Go Dispone di funzionalità di registrazione che consentono all'applicazione di abilitare le informazioni di debug per il debug e la diagnosi di problemi o errori nelle richieste. L'interfaccia [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) e [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)i componenti principali a vostra disposizione per determinare come e cosa devono essere registrati dai client.
## Logger
Quando si costruisce un [Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config), [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig)l'utilizzo di un `Logger` valore predefinito è configurato per inviare messaggi di registro all'errore standard del processo (stderr). [Un logger personalizzato che soddisfa l'interfaccia [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) può essere passato come argomento a racchiudendolo con config. `LoadDefaultConfig` WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger).
Ad esempio, per configurare i nostri clienti in modo che utilizzino i nostri`applicationLogger`:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
Ora i client configurati utilizzando il build `aws.Config` invieranno messaggi di registro a`applicationLogger`.
### Logger sensibili al contesto
Un'implementazione di Logger può implementare l'interfaccia opzionale. [ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger) I logger che implementano questa interfaccia avranno i loro `WithContext` metodi richiamati nel contesto corrente. Ciò consente alle implementazioni di registrazione di restituirne una nuova in `Logger` grado di scrivere metadati di registrazione aggiuntivi in base ai valori presenti nel contesto.
## ClientLogMode
Per impostazione predefinita, i client di servizio non producono messaggi di registro. Per configurare i client per l'invio di messaggi di registro a scopo di debug, usa il [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)member on. `Config` `ClientLogMode`può essere impostato per abilitare la messaggistica di debug per:
+ Firma versione 4 (SigV4) Firma
+ Richiedi nuovi tentativi
+ Richieste HTTP
+ Risposte HTTP
Ad esempio, per abilitare la registrazione delle richieste e dei tentativi HTTP:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
Vedi [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)le diverse modalità di registro del client disponibili.
# Tracce e metriche
AWS SDK per Go È progettato per registrare gli intervalli di traccia e le metriche lato client per le operazioni SDK. Per impostazione predefinita, i client utilizzano implementazioni no-op sia per il tracciamento che per le metriche, il che significa che non viene raccolto alcun dato a meno che non si configuri un provider.
I client di servizio hanno due opzioni di configurazione per l'osservabilità:
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider)— Punto di ingresso per la creazione di traccianti e la registrazione degli intervalli di traccia dei client.
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider)— Punto di ingresso per la creazione di contatori e la registrazione delle metriche lato client.
Sebbene ispirate alle specifiche OpenTelemetry (OTel), queste APIs sono definite indipendentemente in. `smithy-go` L'SDK fornisce moduli adattatori per collegare implementazioni OTel SDK concrete alle interfacce del provider dell'SDK.
## Tracciamento
Utilizzate il modulo adattatore [smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) per connettere un client di servizio. OTel `trace.TracerProvider`
L'esempio seguente mostra come configurare il tracciamento per un client Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/tracing/smithyoteltracing"
"go.opentelemetry.io/otel/trace"
)
// provider is an OTel trace.TracerProvider that you have configured.
var provider trace.TracerProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.TracerProvider = smithyoteltracing.Adapt(provider)
})
```
Le operazioni SDK sono strumentate con una gerarchia di intervalli che copre i componenti di alto livello del ciclo di vita dell'operazione, come la serializzazione delle richieste, la firma e il ciclo di riprova.
## Metriche
Utilizzate il modulo adattatore [smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) per connettere An a un client di servizio. OTel `metric.MeterProvider`
L'esempio seguente mostra come configurare i parametri per un client Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/metrics/smithyotelmetrics"
"go.opentelemetry.io/otel/metric"
)
// provider is an OTel metric.MeterProvider that you have configured.
var provider metric.MeterProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.MeterProvider = smithyotelmetrics.Adapt(provider)
})
```
### Parametri supportati
I client SDK raccolgono le seguenti metriche:
| Nome parametro | Unità | Tipo | Description |
| --- | --- | --- | --- |
| client.call.duration | s | Istogramma | Durata complessiva della chiamata, compresi i nuovi tentativi e il tempo necessario per inviare o ricevere la richiesta e il messaggio di risposta. |
| client.call.attempts | \$1tentativo\$1 | MonotonicCounter | Il numero di tentativi per una singola operazione. |
| client.call.errors | \$1errore\$1 | MonotonicCounter | Il numero di errori per un'operazione. |
| client.call.attempt\$1duration | s | Istogramma | L'ora necessaria per connettersi al servizio, inviare la richiesta e recuperare il codice di stato HTTP e le intestazioni (incluso il tempo in coda in attesa di invio). |
| client.call.resolve\$1endpoint\$1duration | s | Istogramma | L'ora necessaria per risolvere un endpoint (endpoint resolver, non DNS) per la richiesta. |
| client.call.deserialization\$1duration | s | Istogramma | Il momento necessario per deserializzare il corpo del messaggio. |
| client.call.auth.signing\$1duration | s | Istogramma | L'ora in cui firmare una richiesta. |
| client.call.auth.resolve\$1identity\$1duration | s | Istogramma | Il momento necessario per acquisire un'identità (AWS credenziali, token al portatore, ecc.) da un provider di identità. |
I seguenti attributi (dimensioni) sono inclusi in ogni metrica, ove applicabile:
+ `rpc.service`— Il nome del servizio.
+ `rpc.method`— Il nome dell'operazione.
+ `exception.type`— Il tipo di errore (incluso in`client.call.errors`).
+ `auth.scheme_id`— Lo schema di autenticazione (incluso nelle metriche relative all'autenticazione).
### Metriche del client HTTP
Il client HTTP dell'SDK raccoglie le seguenti metriche aggiuntive relative al ciclo di vita della connessione HTTP sottostante:
| Nome parametro | Unità | Tipo | Description |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | s | Istogramma | Il tempo impiegato da una richiesta per acquisire una connessione. |
| client.http.connections.dns\$1lookup\$1duration | s | Istogramma | Il tempo necessario per eseguire una ricerca DNS. |
| client.http.connections.tls\$1handshake\$1duration | s | Istogramma | Il tempo necessario per eseguire un handshake TLS. |
| client.http.connections.usage | \$1connessione\$1 | UpDownCounter | Lo stato attuale delle connessioni nel pool. Utilizza una state dimensione con un valore di idle oacquired. |
| client.http.do\$1request\$1duration | s | Istogramma | Il tempo totale impiegato per eseguire la richiesta HTTP. |
| client.http.time\$1to\$1first\$1byte | s | Istogramma | Il tempo che intercorre tra l'invio della richiesta e la ricezione del primo byte di risposta. |
# Tentativi e timeout
AWS SDK per Go Consente di configurare il comportamento di ripetizione delle richieste ai servizi HTTP. Per impostazione predefinita, i client di servizio utilizzano [Retry.Standard come retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) predefinito. Se la configurazione o il comportamento predefiniti non soddisfano i requisiti dell'applicazione, è possibile modificare la configurazione di retryer o fornire un'implementazione retryer personalizzata.
AWS SDK per Go Fornisce un'interfaccia [AWS.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) che definisce l'insieme di metodi richiesti da un'implementazione Retry per l'implementazione. [L'SDK fornisce due implementazioni per i tentativi: retry.standard e aws.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) [ NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer).
## Retrizzatore standard
[Retry.Standard retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) è l'`aws.Retryer`implementazione predefinita utilizzata dai client SDK. Il retryer standard è un retryer a velocità limitata con un numero massimo di tentativi configurabile e la possibilità di ottimizzare la politica di annullamento della richiesta.
La tabella seguente definisce i valori predefiniti per questo retryer:
| Proprietà | Predefinita |
| --- | --- |
| Numero massimo di tentativi | 3 |
| Ritardo massimo di back off | 20 secondi |
Quando si verifica un errore riutilizzabile durante l'invocazione della richiesta, il sistema standard utilizzerà la configurazione fornita per ritardare e successivamente riprovare la richiesta. I nuovi tentativi aumentano la latenza complessiva della richiesta ed è necessario configurare retryer se la configurazione predefinita non soddisfa i requisiti dell'applicazione.
Consultate la documentazione del pacchetto [retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) per i dettagli su quali errori sono considerati riutilizzabili dall'implementazione standard di retryer.
## NopRetryer
[Le leggi. NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer)è un'`aws.Retryer`implementazione che viene fornita se si desidera disabilitare tutti i tentativi di nuovo tentativo. Quando si richiama l'operazione di un client di servizio, questo retryer consente di tentare la richiesta una sola volta e qualsiasi errore risultante verrà restituito all'applicazione chiamante.
## Personalizzazione del comportamento
L'SDK fornisce una serie di utilità di supporto che completano un'`aws.Retryer`implementazione e restituisce il retryer fornito con il comportamento di riprova desiderato. È possibile sostituire il retryer predefinito per tutti i client, per client o per operazione, a seconda dei requisiti delle applicazioni. Per vedere altri esempi che mostrano come eseguire questa operazione, consulta gli esempi di documentazione del pacchetto [retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
**avvertimento**
Se si specifica un'`aws.Retryer`implementazione globale utilizzando`config.WithRetryer`, è necessario assicurarsi di restituire una nuova istanza di `aws.Retryer` ogni chiamata. In questo modo non creerai un bucket di token di riprova globale su tutti i client di servizio.
### Limitazione del numero massimo di tentativi
Si usa [retry. AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts)per completare un'`aws.Retryer`implementazione per impostare il numero massimo di tentativi sul valore desiderato.
**avvertimento**
L'utilizzo `retry.AddWithMaxAttempts` con un valore pari a zero consentirà all'SDK di riprovare tutti gli errori riproducibili finché la richiesta non avrà esito positivo o non verrà restituito un errore non riproducibile. **Consentire all'SDK di riprovare all'infinito può comportare carichi di lavoro inutili e cicli di fatturazione gonfiati.**
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will be infinite (will retry indefinitely)
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxAttempts(retry.NewStandard(), 0)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
Tieni presente che l'istanziazione di un retryer utilizzando opzioni funzionali per l'impostazione diretta avrà un comportamento leggermente diverso. MaxAttempts Più specificamente, l'impostazione di un valore inferiore o uguale a zero farà sì che il retryer utilizzi il massimo predefinito di 3 tentativi, anziché riprovare all'infinito:
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will default to 3
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.MaxAttempts = 0
})
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Limitazione del ritardo massimo di backoff
Si usa [retry. AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay)per completare un'`aws.Retryer`implementazione e limitare il ritardo massimo consentito tra un tentativo e l'altro di una richiesta fallita.
Ad esempio, è possibile utilizzare il codice seguente per eseguire il wrapping del client retryer standard con un ritardo massimo desiderato di cinque secondi:
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Riprova i codici di errore API aggiuntivi
Si utilizza [retry. AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes)per completare un'`aws.Retryer`implementazione e includere codici di errore API aggiuntivi che dovrebbero essere considerati riutilizzabili.
Ad esempio, puoi utilizzare il codice seguente per inserire il client retryer standard in modo da includere l'eccezione Amazon `NoSuchBucketException` S3 come riutilizzabile.
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/service/s3/types"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithErrorCodes(retry.NewStandard(), (*types.NoSuchBucketException)(nil).ErrorCode())
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Limitazione della tariffa lato client
AWS SDK per Go Introduce un nuovo meccanismo di limitazione della velocità lato client nella politica di ripetizione dei tentativi standard per allinearsi al comportamento moderno. SDKs [Questo comportamento è controllato dal campo delle opzioni di un retryer. [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter)](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions)
A RateLimiter funziona come un token bucket con una capacità prestabilita, laddove i tentativi di operazione falliti consumano i token. Un nuovo tentativo che tenta di consumare più token di quelli disponibili comporta un fallimento dell'operazione con a. [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError)
L'implementazione predefinita è parametrizzata come segue (come modificare ogni impostazione):
+ una capacità di 500 (imposta il valore di RateLimiter on StandardOptions using) [NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit)
+ un nuovo tentativo causato da un timeout costa 10 token (impostato su) RetryTimeoutCost StandardOptions
+ un nuovo tentativo causato da altri errori costa 5 token (impostato su) RetryCost StandardOptions
+ un'operazione che riesce al primo tentativo aggiunge 1 token (impostato su) NoRetryIncrement StandardOptions
+ le operazioni che hanno esito positivo al secondo o successivo tentativo non aggiungono nuovamente alcun token
Se ritieni che il comportamento predefinito non soddisfi le esigenze dell'applicazione, puoi disabilitarlo con [RateLimit.None](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables).
#### Esempio: limitatore di velocità modificato
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
// Makes the rate limiter more permissive in general. These values are
// arbitrary for demonstration and may not suit your specific
// application's needs.
o.RateLimiter = ratelimit.NewTokenRateLimit(1000)
o.RetryCost = 1
o.RetryTimeoutCost = 3
o.NoRetryIncrement = 10
})
}))
```
#### Esempio: nessun limite di velocità utilizzando RateLimit.None
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.RateLimiter = ratelimit.None
})
}))
```
## Timeout
Si utilizza il pacchetto [context](https://golang.org/pkg/context/) per impostare timeout o scadenze quando si richiama un'operazione del client di servizio. [Usa il contesto. WithDeadline](https://golang.org/pkg/context/#WithDeadline)per riassumere il contesto dell'applicazione e fissare una scadenza a un'ora specifica entro la quale l'operazione richiamata deve essere completata. [Per impostare un timeout dopo un determinato `time.Duration` contesto di utilizzo. WithTimeout](https://golang.org/pkg/context/#WithTimeout). L'SDK passa il fornito `context.Context` al client di trasporto HTTP quando richiama un'API di servizio. Se il contesto passato all'SDK viene annullato o viene annullato durante l'invocazione dell'operazione, l'SDK non ritenterà ulteriormente la richiesta e tornerà all'applicazione chiamante. È necessario gestire l'annullamento del contesto in modo appropriato nell'applicazione nei casi in cui il contesto fornito all'SDK sia stato annullato.
### Impostazione di un timeout
L'esempio seguente mostra come impostare un timeout per l'operazione di un client di servizio.
```
import "context"
import "time"
// ...
ctx := context.TODO() // or appropriate context.Context value for your application
client := s3.NewFromConfig(cfg)
// create a new context from the previous ctx with a timeout, e.g. 5 seconds
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
resp, err := client.GetObject(ctx, &s3.GetObjectInput{
// input parameters
})
if err != nil {
// handle error
}
```