Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Configuration du kit SDK
Dans la AWS SDK pour Go version V2, vous pouvez configurer des paramètres courants pour les clients de service, tels que l'enregistreur, le niveau de journalisation et la configuration des nouvelles tentatives. La plupart des paramètres sont facultatifs. Toutefois, pour chaque client de service, vous devez spécifier une AWS région et vos informations d'identification. Le SDK utilise ces valeurs pour envoyer des demandes à la région appropriée et signer les demandes avec les informations d'identification correctes. Vous pouvez spécifier ces valeurs par programmation dans le code ou via l'environnement d'exécution.
## Chargement de fichiers de configuration AWS partagés
Il existe plusieurs méthodes pour initialiser un client d'API de service, mais voici le modèle le plus couramment recommandé aux utilisateurs.
Pour configurer le SDK afin d'utiliser les fichiers de configuration AWS partagés, utilisez le code suivant :
```
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())`construira un fichier [AWS.config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) en utilisant les sources de configuration AWS partagées. Cela inclut la configuration d'un fournisseur d'informations d'identification, la configuration de la AWS région et le chargement de la configuration spécifique au service. Les clients de service peuvent être créés à l'aide du fichier chargé`aws.Config`, fournissant ainsi un modèle cohérent pour la construction de clients.
Pour plus d'informations sur les fichiers de configuration AWS partagés, consultez la section [Configuration](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) dans le guide de référence des outils AWS SDKs et des outils.
## Spécification de la AWS région
Lorsque vous spécifiez la région, vous indiquez où envoyer les demandes, par exemple `us-west-2` ou`us-east-2`. Pour obtenir la liste des régions pour chaque service, consultez la section [Points de terminaison et quotas du service](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) dans le Référence générale d'Amazon Web Services.
Le SDK ne possède pas de région par défaut. Pour spécifier une région :
+ Définissez la variable d'`AWS_REGION`environnement sur la région par défaut.
+ Définissez la région de manière explicite à l'aide de [config. WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127)comme argument `config.LoadDefaultConfig` lors du chargement de la configuration.
RÉVISION : Si vous définissez une région à l'aide de toutes ces techniques, le SDK utilise la région que vous avez explicitement spécifiée.
### Configurer la région avec une variable d'environnement
#### Linux, macOS ou Unix
```
export AWS_REGION=us-west-2
```
#### Windows
```
set AWS_REGION=us-west-2
```
### Spécifier la région par programmation
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## Spécification des informations d'identification
AWS SDK pour Go Nécessite des informations d'identification (une clé d'accès et une clé d'accès secrète) pour signer les demandes à AWS. Vous pouvez spécifier vos informations d'identification à plusieurs endroits, en fonction de votre cas d'utilisation particulier. Pour plus d'informations sur l'obtention d'informations d'identification, consultez[Commencez avec AWS SDK pour Go](getting-started.md).
Lorsque vous initialisez une `aws.Config` instance à l'aide de`config.LoadDefaultConfig`, le SDK utilise sa chaîne d'informations d'identification par défaut pour rechercher les informations d'identification. AWS Cette chaîne d'informations d'identification par défaut recherche les informations d'identification dans l'ordre suivant :
1. Variables d'environnement.
1. Informations d'identification statiques (`AWS_ACCESS_KEY_ID`,`AWS_SECRET_ACCESS_KEY`,`AWS_SESSION_TOKEN`)
1. Jeton d'identité Web (`AWS_WEB_IDENTITY_TOKEN_FILE`)
1. Fichiers de configuration partagés.
1. Le SDK utilise par défaut `credentials` le fichier sous `.aws` le dossier qui est placé dans le dossier d'accueil de votre ordinateur.
1. Le SDK utilise par défaut `config` le fichier sous `.aws` le dossier qui est placé dans le dossier d'accueil de votre ordinateur.
1. Si votre application utilise une définition de tâche Amazon ECS ou une opération RunTask d'API, rôle IAM pour les tâches.
1. Si votre application s'exécute sur une instance Amazon EC2, rôle IAM pour Amazon EC2.
Le SDK détecte et utilise automatiquement les fournisseurs intégrés, sans nécessiter de configurations manuelles. Par exemple, si vous utilisez des rôles IAM pour les instances Amazon EC2, vos applications utilisent automatiquement les informations d'identification de l'instance. Il n'est pas nécessaire de configurer manuellement les informations d'identification dans votre application.
Il est AWS recommandé de spécifier les informations d'identification dans l'ordre suivant :
1. Utilisez des rôles IAM pour les tâches si votre application utilise une définition de tâche Amazon ECS ou une opération RunTask d'API.
1. Utilisez des rôles IAM pour Amazon EC2 (si votre application s'exécute sur une instance Amazon EC2).
Les rôles IAM fournissent aux applications présentes sur l'instance des informations d'identification de sécurité temporaires leur permettant de AWS passer des appels. Les rôles IAM permettent de distribuer et de gérer facilement les informations d'identification sur plusieurs instances Amazon EC2.
1. Utilisez des informations d'identification ou des fichiers de configuration partagés.
Les informations d'identification et les fichiers de configuration sont partagés entre d'autres AWS SDKs et AWS CLI. Pour des raisons de sécurité, nous vous recommandons d'utiliser un fichier d'informations d'identification pour définir des valeurs sensibles telles que la clé d'accès IDs et les clés secrètes. Voici les [exigences de mise en forme](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) pour chacun de ces fichiers.
1. Utiliser des variables d’environnement.
La définition de variables d'environnement est utile si vous effectuez des travaux de développement sur une machine autre qu'une instance Amazon EC2.
### Rôles IAM pour les tâches
Si votre application utilise une définition ou une `RunTask` opération de tâche Amazon ECS, utilisez les [rôles IAM pour les tâches pour](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) spécifier un rôle IAM qui peut être utilisé par les conteneurs d'une tâche.
### Rôles IAM pour les instances Amazon EC2
Si vous exécutez votre application sur une instance Amazon EC2, utilisez le [rôle IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) de l'instance pour obtenir des informations d'identification de sécurité temporaires auxquelles passer des appels. AWS
Si vous avez configuré votre instance pour utiliser des rôles IAM, le SDK utilise automatiquement ces informations d'identification pour votre application. Il n'est pas nécessaire de spécifier manuellement ces informations d'identification.
### Informations d'identification et configuration partagées
Les informations d'identification et les fichiers de configuration partagés peuvent être utilisés pour partager une configuration commune entre AWS SDKs d'autres outils. Si vous utilisez des informations d’identification différentes selon les outils ou les applications, vous pouvez utiliser des *profils* pour configurer plusieurs clés d’accès dans le même fichier de configuration.
Vous pouvez fournir plusieurs emplacements de fichiers d'identification ou de configuration en utilisant`config.LoadOptions`, par défaut, le SDK charge les fichiers stockés aux emplacements par défaut mentionnés dans le. [Spécification des informations d'identification](#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"},
)
)
```
Lorsque vous travaillez avec des informations d'identification et des fichiers de configuration partagés, si des profils dupliqués sont spécifiés, ils sont fusionnés pour résoudre un profil. En cas de conflit de fusion,
1. Si des profils dupliqués sont spécifiés dans un même credentials/config fichier, les propriétés de profil spécifiées dans ce dernier profil sont prioritaires.
1. Si des profils dupliqués sont spécifiés dans plusieurs fichiers d'informations d'identification ou dans plusieurs fichiers de configuration, les propriétés des profils sont résolues selon l'ordre d'entrée des fichiers dans le`config.LoadOptions`. Les propriétés du profil dans ces derniers fichiers sont prioritaires.
1. Si un profil existe à la fois dans le fichier d'informations d'identification et dans le fichier de configuration, les propriétés du fichier d'informations d'identification sont prioritaires.
Si nécessaire, vous pouvez `LogConfigurationWarnings` activer `config.LoadOptions` et enregistrer les étapes de résolution du profil.
#### Création du fichier d'informations d'identification
Si vous n'avez pas de fichier d'informations d'identification partagé (`.aws/credentials`), vous pouvez utiliser n'importe quel éditeur de texte pour en créer un dans votre répertoire personnel. Ajoutez le contenu suivant à votre fichier d'informations d'identification, en ** remplaçant ** et par vos informations d'identification.
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
L'`[default]`en-tête définit les informations d'identification du profil par défaut, que le SDK utilisera à moins que vous ne le configuriez pour utiliser un autre profil.
Vous pouvez également utiliser des informations d'identification de sécurité temporaires en ajoutant les jetons de session à votre profil, comme illustré dans l'exemple suivant :
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
Le nom de section d'un profil autre que celui par défaut dans un fichier d'informations d'identification ne doit pas commencer par le mot`profile`. Pour en savoir plus, consultez le [Guide AWS SDKs de référence des outils](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds).
#### Création du fichier de configuration
Si vous n'avez pas de fichier d'informations d'identification partagé (`.aws/config`), vous pouvez utiliser n'importe quel éditeur de texte pour en créer un dans votre répertoire personnel. Ajoutez le contenu suivant à votre fichier de configuration, en le ** remplaçant par la région souhaitée.
```
[default]
region =
```
L'`[default]`en-tête définit la configuration du profil par défaut, que le SDK utilisera à moins que vous ne le configuriez pour utiliser un autre profil.
Vous pouvez utiliser des profils nommés comme indiqué dans l'exemple suivant :
```
[profile named-profile]
region =
```
Le nom de section d'un profil autre que celui par défaut dans un fichier de configuration doit toujours commencer par le mot`profile`, suivi du nom de profil prévu. Pour en savoir plus, consultez le [guide de référence AWS SDKs et les outils](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config).
#### Spécification des profils
Vous pouvez inclure plusieurs clés d'accès dans le même fichier de configuration en associant chaque jeu de clés d'accès à un profil. Par exemple, dans votre fichier d'informations d'identification, vous pouvez déclarer plusieurs profils, comme suit.
```
[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 =
```
Par défaut, le kit SDK vérifie la variable d'environnement `AWS_PROFILE` afin de déterminer quel profil utiliser. Si aucune `AWS_PROFILE` variable n'est définie, le SDK utilise le `default` profil.
Parfois, vous souhaiterez peut-être utiliser un profil différent avec votre application. Par exemple, vous souhaitez utiliser les `test-account` informations d'identification avec votre `myapp` application. Vous pouvez utiliser ce profil à l'aide de la commande suivante :
```
$ AWS_PROFILE=test-account myapp
```
Vous pouvez également utiliser l'instruction du SDK pour sélectionner un profil soit en appelant `os.Setenv("AWS_PROFILE", "test-account")` avant d'appeler`config.LoadDefaultConfig`, soit en passant un profil explicite en argument, comme indiqué dans l'exemple suivant :
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**Note**
Si vous spécifiez des informations d'identification dans des variables d'environnement, le SDK utilise toujours ces informations d'identification, quel que soit le profil que vous spécifiez.
### Variables d’environnement
Par défaut, le SDK détecte les AWS informations d'identification définies dans votre environnement et les utilise pour signer les demandes. AWS Ainsi, vous n'avez pas besoin de gérer les informations d'identification dans vos applications.
Le SDK recherche les informations d'identification dans les variables d'environnement suivantes :
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (facultatif)
Les exemples suivants montrent comment configurer les variables d'environnement.
#### Linux, OS X ou 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
```
### Spécifier les informations d'identification par programmation
`config.LoadDefaultConfig`vous permet de fournir une loi [explicite. CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)lors du chargement des sources de configuration partagées. Pour transmettre un fournisseur d'informations d'identification explicite lors du chargement de la configuration partagée, utilisez [config. WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider). Par exemple, si elle `customProvider` fait référence à une instance d'`aws.CredentialProvider`implémentation, elle peut être transmise lors du chargement de la configuration comme suit :
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
Si vous fournissez explicitement des informations d'identification, comme dans cet exemple, le SDK utilise uniquement ces informations d'identification.
**Note**
Tous les fournisseurs d'informations d'identification transmis ou renvoyés par `LoadDefaultConfig` sont [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache)automatiquement encapsulés dans un fichier. Cela permet une mise en cache et une rotation des informations d'identification qui sont sûres en matière de simultanéité. Si vous configurez explicitement un fournisseur `aws.Config` directement, vous devez également encapsuler explicitement le fournisseur avec ce type en utilisant [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache).
#### Informations d'identification statiques
[Vous pouvez coder en dur les informations d'identification dans votre application à l'aide de celles-ci. NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider)fournisseur d'informations d'identification pour définir explicitement les clés d'accès à utiliser. Par exemple :
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**Avertissement**
N'intégrez pas d'informations d'identification dans une application. Utilisez cette méthode uniquement à des fins de test.
#### Informations d'identification unique
Le SDK fournit un fournisseur d'informations d'identification permettant de récupérer des informations d'identification temporaires AWS à l'aide de. AWS IAM Identity CenterÀ l'aide du AWS CLI, vous vous authentifiez auprès du portail AWS d'accès et autorisez l'accès aux AWS informations d'identification temporaires. Vous configurez ensuite votre application pour charger le profil d'authentification unique (SSO), et le SDK utilise vos informations d'identification SSO pour récupérer des informations d' AWS identification temporaires qui seront automatiquement renouvelées en cas d'expiration. Si vos informations d'identification SSO expirent, vous devez les renouveler explicitement en vous reconnectant à votre compte IAM Identity Center à l'aide du. AWS CLI
Par exemple, vous pouvez créer un profil`dev-profile`, authentifier et autoriser ce profil à l'aide du AWS CLI, et configurer votre application comme indiqué ci-dessous.
1. Créez d'abord le `profile` et `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. Connectez-vous AWS CLI à l'aide du pour authentifier et autoriser le profil 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. Configurez ensuite votre application pour utiliser le profil 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
}
```
Pour plus d'informations sur la configuration des profils SSO et l'authentification à l'aide de la AWS CLI section [Configuration du AWS CLI à utiliser AWS IAM Identity Center dans le](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) Guide de l' AWS CLI utilisateur. Pour plus d'informations sur la création programmatique du fournisseur d'informations d'identification SSO, consultez la documentation de référence de l'API [ssocreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds).
#### Identifiants de connexion
Vous pouvez utiliser vos identifiants de connexion existants à la console de AWS gestion pour accéder aux AWS services par programmation. Après un flux d'authentification basé sur un navigateur, AWS génère des informations d'identification temporaires qui fonctionnent avec les outils de développement locaux tels que la AWS CLI et Outils AWS pour PowerShell . AWS SDKs Cette fonctionnalité simplifie le processus de configuration et de gestion des informations d'identification de la AWS CLI, en particulier si vous préférez l'authentification interactive à la gestion des clés d'accès à long terme.
1. Lancez le flux de connexion à l'aide de la AWS CLI et suivez les instructions du navigateur. Dans cet exemple, nous enregistrons la session de connexion dans un nouveau profil**dev-profile**, mais cela est facultatif.
```
$ aws --profile dev-profile login
```
1. (Facultatif) Inspectez votre fichier de configuration AWS partagé pour vérifier que la session a été établie.
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. Configurez ensuite votre application pour utiliser le profil de connexion.
```
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
}
```
Pour plus d'informations sur la configuration des profils de connexion et l'authentification à l'aide de la AWS CLI, voir [Connexion pour le développement AWS local à l'aide des informations d'identification de console](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html).
#### Autres fournisseurs d'informations d'identification
Le SDK fournit d'autres méthodes pour récupérer les informations d'identification dans le module des informations d'[identification](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials). Par exemple, vous pouvez récupérer des informations d'identification de sécurité temporaires AWS Security Token Service ou des informations d'identification provenant d'un stockage crypté.
**Fournisseurs d'informations d'identification disponibles** :
+ [ec2rolecreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds) — Récupérez les informations d'identification des rôles des instances Amazon EC2 via Amazon EC2 IMDS.
+ [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds) — Récupère les informations d'identification d'un point de terminaison HTTP arbitraire.
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds) — Récupère les informations d'identification d'un processus externe qui sera invoqué par le shell de l'environnement hôte.
+ [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) — Récupère les informations d'identification depuis AWS STS
# Configuration de l'authentification
Permet AWS SDK pour Go de configurer le service de comportement d'authentification. Dans la plupart des cas, la configuration par défaut suffit, mais la configuration de l'authentification personnalisée permet d'adopter des comportements supplémentaires, tels que l'utilisation de fonctionnalités de service préliminaires.
## Définitions
Cette section fournit une description détaillée des composants d'authentification du AWS SDK pour Go.
### AuthScheme
An [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)est l'interface qui définit le flux de travail par lequel le SDK récupère l'identité de l'appelant et l'associe à une demande d'opération.
Un schéma d'authentification utilise les composants suivants, décrits en détail ci-dessous :
+ Un identifiant unique qui identifie le schéma
+ Un résolveur d'identité, qui renvoie l'identité de l'appelant utilisée lors du processus de signature (par exemple, vos AWS informations d'identification)
+ Un signataire, qui effectue l'injection effective de l'identité de l'appelant dans la demande de transport de l'opération (par exemple, l'en-tête `Authorization` HTTP)
Les options de chaque client de service incluent un `AuthSchemes` champ qui est renseigné par défaut avec la liste des schémas d'authentification pris en charge par ce service.
### AuthSchemeResolver
Les options de chaque service client incluent un `AuthSchemeResolver` champ. Cette interface, définie par service, est l'API appelée par le SDK pour déterminer les options d'authentification possibles pour chaque opération.
**Important**
Le résolveur de schéma d'authentification ne dicte PAS quel schéma d'authentification est utilisé. Il renvoie une liste de schémas *pouvant* être utilisés (« options »), le schéma final est sélectionné via un algorithme fixe décrit [ici](#auth-scheme-resolution-workflow).
### Option
Retournée par un appel à`ResolverAuthSchemes`, une [option](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) représente une option d'authentification possible.
Une option comprend trois ensembles d'informations :
+ Un identifiant représentant le schéma possible
+ Un ensemble opaque de propriétés à fournir au résolveur d'identité du schéma
+ Un ensemble opaque de propriétés à fournir au signataire du schéma
#### Remarque sur les propriétés
Dans 99 % des cas d'utilisation, les appelants n'ont pas à se soucier des propriétés opaques de résolution d'identité et de signature. Le SDK extraira les propriétés nécessaires pour chaque schéma et les transmettra aux interfaces fortement typées exposées dans le SDK. [Par exemple, le résolveur d'authentification par défaut pour les services code l'option SigV4 afin d'avoir des propriétés de signature pour le nom et la région de signature, dont les valeurs sont transmises au v4 configuré par le client. HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option)mise en œuvre lorsque SigV4 est sélectionné.
### Identity
Une [identité](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) est une représentation abstraite de l'identité de l'appelant du SDK.
Le type d'identité le plus couramment utilisé dans le SDK est un ensemble de`aws.Credentials`. Dans la plupart des cas d'utilisation, l'appelant n'a pas à se préoccuper `Identity` d'une abstraction et peut travailler directement avec les types concrets.
**Note**
Pour préserver la rétrocompatibilité et éviter toute confusion entre les API, le type d'identité AWS spécifique au SDK `aws.Credentials` ne correspond pas directement à l'interface. `Identity` Ce mappage est géré en interne.
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver)est l'interface par laquelle un `Identity` est récupéré.
[Des versions concrètes de `IdentityResolver` existent dans le SDK sous une forme fortement typée (par exemple aws. CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)), le SDK gère ce mappage en interne.
L'appelant n'aura qu'à implémenter directement l'`IdentityResolver`interface lors de la définition d'un schéma d'authentification externe.
### Signer
Le [signataire](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) est l'interface par laquelle une demande est complétée par l'appelant `Identity` récupéré.
[Des versions concrètes de `Signer` existent dans le SDK sous une forme fortement typée (par exemple v4. HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner)), le SDK gère ce mappage en interne.
L'appelant n'aura qu'à implémenter directement l'`Signer`interface lors de la définition d'un schéma d'authentification externe.
### AuthResolverParameters
Chaque service utilise un ensemble spécifique d'entrées qui sont transmises à sa fonction de résolution, définie dans chaque package de services comme`AuthResolverParameters`.
Les paramètres du résolveur de base sont les suivants :
| name | type | description |
| --- | --- | --- |
| Operation | string | Nom de l'opération invoquée. |
| Region | string | La AWS région du client. Présent uniquement pour les services utilisant SigV4 [A]. |
Si vous implémentez votre propre résolveur, vous ne devriez jamais avoir à créer votre propre instance à partir de ses paramètres. Le SDK fournira ces valeurs par demande et les transmettra à votre implémentation.
## Flux de travail de résolution du schéma d'authentification
Lorsque vous appelez une opération de AWS service via le SDK, la séquence d'actions suivante se produit après la sérialisation de la demande :
1. Le SDK appelle l'`AuthSchemeResolver.ResolveAuthSchemes()`API du client, en fournissant les paramètres d'entrée nécessaires, afin d'obtenir une liste des [options](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) possibles pour l'opération.
1. Le SDK parcourt cette liste et sélectionne le premier schéma qui répond aux conditions suivantes.
+ Un schéma avec l'ID correspondant est présent dans la propre `AuthSchemes` liste du client
+ Le résolveur d'identité du schéma existe (n'est pas-`nil`) dans les options du client (vérifié via la `GetIdentityResolver` méthode du schéma, le mappage vers les types de résolveurs d'identité concrets décrits ci-dessus est géré en interne) (1)
1. En supposant qu'un schéma viable ait été sélectionné, le SDK invoque son `GetIdentityResolver()` API pour récupérer l'identité de l'appelant. Par exemple, le schéma d'authentification SigV4 intégré sera mappé au fournisseur du `Credentials` client en interne.
1. Le SDK appelle le résolveur d'identité `GetIdentity()` (par exemple `aws.CredentialProvider.Retrieve()` pour SigV4).
1. Le SDK appelle le résolveur du point de terminaison `ResolveEndpoint()` pour trouver le point de terminaison correspondant à la demande. Le point de terminaison peut inclure des métadonnées supplémentaires qui influencent le processus de signature (par exemple, un nom de signature unique pour S3 Object Lambda).
1. Le SDK appelle l'`Signer()`API du schéma d'authentification pour récupérer son signataire et utilise son `SignRequest()` API pour signer la demande avec l'identité de l'appelant précédemment récupérée.
(1) Si le SDK trouve l'option anonyme (ID`smithy.api#noAuth`) dans la liste, il est sélectionné automatiquement, car il n'existe aucun résolveur d'identité correspondant.
## Supportés nativement `AuthScheme`
Les schémas d'authentification suivants sont pris en charge nativement par. AWS SDK pour Go
| Nom | ID du schéma | Résolveur d'identité | Signer | Remarques |
| --- | --- | --- | --- | --- |
| [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | aws.auth\$1sigv4 | [aws. 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) | Valeur par défaut actuelle pour la plupart des opérations AWS de service. |
| SigV4A | aws.auth\$1sigv4a | aws. CredentialsProvider | N/A | L'utilisation de SigV4a est limitée pour le moment, l'implémentation du signataire est interne. Consultez cette [annonce](https://github.com/aws/aws-sdk-go-v2/discussions/2812) pour un nouveau module opt-in aws-http-authqui expose l'usage général de la signature APIs de requêtes HTTP. |
| SIGV4 Express | com.amazonaws.s3\$1sigv4express | [s3. ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4. HTTPSigner | Utilisé pour [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). |
| Support HTTP | smithy.api\$1httpBearerAuth | [forgeron. TokenProvider](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#TokenProvider) | [SmithyBearer.Signataire](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#Signer) | Utilisé par [Codecatalyst](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst). |
| Anonyme | smithy.api\$1noAuth | N/A | s/o | Aucune authentification : aucune identité n'est requise et la demande n'est ni signée ni authentifiée. |
### Configuration de l'identité
Dans AWS SDK pour Go, les composants d'identité d'un schéma d'authentification sont configurés dans le client SDK. `Options` Le SDK récupère et utilise automatiquement les valeurs de ces composants pour le schéma qu'il sélectionne lorsqu'une opération est appelée.
**Note**
Pour des raisons de rétrocompatibilité, le SDK autorise implicitement l'utilisation du schéma d'authentification anonyme si aucun résolveur d'identité n'est configuré. Cela peut être réalisé manuellement en configurant tous les résolveurs d'identité sur le point d'un client `Options` `nil` (le résolveur d'identité sigv4 peut également être réglé sur). `aws.AnonymousCredentials{}`
### Configuration du signataire
Dans AWS SDK pour Go, les composants signataires d'un schéma d'authentification sont configurés dans le client SDK. `Options` Le SDK récupère et utilise automatiquement les valeurs de ces composants pour le schéma qu'il sélectionne lorsqu'une opération est appelée. Aucune configuration supplémentaire n'est nécessaire.
#### Schéma d'authentification personnalisé
Afin de définir un schéma d'authentification personnalisé et de le configurer en vue de son utilisation, l'appelant doit effectuer les opérations suivantes :
1. Définition d'une [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)implémentation
1. Enregistrez le schéma dans la liste des clients du `AuthSchemes` SDK
1. Instrumentez le client du SDK `AuthSchemeResolver` pour renvoyer une authentification `Option` avec l'ID du schéma, le cas échéant
**Avertissement**
Les services suivants ont un comportement d'authentification unique ou personnalisé. Nous vous recommandons de déléguer à l'implémentation par défaut et d'encapsuler en conséquence si vous avez besoin d'un comportement d'authentification personnalisé :
| Service | Remarques |
| --- | --- |
| S3 | Utilisation conditionnelle de SigV4A et SIGV4Express en fonction de l'entrée de l'opération. |
| EventBridge | Utilisation conditionnelle de SigV4A en fonction de l'entrée de l'opération. |
| Cognito | Certaines opérations sont uniquement anonymes. |
| SSO | Certaines opérations sont uniquement anonymes. |
| STS | Certaines opérations sont uniquement anonymes. |
# Configuration des points de terminaison clients
**Avertissement**
La résolution des points de terminaison est une rubrique avancée du SDK. En modifiant ces paramètres, vous risquez de casser votre code. Les paramètres par défaut doivent être applicables à la plupart des utilisateurs dans les environnements de production.
AWS SDK pour Go Permet de configurer un point de terminaison personnalisé à utiliser pour un service. Dans la plupart des cas, la configuration par défaut suffit. La configuration de points de terminaison personnalisés permet d'adopter des comportements supplémentaires, tels que l'utilisation de versions préliminaires d'un service.
## Personnalisation
Il existe deux « versions » de la configuration de résolution des points de terminaison dans le SDK.
+ v2, sortie au troisième trimestre 2023, configurée via :
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1, publié en même temps que le SDK, configuré via :
+ `EndpointResolver`
Nous recommandons aux utilisateurs de la version v1 de la solution des terminaux de migrer vers la version v2 pour avoir accès aux nouvelles fonctionnalités de service liées aux terminaux.
## V2 : `EndpointResolverV2` \$1 `BaseEndpoint`
Dans la résolution v2, `EndpointResolverV2` c'est le mécanisme définitif par lequel la résolution du point final se produit. La `ResolveEndpoint` méthode du résolveur est invoquée dans le cadre du flux de travail pour chaque demande que vous effectuez dans le SDK. Le nom d'hôte `Endpoint` renvoyé par le résolveur est utilisé **tel quel** lors de la demande (les sérialiseurs d'opérations peuvent toutefois toujours être ajoutés au chemin HTTP).
La résolution v2 inclut une configuration supplémentaire au niveau du client`BaseEndpoint`, qui est utilisée pour spécifier un nom d'hôte « de base » pour l'instance de votre service. La valeur définie ici n'est pas définitive : elle est finalement transmise en tant que paramètre au client `EndpointResolverV2` lors de la résolution finale (lisez la suite pour plus d'informations sur `EndpointResolverV2` les paramètres). L'implémentation du résolveur a alors la possibilité d'inspecter et éventuellement de modifier cette valeur pour déterminer le point final.
Par exemple, si vous effectuez une `GetObject` requête S3 sur un compartiment donné avec un client pour lequel vous avez spécifié un`BaseEndpoint`, le résolveur par défaut injectera le bucket dans le nom d'hôte s'il est compatible avec l'hôte virtuel (en supposant que vous n'avez pas désactivé l'hébergement virtuel dans la configuration du client).
En pratique, il `BaseEndpoint` sera très probablement utilisé pour diriger votre client vers une instance de développement ou de prévisualisation d'un service.
### Paramètres dans l’`EndpointResolverV2`
Chaque service utilise un ensemble spécifique d'entrées qui sont transmises à sa fonction de résolution, définie dans chaque package de services comme`EndpointParameters`.
Chaque service inclut les paramètres de base suivants, qui sont utilisés pour faciliter la résolution générale des terminaux au sein de AWS :
| name | type | description |
| --- | --- | --- |
| Region | string | La AWS région du client |
| Endpoint | string | La valeur définie pour BaseEndpoint dans la configuration du client |
| UseFips | bool | Si les points de terminaison FIPS sont activés dans la configuration du client |
| UseDualStack | bool | Si les points de terminaison à double pile sont activés dans la configuration du client |
Les services peuvent spécifier des paramètres supplémentaires requis pour la résolution. Par exemple, les S3 `EndpointParameters` incluent le nom du compartiment, ainsi que plusieurs paramètres de fonctionnalités spécifiques à S3, tels que l'activation de l'adressage des hôtes virtuels.
Si vous implémentez la vôtre`EndpointResolverV2`, vous ne devriez jamais avoir à créer votre propre instance de`EndpointParameters`. Le SDK fournira les valeurs par demande et les transmettra à votre implémentation.
### Remarque à propos d'Amazon S3
Amazon S3 est un service complexe dont bon nombre de fonctionnalités sont modélisées par le biais de personnalisations complexes des terminaux, telles que l'hébergement virtuel de compartiments, le MRAP S3, etc.
Pour cette raison, nous vous recommandons de ne pas remplacer l'`EndpointResolverV2`implémentation dans votre client S3. Si vous devez étendre son comportement de résolution, par exemple en envoyant des requêtes à une pile de développement locale en tenant compte des points de terminaison supplémentaires, nous vous recommandons d'encapsuler l'implémentation par défaut de manière à ce qu'elle revienne à la valeur par défaut en tant que solution de secours (voir les exemples ci-dessous).
### Exemples
#### Avec `BaseEndpoint`
L'extrait de code suivant montre comment pointer votre client S3 vers une instance locale d'un service qui, dans cet exemple, est hébergée sur le périphérique de bouclage sur le port 8080.
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### Avec `EndpointResolverV2`
L'extrait de code suivant montre comment injecter un comportement personnalisé dans la résolution du point de terminaison de S3 en utilisant. `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{
// ...
}
})
}
```
#### Avec les deux
L'exemple de programme suivant illustre l'interaction entre `BaseEndpoint` et`EndpointResolverV2`. **Il s'agit d'un cas d'utilisation avancé :**
```
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)
}
```
Lorsqu'il est exécuté, le programme ci-dessus produit ce qui suit :
```
The endpoint provided in config is https://endpoint.dev/
```
## V1 : `EndpointResolver`
**Avertissement**
La résolution du point de terminaison v1 est conservée pour des raisons de rétrocompatibilité et est isolée du comportement moderne de la résolution du point de terminaison v2. Il ne sera utilisé que si le `EndpointResolver` champ est défini par l'appelant.
L'utilisation de la version 1 vous empêchera très probablement d'accéder aux fonctionnalités de service liées aux terminaux introduites avec ou après la publication de la résolution v2. Reportez-vous à la section « Migration » pour obtenir des instructions sur la procédure de mise à niveau.
A [EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver)peut être configuré pour fournir une logique de résolution des points de terminaison personnalisée aux clients du service. Vous pouvez utiliser un résolveur de point de terminaison personnalisé pour remplacer la logique de résolution de point de terminaison d'un service pour tous les points de terminaison ou uniquement pour un point de terminaison régional spécifique. Le résolveur de point de terminaison personnalisé peut déclencher la logique de résolution de point de terminaison du service pour revenir en arrière si un résolveur personnalisé ne souhaite pas résoudre un point de terminaison demandé. [EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc)peut être utilisé pour encapsuler facilement des fonctions afin de satisfaire l'`EndpointResolverWithOptions`interface.
A `EndpointResolver` peut être facilement configuré en transmettant le résolveur encapsulé [WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions)à [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), ce qui permet de remplacer les points de terminaison lors du chargement des informations d'identification, ainsi qu'en configurant le résultat `aws.Config` avec votre résolveur de point de terminaison personnalisé.
Le résolveur de point de terminaison reçoit le service et la région sous forme de chaîne, ce qui permet au résolveur de piloter dynamiquement son comportement. Chaque package de client de service possède une `ServiceID` constante exportée qui peut être utilisée pour déterminer quel client de service appelle votre résolveur de point de terminaison.
Un résolveur de point de terminaison peut utiliser la valeur d'erreur [EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError)sentinelle pour déclencher une résolution de repli selon la logique de résolution par défaut du client du service. Cela vous permet de remplacer de manière sélective un ou plusieurs points de terminaison de manière fluide sans avoir à gérer une logique de repli.
Si l'implémentation de votre résolveur de point de terminaison renvoie une erreur autre que`EndpointNotFoundError`, la résolution de point de terminaison s'arrête et le fonctionnement du service renvoie une erreur à votre application.
### Exemples
#### Avec solution de repli
L'extrait de code suivant montre comment un point de terminaison de service unique peut être remplacé pour DynamoDB par un comportement de remplacement pour les autres points de terminaison :
```
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))
```
#### Sans solution de repli
L'extrait de code suivant montre comment un seul point de terminaison de service peut être remplacé pour DynamoDB sans adopter de comportement de remplacement pour les autres points de terminaison :
```
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))
```
### Points de terminaison immuables
**Avertissement**
Le fait de définir un point de terminaison comme immuable peut empêcher certaines fonctionnalités du client de service de fonctionner correctement et entraîner un comportement indéfini. Il convient de faire preuve de prudence lorsque vous définissez un point de terminaison comme immuable.
Certains clients de service, tels qu'Amazon S3, peuvent modifier le point de terminaison renvoyé par le résolveur pour certaines opérations de service. Par exemple, Amazon S3 gérera automatiquement l'[adressage du compartiment virtuel](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) en mutant le point de terminaison résolu. Vous pouvez empêcher le SDK de modifier vos points de terminaison personnalisés en réglant sur. [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)`true` Par exemple :
```
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))
```
## Migration
Lors de la migration de la version v1 vers la version v2 de la résolution des terminaux, les principes généraux suivants s'appliquent :
+ Le renvoi d'un [point de terminaison](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) avec [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)défini sur `false` équivaut à peu près `BaseEndpoint` à définir l'URL initialement renvoyée par la version v1 et à la laisser `EndpointResolverV2` comme URL par défaut.
+ Le renvoi d'un point de terminaison HostnameImmutable défini sur `true` équivaut à peu près à l'implémentation d'un `EndpointResolverV2` qui renvoie l'URL initialement renvoyée par la v1.
+ La principale exception concerne les opérations utilisant des préfixes de point de terminaison modélisés. Une note à ce sujet figure plus bas.
Des exemples de ces cas sont fournis ci-dessous.
**Avertissement**
Les points de terminaison immuables V1 et la résolution V2 n'ont pas un comportement équivalent. Par exemple, les remplacements de signature pour des fonctionnalités personnalisées telles que S3 Object Lambda seraient toujours définis pour les points de terminaison immuables renvoyés via le code v1, mais il n'en serait pas de même pour la v2.
### Remarque sur les préfixes d'hôte
Certaines opérations sont modélisées avec des préfixes d'hôte à ajouter au point de terminaison résolu. Ce comportement doit fonctionner en tandem avec la sortie de ResolveEndpoint V2 et, par conséquent, le préfixe hôte sera toujours appliqué à ce résultat.
Vous pouvez désactiver manuellement le préfixation de l'hôte du point de terminaison en appliquant un intergiciel, voir la section des exemples.
### Exemples
#### Point de terminaison mutable
L'exemple de code suivant montre comment migrer un résolveur de point de terminaison v1 de base qui renvoie un point de terminaison modifiable :
```
// 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/")
})
```
#### Point de terminaison immuable
```
// 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{}
})
```
#### Désactiver le préfixe d'hôte
```
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)
}
}
```
# Personnalisation du client HTTP
AWS SDK pour Go Utilise un client HTTP par défaut avec des valeurs de configuration par défaut. Bien que vous puissiez modifier certaines de ces valeurs de configuration, le client et le transport HTTP par défaut ne sont pas suffisamment configurés pour les clients utilisant le AWS SDK pour Go dans un environnement présentant des exigences de débit élevé et de faible latence. Pour plus d'informations, reportez-vous au [Questions fréquentes (FAQ)](faq-gosdk.md) car les recommandations de configuration varient en fonction des charges de travail spécifiques. Cette section décrit comment configurer un client HTTP personnalisé et comment utiliser ce client pour créer des AWS SDK pour Go appels.
Pour vous aider à créer un client HTTP personnalisé, cette section décrit comment [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient)configurer des paramètres personnalisés et comment utiliser ce client avec un client de AWS SDK pour Go service.
Définissons ce que nous voulons personnaliser.
## Remplacement lors du chargement de la configuration
Des clients HTTP personnalisés peuvent être fournis lors d'un appel [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig)en encapsulant le client à l'aide de la HTTPClient touche [With](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) et en transmettant la valeur résultante à`LoadDefaultConfig`. Par exemple, pour nous faire passer `customClient` pour notre client :
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## Expiration
Il `BuildableHTTPClient` peut être configuré avec une limite de délai d'expiration des demandes. Ce délai inclut le temps nécessaire pour se connecter, traiter les redirections et lire le corps de la réponse dans son intégralité. Par exemple, pour modifier le délai d'expiration du client :
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## composeur
`BuildableHTTPClient`Il fournit un mécanisme de création pour créer des clients avec des options de [numérotation](https://golang.org/pkg/net/#Dialer) modifiées. L'exemple suivant montre comment configurer les `Dialer` paramètres d'un client.
```
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
})
```
### Paramètres
#### composeur. KeepAlive
Ce paramètre représente la durée de conservation d'une connexion réseau active.
Réglez sur une valeur négative pour désactiver Keep-alives.
Définissez cette valeur sur **0** pour activer Keep-Alives si le protocole et le système d'exploitation le prennent en charge.
Les protocoles réseau ou les systèmes d'exploitation qui ne prennent pas en charge le mode Keep-Alives ignorent ce champ. Par défaut, le protocole TCP active Keep Alive.
Voir [https://golang. org/pkg/net/\$1Dialer. KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive)
Définissez `KeepAlive` comme **time.Duration.**
#### Dialer.Timeout
Ce paramètre représente la durée maximale pendant laquelle un cadran attend qu'une connexion soit créée.
La valeur par défaut est de 30 secondes.
Voir [https://golang. org/pkg/net/\$1Dialer .Délai](https://golang.org/pkg/net/#Dialer.Timeout) d'expiration
Définissez `Timeout` comme **time.Duration.**
## Transport
`BuildableHTTPClient`Il fournit un mécanisme de création pour créer des clients avec des options de [transport](https://golang.org/pkg/net/http#Transport) modifiées.
### Configuration d'un proxy
Si vous ne pouvez pas vous connecter directement à Internet, vous pouvez utiliser les variables d'environnement prises en charge par GO (`HTTP_PROXY`/`HTTPS_PROXY`) ou créer un client HTTP personnalisé pour configurer votre proxy. L'exemple suivant configure le client à utiliser `PROXY_URL` comme point de terminaison du 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)
})
```
### Autres paramètres
Vous trouverez ci-dessous quelques autres `Transport` paramètres qui peuvent être modifiés pour régler le client HTTP. Tous les paramètres supplémentaires non décrits ici se trouvent dans la documentation du type de [transport](https://golang.org/pkg/net/http/#Transport). Ces paramètres peuvent être appliqués comme indiqué dans l'exemple suivant :
```
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
})
```
#### Transport. ExpectContinueTimeout
Si la demande comporte un en-tête « Expect : 100-continue », ce paramètre représente le temps maximum d'attente pour les premiers en-têtes de réponse d'un serveur après avoir entièrement écrit les en-têtes de demande. Ce délai n'inclut pas le temps d'envoi de l'en-tête de demande. Le client HTTP envoie sa charge utile une fois ce délai expiré.
Par défaut, 1 seconde.
Réglez sur **0** pour éviter tout délai d'expiration et envoyer la charge utile de la demande sans attendre. L'un des cas d'utilisation est celui où vous rencontrez des problèmes avec des proxys ou des services tiers qui prennent une session similaire à l'utilisation d'Amazon S3 dans la fonction illustrée plus loin.
Voir [https://golang. org/pkg/net/http/\$1Transport. ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout)
Définissez `ExpectContinue` comme **time.Duration.**
#### Transport. IdleConnTimeout
Ce paramètre représente la durée maximale pendant laquelle une connexion réseau inactive est maintenue entre les requêtes HTTP.
Réglez sur **0** pour une limite illimitée.
Voir [https://golang. org/pkg/net/http/\$1Transport. IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout)
Définissez `IdleConnTimeout` comme **time.Duration.**
#### Transport. MaxIdleConns
Ce paramètre représente le nombre maximum de connexions inactives (maintenues actives) sur tous les hôtes. Un cas d'utilisation pour augmenter cette valeur est lorsque vous constatez de nombreuses connexions en peu de temps provenant des mêmes clients
**0** signifie qu'il n'y a pas de limite.
Voir [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns)
`MaxIdleConns`Défini comme **int**.
#### Transport. MaxIdleConnsPerHost
Ce paramètre représente le nombre maximum de connexions inactives (maintenues actives) à conserver par hôte. Un cas d'utilisation pour augmenter cette valeur est lorsque vous constatez de nombreuses connexions en peu de temps provenant des mêmes clients
La valeur par défaut est de deux connexions inactives par hôte.
Réglez sur **0** pour utiliser DefaultMaxIdleConnsPerHost (2).
Voir [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost)
`MaxIdleConnsPerHost`Défini comme **int**.
#### Transport. ResponseHeaderTimeout
Ce paramètre représente le délai maximal d'attente avant qu'un client lise l'en-tête de réponse.
Si le client n'est pas en mesure de lire l'en-tête de la réponse pendant cette durée, la demande échoue avec une erreur de temporisation.
Veillez à définir cette valeur lorsque vous utilisez des fonctions Lambda de longue durée, car l'opération ne renvoie aucun en-tête de réponse tant que la fonction Lambda n'est pas terminée ou que le délai imparti n'est pas expiré. Cependant, vous pouvez toujours utiliser cette option avec l'opération d'API InvokeAsync \$1\$1 \$1\$1.
Par défaut, il n'y a pas de délai d'attente ; attendez indéfiniment.
Voir [https://golang. org/pkg/net/http/\$1Transport. ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout)
Définissez `ResponseHeaderTimeout` comme **time.Duration.**
#### Transport. TLSHandshakeDélai d'expiration
Ce paramètre représente la durée maximale d'attente avant la fin d'une poignée de main TLS.
La valeur par défaut est de 10 secondes.
Zéro signifie qu'il n'y a aucun délai d'attente.
Voir [https://golang. org/pkg/net/http/\$1Transport. TLSHandshakeDélai d'expiration](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout)
Définissez `TLSHandshakeTimeout` comme **time.Duration.**
# Intercepteurs HTTP
Vous pouvez utiliser des intercepteurs pour vous connecter à l'exécution des demandes et réponses d'API. Les intercepteurs sont des mécanismes ouverts dans lesquels le SDK appelle le code que vous écrivez pour injecter du comportement dans le request/response cycle de vie. De cette façon, vous pouvez modifier une demande en cours de vol, le traitement d'une demande de débogage, consulter les exceptions, etc.
## Intercepteurs et intergiciels
La AWS SDK pour Go v2 fournit à la fois des intercepteurs et des intergiciels pour personnaliser le traitement des demandes. Bien que les deux aient des objectifs similaires, ils sont conçus pour des publics et des cas d'utilisation différents :
+ Les **intercepteurs** sont conçus pour les utilisateurs du SDK qui souhaitent personnaliser le request/response traitement à l'aide d'une API simple axée sur le protocole HTTP. Ils fournissent des points d'accroche spécifiques dans le cycle de vie des demandes et fonctionnent directement avec les requêtes et réponses HTTP.
+ Le **middleware** est un système plus avancé, indépendant du transport, principalement utilisé en interne par le SDK. Bien que puissant, le middleware nécessite une connaissance approfondie des composants internes du SDK et implique des interfaces plus complexes.
Principaux avantages des intercepteurs par rapport aux intergiciels pour les cas d'utilisation courants :
+ **Axé sur le protocole HTTP** : les intercepteurs fonctionnent directement avec les requêtes et réponses HTTP, ce qui élimine le besoin de vérifier le type de transport requis par le middleware.
+ **Interfaces plus simples** : chaque hook d'interception possède une interface spécifique et ciblée plutôt que le modèle générique de middleware.
+ **Modèle d'exécution plus clair** : les intercepteurs s'exécutent à des moments bien définis du cycle de vie des demandes sans qu'il soit nécessaire de connaître l'ordre des piles d'intergiciels.
**Note**
Les intercepteurs sont basés sur le système intergiciel existant, de sorte que les deux peuvent coexister dans la même application. Le middleware reste disponible pour les cas d'utilisation avancés nécessitant un comportement indépendant du transport ou une manipulation complexe des piles.
## Crochets d'interception disponibles
La AWS SDK pour Go v2 fournit des crochets d'interception à différentes étapes du cycle de vie des demandes. Chaque hook correspond à une interface spécifique que vous pouvez implémenter :
+ `BeforeExecution`- Premier hook appelé lors de l'exécution de l'opération
+ `BeforeSerialization`- Avant que le message d'entrée ne soit sérialisé dans la demande de transport
+ `AfterSerialization`- Une fois le message d'entrée sérialisé dans la demande de transport
+ `BeforeRetryLoop`- Avant d'entrer dans la boucle de nouvelle tentative
+ `BeforeAttempt`- Premier crochet appelé boucle de réessai intérieure
+ `BeforeSigning`- Avant la signature de la demande de transport
+ `AfterSigning`- Après signature de la demande de transport
+ `BeforeTransmit`- Avant l'envoi de la demande de transport
+ `AfterTransmit`- Après réception de la réponse du transport
+ `BeforeDeserialization`- Avant que la réponse au transport ne soit désérialisée
+ `AfterDeserialization`- Après avoir désorganisé la réponse du transport
+ `AfterAttempt`- Dernier crochet appelé boucle de réessai intérieure
+ `AfterExecution`- Dernier hook appelé lors de l'exécution de l'opération
Vous pouvez implémenter plusieurs interfaces dans un seul intercepteur afin de vous connecter à plusieurs étapes du cycle de vie des demandes.
## Enregistrement de l'intercepteur
Vous enregistrez des intercepteurs lorsque vous créez un client de service ou lorsque vous remplacez la configuration pour une opération spécifique. L'enregistrement varie selon que vous souhaitez que l'intercepteur s'applique à toutes les opérations pour votre client ou uniquement à des opérations spécifiques.
Les intercepteurs sont gérés via un registre d'intercepteurs qui fournit des méthodes pour ajouter et supprimer des intercepteurs. L'exemple suivant montre un intercepteur simple qui ajoute un en-tête AWS X-Ray trace ID aux demandes sortantes avant le processus de signature :
```
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{})
})
```
Le registre des intercepteurs est ajouté aux options du client, ce qui permet de configurer l'intercepteur par opération :
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## Configuration globale de l'intercepteur
Vous pouvez également enregistrer les intercepteurs globalement à l'aide de la `config.LoadDefaultConfig` fonction avec les `With*` options appropriées pour chaque type d'intercepteur. Cela applique l'intercepteur à tous les clients AWS de service créés à partir de cette configuration :
```
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)
```
# Journalisation
AWS SDK pour Go Il dispose de fonctionnalités de journalisation qui permettent à votre application d'activer les informations de débogage pour le débogage et le diagnostic des problèmes ou des échecs liés aux demandes. L'interface [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) et ce [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)sont les principaux composants à votre disposition pour déterminer comment et ce qui doit être enregistré par les clients.
## Logger
Lors de la construction d'une [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)une configuration par défaut `Logger` est configurée pour envoyer des messages de journal à l'erreur standard du processus (stderr). [Un enregistreur personnalisé qui répond à l'interface [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) peut être transmis en tant qu'argument en l'`LoadDefaultConfig`enveloppant avec config. WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger).
Par exemple, pour configurer nos clients afin qu'ils utilisent notre `applicationLogger` :
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
Désormais, les clients configurés à l'aide de la construction `aws.Config` enverront des messages de journal à`applicationLogger`.
### Enregistreurs sensibles au contexte
Une implémentation de Logger peut implémenter l'[ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger)interface optionnelle. Les `WithContext` méthodes des enregistreurs qui implémentent cette interface seront invoquées dans le contexte actuel. Cela permet à vos implémentations de journalisation de renvoyer un nouveau `Logger` qui peut écrire des métadonnées de journalisation supplémentaires en fonction des valeurs présentes dans le contexte.
## ClientLogMode
Par défaut, les clients du service ne produisent pas de messages de journal. Pour configurer les clients afin qu'ils envoient des messages de journal à des fins de débogage, utilisez le [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)membre on`Config`. `ClientLogMode`peut être configuré pour activer les messages de débogage pour :
+ Signature version 4 (SigV4)
+ Demander de nouvelles tentatives
+ Requêtes HTTP
+ Réponses HTTP
Par exemple, pour activer la journalisation des requêtes et des tentatives HTTP :
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
Consultez [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)les différents modes de journalisation des clients disponibles.
# Traces et métriques
AWS SDK pour Go Il est instrumenté pour enregistrer les intervalles de suivi et les métriques côté client pour les opérations du SDK. Par défaut, les clients utilisent des implémentations non opérationnelles pour le suivi et les métriques, ce qui signifie qu'aucune donnée n'est collectée sauf si vous configurez un fournisseur.
Les clients du service disposent de deux options de configuration pour l'observabilité :
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider)— Point d'entrée pour créer des traceurs et enregistrer les intervalles de suivi des clients.
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider)— Point d'entrée pour créer des compteurs et enregistrer les mesures côté client.
Bien qu'inspirées des spécifications OpenTelemetry (OTel), celles-ci APIs sont définies indépendamment dans`smithy-go`. Le SDK fournit des modules adaptateurs pour connecter des implémentations concrètes du OTel SDK aux interfaces du fournisseur du SDK.
## Tracing
Utilisez le module adaptateur [smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) pour connecter un OTel `trace.TracerProvider` à un client de service.
L'exemple suivant montre comment configurer le suivi pour 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)
})
```
Les opérations du SDK sont instrumentées selon une hiérarchie d'intervalles qui couvre les composants de haut niveau du cycle de vie des opérations, tels que la sérialisation des demandes, la signature et la boucle de nouvelle tentative.
## Métriques
Utilisez le module adaptateur [smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) pour connecter un OTel `metric.MeterProvider` à un client de service.
L'exemple suivant montre comment configurer les métriques pour 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)
})
```
### Métriques prises en charge
Les clients du SDK collectent les métriques suivantes :
| Nom de la métrique | Unit | Type | Description |
| --- | --- | --- | --- |
| client.call.duration | s | Histogramme | Durée totale de l'appel, y compris les nouvelles tentatives, le temps d'envoi ou de réception de la demande et le corps de réponse. |
| client.call.attempts | \$1tentative\$1 | MonotonicCounter | Nombre de tentatives pour une opération individuelle. |
| client.call.errors | \$1erreur\$1 | MonotonicCounter | Le nombre d'erreurs associées à une opération. |
| client.call.attempt\$1duration | s | Histogramme | Le temps nécessaire pour se connecter au service, envoyer la demande et récupérer le code d'état HTTP et les en-têtes (y compris le temps passé en attente d'envoi). |
| client.call.resolve\$1endpoint\$1duration | s | Histogramme | Durée de résolution d'un point de terminaison (résolveur de point de terminaison, pas DNS) pour la demande. |
| client.call.deserialization\$1duration | s | Histogramme | C'est le moment de désérialiser le corps d'un message. |
| client.call.auth.signing\$1duration | s | Histogramme | C'est le moment de signer une demande. |
| client.call.auth.resolve\$1identity\$1duration | s | Histogramme | Le moment d'acquérir une identité (AWS informations d'identification, jeton porteur, etc.) auprès d'un fournisseur d'identité. |
Les attributs (dimensions) suivants sont inclus dans chaque métrique, le cas échéant :
+ `rpc.service`— Le nom du service.
+ `rpc.method`— Le nom de l'opération.
+ `exception.type`— Le type d'erreur (inclus dans`client.call.errors`).
+ `auth.scheme_id`— Le schéma d'authentification (inclus dans les métriques relatives à l'authentification).
### Métriques du client HTTP
Le client HTTP du SDK collecte les mesures supplémentaires suivantes relatives au cycle de vie de la connexion HTTP sous-jacente :
| Nom de la métrique | Unit | Type | Description |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | s | Histogramme | Le temps nécessaire à une demande pour établir une connexion. |
| client.http.connections.dns\$1lookup\$1duration | s | Histogramme | Le temps nécessaire pour effectuer une recherche DNS. |
| client.http.connections.tls\$1handshake\$1duration | s | Histogramme | Le temps nécessaire pour effectuer une poignée de main TLS. |
| client.http.connections.usage | \$1connexion\$1 | UpDownCounter | État actuel des connexions dans le pool. Utilise une state dimension dont la valeur est idle ouacquired. |
| client.http.do\$1request\$1duration | s | Histogramme | Le temps total passé à exécuter la requête HTTP. |
| client.http.time\$1to\$1first\$1byte | s | Histogramme | Temps écoulé entre l'envoi de la demande et la réception du premier octet de réponse. |
# Nouvelles tentatives et délais d'expiration
Vous AWS SDK pour Go permet de configurer le comportement des nouvelles tentatives des demandes adressées aux services HTTP. Par défaut, les clients du service utilisent [Retry.standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) comme rétryer par défaut. Si la configuration ou le comportement par défaut ne répond pas aux exigences de votre application, vous pouvez ajuster la configuration du rétryer ou fournir votre propre implémentation de rétryer.
AWS SDK pour Go Fournit une interface [AWS.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) qui définit l'ensemble des méthodes requises pour implémenter une nouvelle tentative. [Le SDK fournit deux implémentations pour les nouvelles tentatives : [Retry.standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) et aws. NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer).
## Rétracteur standard
Le [retryer Retry.standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) est l'`aws.Retryer`implémentation par défaut utilisée par les clients du SDK. Le réessayeur standard est un réessayeur à débit limité avec un nombre maximum de tentatives configurable et la possibilité d'ajuster la politique de rétrogradation des demandes.
Le tableau suivant définit les valeurs par défaut pour ce rétryer :
| Propriété | Par défaut |
| --- | --- |
| Nombre maximum de tentatives | 3 |
| Délai de retour maximal | 20 secondes |
Lorsqu'une erreur réessayable se produit lors de l'appel de votre demande, le réessayeur standard utilise la configuration fournie pour retarder puis réessayer la demande. Les nouvelles tentatives augmentent la latence globale de votre demande, et vous devez configurer une nouvelle tentative si la configuration par défaut ne répond pas aux exigences de votre application.
Consultez la documentation du package [Retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) pour plus de détails sur les erreurs considérées comme réessayables par l'implémentation standard du retryer.
## NopRetryer
Les [lois. NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer)est une `aws.Retryer` implémentation qui est fournie si vous souhaitez désactiver toutes les tentatives de nouvelle tentative. Lors de l'appel d'une opération client de service, ce réessayeur n'autorisera la demande qu'une seule fois, et toute erreur qui en résultera sera renvoyée à l'application appelante.
## Personnalisation du comportement
Le SDK fournit un ensemble d'utilitaires d'assistance qui encapsulent une `aws.Retryer` implémentation et renvoie le rétryer fourni avec le comportement de nouvelle tentative souhaité. Vous pouvez remplacer le rétryer par défaut pour tous les clients, par client ou par opération en fonction des exigences de vos applications. Pour voir des exemples supplémentaires montrant comment procéder, consultez les exemples de documentation du package [retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
**Avertissement**
Si vous spécifiez une `aws.Retryer` implémentation globale en utilisant`config.WithRetryer`, vous devez vous assurer de renvoyer une nouvelle instance de `aws.Retryer` chaque appel. Cela vous évitera de créer un bucket global de jetons de réessai pour tous les clients du service.
### Limiter le nombre maximum de tentatives
Vous utilisez [Retry. AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts)pour encapsuler une `aws.Retryer` implémentation afin de définir le nombre maximum de tentatives à la valeur souhaitée.
**Avertissement**
L'utilisation `retry.AddWithMaxAttempts` d'une valeur de zéro permettra au SDK de réessayer toutes les erreurs réessayables jusqu'à ce que la demande aboutisse ou qu'une erreur non réessayable soit renvoyée. **Permettre au SDK de réessayer à l'infini peut entraîner une charge de travail galopante et des cycles de facturation excessifs.**
```
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)
```
Notez que l'instanciation d'un rétryer à l'aide d'options fonctionnelles à définir MaxAttempts directement aura un comportement légèrement différent. Plus précisément, si vous définissez une valeur inférieure ou égale à zéro, le réessayeur utilisera le maximum de 3 tentatives par défaut, plutôt que de réessayer à l'infini :
```
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)
```
### Limiter le délai maximal d'arrêt
Vous utilisez [Retry. AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay)pour encapsuler une `aws.Retryer` implémentation et limiter le délai d'attente maximal autorisé entre deux nouvelles tentatives d'une demande ayant échoué.
Par exemple, vous pouvez utiliser le code suivant pour encapsuler le rétryer client standard avec le délai maximum souhaité de cinq secondes :
```
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)
```
### Réessayez d'autres codes d'erreur d'API
Vous utilisez [Retry. AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes)pour encapsuler une `aws.Retryer` implémentation et inclure des codes d'erreur d'API supplémentaires qui doivent être considérés comme réessayables.
Par exemple, vous pouvez utiliser le code suivant pour encapsuler le rétryer client standard afin d'inclure l'`NoSuchBucketException`exception Amazon S3 comme réessayable.
```
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)
```
### Limitation du débit côté client
Le AWS SDK pour Go introduit un nouveau mécanisme de limitation du débit côté client dans la politique de réessai standard afin de s'aligner sur le comportement moderne. SDKs [Ce comportement est contrôlé par le [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter)champ des options d'un réessayeur.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions)
A RateLimiter fonctionne comme un bucket de jetons d'une capacité définie, où les échecs de tentative d'opération consomment des jetons. Une nouvelle tentative qui tente de consommer plus de jetons que ce qui est disponible entraîne un échec de l'opération avec un [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError).
L'implémentation par défaut est paramétrée comme suit (comment modifier chaque paramètre) :
+ une capacité de 500 (définissez la valeur de RateLimiter lors de StandardOptions l'utilisation [NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit))
+ une nouvelle tentative provoquée par un délai d'attente coûte 10 jetons (activé RetryTimeoutCost ) StandardOptions
+ une nouvelle tentative provoquée par d'autres erreurs coûte 5 jetons ( RetryCostactivé StandardOptions)
+ une opération réussie à la première tentative ajoute 1 jeton ( NoRetryIncrement activé StandardOptions)
+ les opérations réussies lors de la deuxième tentative ou d'une tentative ultérieure n'ajoutent aucun jeton
Si vous trouvez que le comportement par défaut ne correspond pas aux besoins de votre application, vous pouvez le désactiver avec [RateLimit.NONE](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables).
#### Exemple : limiteur de débit modifié
```
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
})
}))
```
#### Exemple : aucune limite de débit avec 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
})
}))
```
## Délais
Vous utilisez le package de [contexte](https://golang.org/pkg/context/) pour définir des délais ou des délais lorsque vous invoquez une opération client de service. Utilisez le [contexte. WithDeadline](https://golang.org/pkg/context/#WithDeadline)pour encapsuler le contexte de vos applications et définir une date limite à laquelle l'opération invoquée doit être terminée. Pour définir un délai d'expiration après un certain [contexte `time.Duration` d'utilisation. WithTimeout](https://golang.org/pkg/context/#WithTimeout). Le SDK transmet le contenu fourni `context.Context` au client de transport HTTP lors de l'appel d'une API de service. Si le contexte transmis au SDK est annulé ou devient annulé lors de l'appel de l'opération, le SDK ne réessaiera pas la demande et retournera à l'application appelante. Vous devez gérer l'annulation du contexte de manière appropriée dans votre application dans les cas où le contexte fourni au SDK est annulé.
### Définition d'un délai d'attente
L'exemple suivant montre comment définir un délai d'expiration pour une opération client de service.
```
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
}
```