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 des clients de service dans le AWS SDK pour Rust
Pour y accéder par programmation Services AWS, le AWS SDK pour Rust utilise une structure client pour chacun. Service AWS Par exemple, si votre application doit accéder à Amazon EC2, elle crée une structure EC2 client Amazon pour interagir avec ce service. Vous utilisez ensuite le client du service pour y faire des demandes Service AWS.
Pour faire une demande à un Service AWS, vous devez d'abord créer un client de service. Pour chaque Service AWS élément utilisé par votre code, il possède sa propre caisse et son propre type dédié pour interagir avec lui. Le client expose une méthode pour chaque opération d'API exposée par le service.
Il existe de nombreuses méthodes alternatives pour configurer le comportement du SDK, mais en fin de compte, tout dépend du comportement des clients du service. Toute configuration n'a aucun effet tant qu'un client de service créé à partir de celles-ci n'est pas utilisé.
Vous devez définir la manière dont votre code s'authentifie AWS lorsque vous développez avec Services AWS. Vous devez également définir la valeur que Région AWS vous souhaitez utiliser.
Le [guide de référence AWS SDKs and Tools](https://docs.aws.amazon.com/sdkref/latest/guide/) contient également des paramètres, des fonctionnalités et d'autres concepts fondamentaux communs à de AWS SDKs nombreux.
**Topics**
+ [Configuration du client en externe](config-external.md)
+ [Configuration du client dans le code](config-code.md)
+ [Région AWS](region.md)
+ [Fournisseurs d'informations d'identification](credproviders.md)
+ [Versions comportementales](behavior-versions.md)
+ [Nouvelles tentatives](retries.md)
+ [Délais](timeouts.md)
+ [Observabilité](observability.md)
+ [Points de terminaison clients](endpoints.md)
+ [Remplacer une configuration d'opération](peroperation.md)
+ [HTTP](http.md)
+ [Intercepteurs](interceptors.md)
# Configuration externe AWS SDK pour Rust des clients de service
De nombreux paramètres de configuration peuvent être gérés en dehors de votre code. Lorsque la configuration est gérée en externe, elle est appliquée à toutes vos applications. La plupart des paramètres de configuration peuvent être définis sous forme de variables d'environnement ou dans un AWS `config` fichier partagé distinct. Le `config` fichier partagé peut gérer des ensembles de paramètres distincts, appelés profils, afin de fournir différentes configurations pour différents environnements ou tests.
Les variables d'environnement et les paramètres de `config` fichiers partagés sont standardisés AWS SDKs et partagés entre les outils afin de garantir des fonctionnalités cohérentes entre les différents langages de programmation et applications.
Consultez le *guide de référence AWS SDKs and Tools* pour en savoir plus sur la configuration de votre application à l'aide de ces méthodes, ainsi que des détails sur chaque paramètre inter-SDK. Pour voir tous les paramètres que le SDK peut résoudre à partir des variables d'environnement ou des fichiers de configuration, consultez la référence des [paramètres dans le guide de référence](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) *des outils AWS SDKs et des outils*.
Pour faire une demande à un Service AWS, vous devez d'abord instancier un client pour ce service. Vous pouvez configurer des paramètres courants pour les clients de service tels que les délais d'expiration, le client HTTP et la configuration des nouvelles tentatives.
Chaque client de service a besoin d'un Région AWS et d'un fournisseur d'informations d'identification. Le SDK utilise ces valeurs pour envoyer des demandes à la région appropriée pour vos ressources et pour signer les demandes avec les informations d'identification correctes. Vous pouvez spécifier ces valeurs par programmation dans le code ou les charger automatiquement depuis l'environnement.
Le SDK possède une série d'emplacements (ou de sources) qu'il vérifie afin de trouver une valeur pour les paramètres de configuration.
1. Tout paramètre explicite défini dans le code ou sur un client de service lui-même a priorité sur tout autre paramètre.
1. Variables d’environnement
+ Pour plus de détails sur la définition des variables d'[environnement, voir les variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) d'environnement dans le *guide de référence AWS SDKs et Tools*.
+ Notez que vous pouvez configurer des variables d'environnement pour un shell à différents niveaux de portée : à l'échelle du système, à l'échelle de l'utilisateur et pour une session de terminal spécifique.
1. Partage `config` et `credentials` fichiers
+ Pour plus de détails sur la configuration de ces fichiers, consultez les [sections Shared `config` et `credentials` files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) du *guide de référence AWS SDKs and Tools*.
1. Toute valeur par défaut fournie par le code source du SDK lui-même est utilisée en dernier.
+ Certaines propriétés, telles que Region, n'ont pas de valeur par défaut. Vous devez les spécifier de manière explicite dans le code, dans un paramètre d'environnement ou dans le `config` fichier partagé. Si le SDK ne parvient pas à résoudre la configuration requise, les demandes d'API peuvent échouer lors de l'exécution.
# Configuration du AWS SDK pour les clients du service Rust dans le code
Lorsque la configuration est gérée directement dans le code, l'étendue de la configuration est limitée à l'application qui utilise ce code. Dans cette application, il existe des options pour la configuration globale de tous les clients de service, la configuration pour tous les clients d'un certain Service AWS type ou la configuration pour une instance de client de service spécifique.
Pour faire une demande à un Service AWS, vous devez d'abord instancier un client pour ce service. Vous pouvez configurer des paramètres courants pour les clients de service tels que les délais d'expiration, le client HTTP et la configuration des nouvelles tentatives.
Chaque client de service a besoin d'un Région AWS et d'un fournisseur d'informations d'identification. Le SDK utilise ces valeurs pour envoyer des demandes à la région appropriée pour vos ressources et pour signer les demandes avec les informations d'identification correctes. Vous pouvez spécifier ces valeurs par programmation dans le code ou les charger automatiquement depuis l'environnement.
**Note**
Les clients du service peuvent être coûteux à construire et sont généralement destinés à être partagés. Pour faciliter cela, toutes les `Client` structures sont `Clone` implémentées.
## Configuration d'un client depuis l'environnement
Pour créer un client avec une configuration basée sur l'environnement, utilisez les méthodes statiques de la `aws-config` caisse :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
La création d'un client de cette manière est utile lors de l'exécution sur Amazon Elastic Compute Cloud ou dans tout autre contexte dans lequel la configuration d'un client de service est disponible directement depuis l'environnement. AWS Lambda Cela dissocie votre code de l'environnement dans lequel il s'exécute et facilite le déploiement de votre application sur plusieurs Régions AWS sans modifier le code.
Vous pouvez explicitement remplacer des propriétés spécifiques. La configuration explicite a priorité sur la configuration résolue depuis l'environnement d'exécution. L'exemple suivant charge la configuration depuis l'environnement, mais remplace explicitement : Région AWS
```
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
**Note**
Toutes les valeurs de configuration ne proviennent pas du client au moment de la création. Les paramètres liés aux informations d'identification, tels que les clés d'accès temporaires et la configuration du centre d'identité IAM, sont accessibles par la couche du fournisseur d'informations d'identification lorsque le client est utilisé pour effectuer une demande.
Le code `BehaviorVersion::latest()` présenté dans les exemples précédents indique la version du SDK à utiliser pour les valeurs par défaut. `BehaviorVersion::latest()`convient dans la plupart des cas. Pour en savoir plus, consultez [Utilisation de versions comportementales dans AWS SDK pour Rust](behavior-versions.md).
## Utiliser le modèle de générateur pour les paramètres spécifiques au service
Certaines options ne peuvent être configurées que sur un type de client de service spécifique. Cependant, le plus souvent, vous souhaiterez toujours charger la majeure partie de la configuration depuis l'environnement, puis ajouter spécifiquement les options supplémentaires. Le modèle Builder est un modèle courant dans les AWS SDK pour Rust caisses. Vous chargez d'abord la configuration générale à l'aide de`aws_config::defaults`, puis vous utilisez la `from` méthode pour charger cette configuration dans le générateur pour le service avec lequel vous travaillez. Vous pouvez ensuite définir des valeurs de configuration uniques pour ce service et cet appel`build`. Enfin, le client est créé à partir de cette configuration modifiée.
```
// Call a static method on aws-config that sources default config values.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// Use the Builder for S3 to create service-specific config from the default config.
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.accelerate(true) // Set an S3-only configuration option
.build();
// Create the client.
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
Pour découvrir des méthodes supplémentaires disponibles pour un type de client de service spécifique, vous pouvez utiliser la documentation de l'API, telle que for [https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html).
## Configuration client explicite avancée
Pour configurer un client de service avec des valeurs spécifiques au lieu de charger une configuration depuis l'environnement, vous pouvez les spécifier dans le `Config` générateur de clients, comme indiqué ci-dessous :
```
let conf = aws_sdk_s3::Config::builder()
.region("us-east-1")
.endpoint_resolver(my_endpoint_resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(conf);
```
Lorsque vous créez une configuration de service avec`aws_sdk_s3::Config::builder()`, *aucune configuration par défaut n'est chargée*. Les valeurs par défaut ne sont chargées que lors de la création d'une configuration basée sur`aws_config::defaults`.
Certaines options ne peuvent être configurées que sur un type de client de service spécifique. L'exemple précédent en montre un exemple en utilisant la `endpoint_resolver` fonction sur un client Amazon S3.
# Régler le Région AWS pour le AWS SDK pour Rust
Vous pouvez accéder à Services AWS ceux qui opèrent dans une zone géographique spécifique en utilisant Régions AWS. Cela peut être utile à la fois pour assurer la redondance et pour que vos données et applications fonctionnent à proximité de l'endroit où vous et vos utilisateurs y accédez. Pour plus d'informations sur la manière dont les régions sont utilisées, consultez [Région AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)le *guide de référence des outils AWS SDKs et des outils*.
**Important**
La plupart des ressources se trouvent dans une région spécifique Région AWS et vous devez indiquer la région appropriée pour la ressource lorsque vous utilisez le SDK.
Vous devez définir une valeur par défaut Région AWS pour le SDK pour Rust à utiliser pour les AWS requêtes. Cette valeur par défaut est utilisée pour tous les appels de méthode de service du SDK qui ne sont pas spécifiés par une région.
Pour des exemples sur la façon de définir la région par défaut via le AWS `config` fichier partagé ou les variables d'environnement, consultez [Région AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)le *Guide de référence des outils AWS SDKs et des outils*.
## Région AWS chaîne de fournisseurs
Le processus de recherche suivant est utilisé lors du chargement de la configuration d'un client de service depuis l'environnement d'exécution. La première valeur définie par le SDK est utilisée dans la configuration du client. Pour plus d'informations sur la création de clients de service, consultez[Configuration d'un client depuis l'environnement](config-code.md#configure-a-client-from-the-environment).
1. Toute région explicite définie par programmation.
1. La variable d'environnement `AWS_REGION` est contrôlée.
+ Si vous utilisez le AWS Lambda service, cette variable d'environnement est définie automatiquement par le AWS Lambda conteneur.
1. La `region` propriété du AWS `config` fichier partagé est vérifiée.
+ La variable d'`AWS_CONFIG_FILE`environnement peut être utilisée pour modifier l'emplacement du `config` fichier partagé. Pour en savoir plus sur l'emplacement de conservation de ce fichier, consultez la section [Emplacement du fichier partagé `config` et `credentials` des fichiers](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) dans le *Guide de référence des outils AWS SDKs et*.
+ La variable d'`AWS_PROFILE`environnement peut être utilisée pour sélectionner un profil nommé au lieu du profil par défaut. Pour en savoir plus sur la configuration des différents profils, consultez la section [Shared `config` and `credentials` files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) dans le *guide de référence AWS SDKs and Tools*.
1. Le SDK tente d'utiliser le service de métadonnées d'instance Amazon EC2 pour déterminer la région de l'instance Amazon EC2 actuellement en cours d'exécution.
+ Les AWS SDK pour Rust seuls supports IMDSv2.
Le `RegionProviderChain` est automatiquement utilisé sans code supplémentaire lors de la création d'une configuration de base à utiliser avec un client de service :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
```
## Paramétrer le code Région AWS d'entrée
### Définition explicite de la région dans le code
À utiliser `Region::new()` directement dans votre configuration lorsque vous souhaitez définir explicitement la région.
La chaîne de fournisseurs de régions n'est pas utilisée : elle ne vérifie pas l'environnement, le `config` fichier partagé ou le service de métadonnées d'instance Amazon EC2.
```
use aws_config::{defaults, BehaviorVersion};
use aws_sdk_s3::config::Region;
#[tokio::main]
async fn main() {
let config = defaults(BehaviorVersion::latest())
.region(Region::new("us-west-2"))
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
Assurez-vous de saisir une chaîne valide pour un Région AWS ; la valeur fournie n'est pas validée.
### Personnalisation du `RegionProviderChain`
Utilisez le [Région AWS chaîne de fournisseurs](#region-provider-chain) lorsque vous souhaitez injecter une région de manière conditionnelle, la remplacer ou personnaliser la chaîne de résolution.
```
use aws_config::{defaults, BehaviorVersion};
use aws_config::meta::region::RegionProviderChain;
use aws_sdk_s3::config::Region;
use std::env;
#[tokio::main]
async fn main() {
let region_provider = RegionProviderChain::first_try(env::var("CUSTOM_REGION").ok().map(Region::new))
.or_default_provider()
.or_else(Region::new("us-east-2"));
let config = aws_config::defaults(BehaviorVersion::latest())
.region(region_provider)
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
La configuration précédente permettra de :
1. Vérifiez d'abord s'il existe une chaîne définie dans la variable d'`CUSTOM_REGION`environnement.
1. Si ce n'est pas disponible, revenez à la chaîne de fournisseurs régionaux par défaut.
1. Si cela échoue, utilisez « us-east-2 » comme solution de repli finale.
# Utilisation du AWS SDK pour les fournisseurs d'informations d'identification Rust
Toutes les demandes AWS doivent être signées cryptographiquement à l'aide des informations d'identification émises par AWS. Au moment de l'exécution, le SDK récupère les valeurs de configuration pour les informations d'identification en vérifiant plusieurs emplacements.
Si la configuration récupérée inclut des [paramètres d'accès par authentification AWS IAM Identity Center unique](credentials.md), le SDK fonctionne avec le IAM Identity Center pour récupérer les informations d'identification temporaires qu'il utilise pour envoyer une demande. Services AWS
Si la configuration récupérée inclut des [informations d'identification temporaires](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html), le SDK les utilise pour Service AWS passer des appels. Les informations d'identification temporaires se composent de clés d'accès et d'un jeton de session.
L'authentification avec AWS peut être gérée en dehors de votre base de code. De nombreuses méthodes d'authentification peuvent être automatiquement détectées, utilisées et actualisées par le SDK à l'aide de la chaîne de fournisseurs d'informations d'identification.
Pour connaître les options guidées permettant de démarrer l' AWS authentification pour votre projet, consultez la section [Authentification et accès](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) dans le *guide de référence des outils AWS SDKs et*.
## La chaîne de fournisseurs d'accréditations
Si vous ne spécifiez pas explicitement de fournisseur d'informations d'identification lors de la création d'un client, le SDK pour Rust utilise une chaîne de fournisseurs d'informations d'identification qui vérifie une série d'endroits où vous pouvez fournir des informations d'identification. Une fois que le SDK a trouvé des informations d'identification à l'un de ces emplacements, la recherche s'arrête. Pour plus de détails sur la création de clients, voir[Configuration du AWS SDK pour les clients du service Rust dans le code](config-code.md).
L'exemple suivant ne spécifie pas de fournisseur d'informations d'identification dans le code. Le SDK utilise la chaîne de fournisseurs d'informations d'identification pour détecter l'authentification qui a été configurée dans l'environnement d'hébergement, et utilise cette authentification pour les appels à. Services AWS
```
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3 = aws_sdk_s3::Client::new(&config);
```
### Ordre de récupération des informations d'identification
La chaîne de fournisseurs d'informations d'identification recherche les informations d'identification à l'aide de la séquence prédéfinie suivante :
1. **Accédez aux variables d'environnement clés**
Le SDK tente de charger les informations d'identification à partir `AWS_ACCESS_KEY_ID` des variables `AWS_SECRET_ACCESS_KEY` d'`AWS_SESSION_TOKEN`environnement et.
1. **Le partage AWS `config` et les `credentials` fichiers**
Le SDK tente de charger les informations d'identification à partir du `[default]` profil dans les `credentials` fichiers partagés AWS `config` et. Vous pouvez utiliser la variable d'`AWS_PROFILE`environnement pour choisir un profil nommé que vous souhaitez que le SDK charge au lieu de l'utiliser`[default]`. Les `credentials` fichiers `config` et sont partagés par différents AWS SDKs outils. Pour plus d'informations sur ces fichiers, consultez les sections [Shared `config` et `credentials` files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) dans le *guide de référence AWS SDKs and Tools*. Pour plus d'informations sur les fournisseurs standardisés que vous pouvez spécifier dans un profil, voir [AWS SDKs et Outils fournisseurs d'informations d'identification standardisés](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).
1. **AWS STS identité Web**
Lorsque vous créez des applications mobiles ou des applications Web basées sur le client qui nécessitent un accès à AWS, AWS Security Token Service (AWS STS) renvoie un ensemble d'informations d'identification de sécurité temporaires pour les utilisateurs fédérés authentifiés par le biais d'un fournisseur d'identité public (IdP).
+ Lorsque vous le spécifiez dans un profil, le SDK ou l'outil tente de récupérer des informations d'identification temporaires à l'aide de la méthode AWS STS `AssumeRoleWithWebIdentity` API. Pour plus de détails sur cette méthode, reportez-vous [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)à la *référence de l'AWS Security Token Service API*.
+ Pour obtenir des conseils sur la configuration de ce fournisseur, consultez [Federate with Web Identity ou OpenID](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity) Connect *AWS SDKs dans le guide de référence and Tools*.
+ Pour plus de détails sur les propriétés de configuration du SDK pour ce fournisseur, voir [Assumer le rôle de fournisseur d'informations d'identification](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html) dans le guide de *référence AWS SDKs and Tools*.
1. **Informations d'identification des conteneurs Amazon ECS et Amazon EKS**
Un rôle IAM peut être associé à vos tâches Amazon Elastic Container Service et à vos comptes de service Kubernetes. Les autorisations accordées dans le rôle IAM sont assumées par les conteneurs exécutés dans la tâche ou les conteneurs du pod. Ce rôle permet à votre SDK pour le code d'application Rust (sur le conteneur) d'en utiliser un autre Services AWS.
Le SDK tente de récupérer les informations d'identification à partir des variables d'`AWS_CONTAINER_CREDENTIALS_FULL_URI`environnement `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or, qui peuvent être définies automatiquement par Amazon ECS et Amazon EKS.
+ Pour plus d'informations sur la configuration de ce rôle pour Amazon ECS, consultez le [rôle IAM de la tâche Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) dans le manuel *Amazon Elastic Container Service Developer Guide*.
+ Pour obtenir des informations sur la configuration d'Amazon EKS, consultez la section [Configuration de l'agent d'identité Amazon EKS Pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) dans le **guide de l'utilisateur Amazon EKS**.
+ Pour plus de détails sur les propriétés de configuration du SDK pour ce fournisseur, consultez la section [Fournisseur d'informations d'identification du conteneur](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html) dans le guide de *référence AWS SDKs and Tools*.
1. **Service de métadonnées d'instance Amazon EC2**
Créez un rôle IAM et attachez-le à votre instance. Le SDK pour l'application Rust de l'instance tente de récupérer les informations d'identification fournies par le rôle à partir des métadonnées de l'instance.
+ Le SDK pour Rust ne prend en charge [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)que.
+ Pour plus de détails sur la configuration de ce rôle et l'utilisation des métadonnées, [consultez les rôles IAM pour Amazon](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) EC2 [et Work with instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) metadata dans le guide de l'utilisateur *Amazon EC2*.
+ Pour plus de détails sur les propriétés de configuration du SDK pour ce fournisseur, consultez la section [fournisseur d'informations d'identification IMDS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html) dans le guide de référence *AWS SDKs and Tools*.
1. Si les informations d'identification ne sont toujours pas résolues à ce stade, l'opération panics entraîne une erreur.
Pour plus de détails sur les paramètres de configuration des fournisseurs AWS d'informations d'identification, consultez la section [Fournisseurs d'informations d'identification standardisés](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) dans la *référence des paramètres* du guide de *référence AWS SDKs et des outils*.
## Fournisseur d'informations d'identification explicite
Au lieu de vous fier à la chaîne de fournisseurs d'informations d'identification pour détecter votre méthode d'authentification, vous pouvez spécifier un fournisseur d'informations d'identification spécifique que le SDK doit utiliser. Lorsque vous chargez votre configuration générale à l'aide de`aws_config::defaults`, vous pouvez spécifier un fournisseur d'informations d'identification personnalisé, comme indiqué ci-dessous :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.credentials_provider(MyCredentialsProvider::new())
.load()
.await;
```
Vous pouvez implémenter votre propre fournisseur d'informations d'identification en implémentant le [https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html](https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html)trait.
## Mise en cache des identités
Le SDK mettra en cache les informations d'identification et les autres types d'identité tels que les jetons SSO. Par défaut, le SDK utilise une implémentation de cache différé qui charge les informations d'identification lors de la première demande, les met en cache, puis tente de les actualiser lors d'une autre demande lorsqu'elles sont sur le point d'expirer. Les clients créés à partir de la même `SdkConfig` page partageront un [https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html](https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html).
# Utilisation de versions comportementales dans AWS SDK pour Rust
AWS SDK pour Rust les développeurs attendent et s'appuient sur le comportement robuste et prévisible du langage et de ses principales bibliothèques. Pour aider les développeurs utilisant le SDK pour Rust à obtenir le comportement attendu, les configurations client doivent inclure un`BehaviorVersion`. `BehaviorVersion`Spécifie la version du SDK dont les valeurs par défaut sont attendues. Cela permet au SDK d'évoluer au fil du temps, en modifiant les meilleures pratiques pour répondre aux nouvelles normes et prendre en charge les nouvelles fonctionnalités sans impact négatif inattendu sur le comportement de votre application.
**Avertissement**
Si vous essayez de configurer le SDK ou de créer un client sans spécifier explicitement a`BehaviorVersion`, le constructeur le fera. panic
Par exemple, imaginez qu'une nouvelle version du SDK soit publiée avec une nouvelle politique de relance par défaut. Si votre application utilise une version précédente du SDK `BehaviorVersion` correspondant, cette configuration précédente est utilisée à la place de la nouvelle configuration par défaut.
Chaque fois qu'une nouvelle version comportementale du SDK pour Rust est publiée, la précédente `BehaviorVersion` est marquée par l'`deprecated`attribut SDK pour Rust et la nouvelle version est ajoutée. Cela provoque l'apparition d'avertissements au moment de la compilation, mais dans le cas contraire, la construction se poursuit comme d'habitude. `BehaviorVersion::latest()`est également mis à jour pour indiquer le comportement par défaut de la nouvelle version.
**Note**
Si votre code ne repose pas sur des caractéristiques comportementales extrêmement spécifiques, vous devez l'utiliser `BehaviorVersion::latest()` dans le code ou utiliser l'indicateur de fonctionnalité `behavior-version-latest` dans le `Cargo.toml` fichier. Si vous écrivez du code sensible à la latence ou qui ajuste les comportements du SDK Rust, pensez `BehaviorVersion` à l'épingler sur une version majeure spécifique.
## Définissez la version du comportement dans `Cargo.toml`
Vous pouvez spécifier la version du comportement pour le SDK et les modules individuels, par exemple `aws-sdk-s3` ou`aws-sdk-iam`, en incluant un indicateur de fonctionnalité approprié dans le `Cargo.toml` fichier. Pour le moment, seule la `latest` version du SDK est prise en charge dans `Cargo.toml` :
```
[dependencies]
aws-config = { version = "1", features = ["behavior-version-latest"] }
aws-sdk-s3 = { version = "1", features = ["behavior-version-latest"] }
```
## Définissez la version du comportement dans le code
Votre code peut modifier la version du comportement selon les besoins en la spécifiant lors de la configuration du SDK ou d'un client :
```
let config = aws_config::load_defaults(BehaviorVersion::v2023_11_09()).await;
```
Cet exemple crée une configuration qui utilise l'environnement pour configurer le SDK, mais qui définit la valeur sur`BehaviorVersion`. `v2023_11_09()`
# Configuration des nouvelles tentatives dans le AWS SDK pour Rust
Le AWS SDK pour Rust fournit un comportement de nouvelle tentative par défaut pour les demandes de service et des options de configuration personnalisables. Appels renvoyant de Services AWS temps en temps des exceptions inattendues. Certains types d'erreurs, tels que les erreurs de régulation ou les erreurs transitoires, peuvent réussir si l'appel est retenté.
Le comportement des nouvelles tentatives peut être configuré globalement à l'aide des variables d'environnement ou des paramètres du AWS `config` fichier partagé. Pour plus d'informations sur cette approche, consultez la section [Comportement des nouvelles](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) tentatives dans le *guide de référence AWS SDKs et Tools*. Il inclut également des informations détaillées sur la mise en œuvre des stratégies de réessai et sur la manière de choisir une stratégie plutôt qu'une autre.
Ces options peuvent également être configurées dans votre code, comme indiqué dans les sections suivantes.
## Configuration de nouvelle tentative par défaut
Chaque client de service utilise par défaut la configuration de stratégie `standard` de nouvelle tentative fournie par la [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)structure. Par défaut, un appel sera essayé trois fois (*la première tentative, plus deux tentatives*). De plus, chaque nouvelle tentative sera retardée d'une courte durée aléatoire afin d'éviter les tempêtes de nouvelles tentatives. Cette convention convient à la majorité des cas d'utilisation, mais peut ne pas être adaptée dans des circonstances spécifiques telles que les systèmes à haut débit.
Seuls certains types d'erreurs sont considérés comme réessayables par le. SDKs Voici des exemples d'erreurs réessayables :
+ délais d'expiration des sockets
+ régulation côté service
+ erreurs de service transitoires telles que les réponses HTTP 5XX
Les exemples suivants **ne sont pas** considérés comme réessayables :
+ Paramètres manquants ou non valides
+ erreurs d'authentification/de sécurité
+ exceptions de mauvaise configuration
Vous pouvez personnaliser la stratégie des `standard` nouvelles tentatives en définissant le nombre maximal de tentatives, les délais et la configuration des interruptions.
## Nombre maximum de tentatives
Vous pouvez personnaliser le nombre maximum de tentatives dans votre code en fournissant une modification [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)à votre `aws_config::defaults` :
```
const CUSTOM_MAX_ATTEMPTS: u32 = 5;
let retry_config = RetryConfig::standard()
// Set max attempts. When max_attempts is 1, there are no retries.
// This value MUST be greater than zero.
// Defaults to 3.
.with_max_attempts(CUSTOM_MAX_ATTEMPTS);
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## Retards et retards
Si une nouvelle tentative est nécessaire, la stratégie de nouvelle tentative par défaut attend avant d'effectuer la prochaine tentative. Le délai de la première tentative est faible, mais il augmente de façon exponentielle lors des tentatives ultérieures. Le délai maximal est plafonné afin qu'il ne devienne pas trop important.
Une instabilité aléatoire est appliquée aux délais entre toutes les tentatives. L'instabilité contribue à atténuer les effets des grandes flottes qui peuvent provoquer des tempêtes de nouvelles tentatives. *Pour une discussion plus approfondie sur le recul et la gigue exponentiels, voir [Exponential Backoff And](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) Jitter dans le blog sur l'architecture.AWS *
Vous pouvez personnaliser les paramètres de délai de votre code en fournissant une modification [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)à votre`aws_config::defaults`. Le code suivant définit la configuration de manière à retarder la première tentative de 100 millisecondes au maximum et à ce que le délai maximum entre chaque nouvelle tentative soit de 5 secondes.
```
let retry_config = RetryConfig::standard()
// Defaults to 1 second.
.with_initial_backoff(Duration::from_millis(100))
// Defaults to 20 seconds.
.with_max_backoff(Duration::from_secs(5));
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## Mode de nouvelle tentative adaptatif
Comme alternative à la stratégie de nouvelle `standard` tentative de mode, la stratégie de nouvelle `adaptive` tentative de mode est une approche avancée qui recherche le taux de requêtes idéal afin de minimiser les erreurs de limitation.
**Note**
Les tentatives adaptatives sont un mode de nouvelle tentative avancé. L'utilisation de cette stratégie n'est généralement pas recommandée. [Reportez-vous à la section Comportement](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#standardvsadaptive) de nouvelle tentative dans le *guide de référence AWS SDKs et Tools*.
Les tentatives adaptatives incluent toutes les fonctionnalités des tentatives standard. Il ajoute un limiteur de débit côté client qui mesure le taux de demandes limitées par rapport aux demandes non limitées. Cela limite également le trafic pour tenter de rester dans une bande passante sûre, ce qui ne provoque idéalement aucune erreur de régulation.
Le tarif s'adapte en temps réel à l'évolution des conditions de service et des modèles de trafic et peut augmenter ou diminuer le taux de trafic en conséquence. Surtout, le limiteur de débit peut retarder les premières tentatives dans les scénarios à fort trafic.
Vous pouvez sélectionner la stratégie `adaptive` de nouvelle tentative dans le code en fournissant une modification [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html):
```
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(RetryConfig::adaptive())
.load()
.await;
```
# Configuration des délais d'expiration dans le AWS SDK pour Rust
Le AWS SDK pour Rust fournit plusieurs paramètres pour gérer les délais d'expiration des Service AWS demandes et les flux de données bloqués. Ils permettent à votre application de se comporter de manière optimale en cas de retards ou de défaillances inattendus sur le réseau.
## Délais d'expiration de l'API
En cas de problèmes transitoires susceptibles de retarder ou d'échouer complètement les tentatives de demande, il est important de revoir et de définir des délais d'expiration afin que votre application puisse échouer rapidement et se comporter de manière optimale. Les demandes qui échouent peuvent être automatiquement réessayées par le SDK. Il est recommandé de définir des délais d'expiration à la fois pour la tentative individuelle et pour l'ensemble de la demande.
Le SDK pour Rust fournit un délai d'expiration par défaut pour établir une connexion pour une requête. Le SDK n'a pas défini de temps d'attente maximal par défaut pour recevoir une réponse à une tentative de demande ou pour l'ensemble de la demande. Les options de délai d'expiration suivantes sont disponibles :
| Paramètre | Valeur par défaut | Description |
| --- | --- | --- |
| Connect Timeout | 3,1 secondes | Durée maximale d'attente avant d'établir une connexion avant d'abandonner. |
| Délai d'expiration de l'opération | Aucune | Durée maximale d'attente avant de recevoir une réponse du SDK pour Rust, y compris toutes les nouvelles tentatives. |
| Délai d'expiration de la tentative d'opération | Aucune | Durée maximale d'attente pour une seule tentative HTTP, après laquelle l'appel d'API peut être réessayé. |
| Délai de lecture | Aucune | Durée maximale d'attente pour lire le premier octet d'une réponse à partir du moment où la demande est initiée. |
L'exemple suivant montre la configuration d'un client Amazon S3 avec des valeurs de délai d'expiration personnalisées :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.timeout_config(
TimeoutConfig::builder()
.operation_timeout(Duration::from_secs(5))
.operation_attempt_timeout(Duration::from_millis(1500))
.build()
)
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
Lorsque vous utilisez à la fois le délai d'expiration des opérations et celui des tentatives, vous définissez une limite stricte au temps total consacré à toutes les tentatives entre les nouvelles tentatives. Vous pouvez également configurer une requête HTTP individuelle pour qu'elle échoue rapidement en cas de requête lente.
Au lieu de définir ces valeurs de délai d'expiration sur le client de service pour toutes les opérations, vous pouvez les configurer ou [les remplacer pour une seule demande](peroperation.md).
**Important**
Les délais d'exécution et de tentative ne s'appliquent pas aux données de streaming consommées une fois que le SDK pour Rust a renvoyé une réponse. Par exemple, la consommation de données provenant d'un `ByteStream` membre d'une réponse n'est pas soumise à des délais d'exécution.
## Protection contre le blocage des cours d'eau
Le SDK pour Rust fournit une autre forme de délai d'attente liée à la détection des flux bloqués. Un flux bloqué est un flux de chargement ou de téléchargement qui ne produit aucune donnée pendant une période de grâce configurée. Cela permet d'éviter que les applications ne se bloquent indéfiniment et ne progressent jamais.
La protection des flux bloqués renvoie une erreur lorsqu'un flux est inactif pendant une période supérieure à la période acceptable.
Par défaut, le SDK pour Rust active la protection des flux bloqués pour les téléchargements et détecte au moins 1 % byte/sec d'activité avec un délai de grâce généreux de 20 secondes.
L'exemple suivant montre une option personnalisée `StalledStreamProtectionConfig` qui désactive la protection des téléchargements et fait passer le délai de grâce en cas d'absence d'activité à 10 secondes :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(
StalledStreamProtectionConfig::enabled()
.upload_enabled(false)
.grace_period(Duration::from_secs(10))
.build()
)
.load()
.await;
```
**Avertissement**
La protection des flux bloqués est une option de configuration avancée. Nous vous recommandons de modifier ces valeurs uniquement si votre application a besoin de meilleures performances ou si cela cause un autre problème.
### Désactiver la protection contre les diffusions bloquées
L'exemple suivant montre comment désactiver complètement la protection des flux bloqués :
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(StalledStreamProtectionConfig::disabled())
.load()
.await;
```
# Configuration des fonctionnalités d'observabilité dans le AWS SDK pour Rust
L'observabilité est la mesure dans laquelle l'état actuel d'un système peut être déduit des données qu'il émet. Les données émises sont communément appelées télémétrie.
**Topics**
+ [Journalisation](logging.md)
# Configuration et utilisation de la journalisation dans le AWS SDK pour Rust
AWS SDK pour Rust Utilise le cadre de [suivi](http://tracing.rs/) pour la journalisation. Pour activer la journalisation, ajoutez la `tracing-subscriber` caisse et initialisez-la dans votre application Rust. Les journaux incluent les horodatages, les niveaux de journalisation et les chemins des modules, ce qui permet de déboguer les requêtes d'API et le comportement du SDK. Utilisez la variable d'`RUST_LOG`environnement pour contrôler la verbosité du journal, en filtrant par module si nécessaire.
## Comment activer la connexion dans le AWS SDK pour Rust
1. Dans une invite de commande pour le répertoire de votre projet, ajoutez la caisse [tracing-subscriber](https://crates.io/crates/tracing-subscriber) en tant que dépendance :
```
$ cargo add tracing-subscriber --features tracing-subscriber/env-filter
```
Cela ajoute la caisse à la `[dependencies]` section de votre `Cargo.toml` fichier.
1. Initialisez l'abonné. Cela se fait généralement au début de la `main` fonction avant d'appeler un SDK pour une opération Rust :
```
use aws_config::BehaviorVersion;
type BoxError = Box;
#[tokio::main]
async fn main() -> Result<(), BoxError> {
tracing_subscriber::fmt::init(); // Initialize the subscriber.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
let _resp = s3.list_buckets()
.send()
.await?;
Ok(())
}
```
1. Activez la journalisation à l'aide d'une variable d'`RUST_LOG`environnement. Pour activer l'affichage des informations de journalisation, dans une invite de commande, définissez la variable d'`RUST_LOG`environnement au niveau auquel vous souhaitez vous connecter. L'exemple suivant définit la journalisation au `debug` niveau suivant :
------
#### [ Linux/macOS ]
```
$ RUST_LOG=debug
```
------
#### [ Windows ]
Si vous utilisez VSCode, la fenêtre du terminal est souvent définie par défaut sur PowerShell. Vérifiez le type d'invite que vous utilisez.
```
C:\> set RUST_LOG=debug
```
------
#### [ PowerShell ]
```
PS C:\> $ENV:RUST_LOG="debug"
```
------
1. Exécutez le programme :
```
$ cargo run
```
Vous devriez voir une sortie supplémentaire dans la console ou dans la fenêtre du terminal.
Pour plus d'informations, consultez la section [Filtrage des événements à l'aide de variables d'environnement](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables) dans la `tracing-subscriber` documentation.
## Interpréter la sortie du journal
Une fois que vous avez activé la journalisation en suivant les étapes de la section précédente, les informations de journal supplémentaires seront imprimées en standard par défaut.
Si vous utilisez le format de sortie de journal par défaut (appelé « complet » par le module de suivi), les informations que vous voyez dans la sortie du journal ressemblent à ceci :
```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```
Chaque entrée inclut les éléments suivants :
+ Horodatage de l'entrée du journal.
+ Le niveau de journalisation de l'entrée. Il s'agit d'un mot tel que `INFO``DEBUG`, ou`TRACE`.
+ Ensemble imbriqué de plages à partir [duquel](https://docs.rs/tracing/latest/tracing/span/index.html) l'entrée du journal a été générée, séparées par des deux-points (« : »). Cela vous permet d'identifier la source de l'entrée du journal.
+ Le chemin du module Rust contenant le code qui a généré l'entrée du journal.
+ Texte du message du journal.
Les formats de sortie standard du module de traçage utilisent des codes d'échappement ANSI pour coloriser la sortie. Gardez ces séquences d'échappement à l'esprit lorsque vous filtrez ou recherchez la sortie.
**Note**
Dans `sdk_invocation_id` l'ensemble imbriqué de plages apparaît un identifiant unique généré côté client par le SDK pour aider à corréler les messages du journal. Il n'est pas lié à l'ID de demande trouvé dans la réponse d'un Service AWS.
## Ajustez vos niveaux de journalisation
Si vous utilisez une caisse qui prend en charge un filtrage d'environnement, par exemple`tracing_subscriber`, vous pouvez contrôler la verbosité des journaux par module.
Vous pouvez activer le même niveau de journalisation pour chaque module. Ce qui suit définit le niveau de journalisation `trace` pour chaque module :
```
$ RUST_LOG=trace cargo run
```
Vous pouvez activer la journalisation au niveau du traçage pour un module spécifique. Dans l'exemple suivant, seuls les journaux provenant de `aws_smithy_runtime` seront entrés au `trace` niveau.
```
$ RUST_LOG=aws_smithy_runtime=trace
```
Vous pouvez spécifier un niveau de journalisation différent pour plusieurs modules en les séparant par des virgules. L'exemple suivant définit le `aws_config` module sur la journalisation de `trace` niveau et le `aws_smithy_runtime` module sur la journalisation de `debug` niveau.
```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```
Le tableau suivant décrit certains des modules que vous pouvez utiliser pour filtrer les messages du journal :
| Préfixe | Description |
| --- | --- |
| `aws_smithy_runtime` | Enregistrement des câbles relatifs aux demandes et aux réponses |
| `aws_config` | Chargement des identifiants |
| `aws_sigv4` | Signature de demandes et demandes canoniques |
Pour déterminer quels modules vous devez inclure dans la sortie de votre journal, vous pouvez d'abord tout enregistrer, puis trouver le nom de la caisse dans le résultat du journal contenant les informations dont vous avez besoin. Vous pouvez ensuite définir la variable d'environnement en conséquence et exécuter à nouveau votre programme.
# Configuration des points de terminaison clients dans le AWS SDK pour Rust
Lorsqu'il AWS SDK pour Rust appelle an Service AWS, l'une de ses premières étapes consiste à déterminer où acheminer la demande. Ce processus est connu sous le nom de résolution des terminaux.
Vous pouvez configurer la résolution des points de terminaison pour le SDK lorsque vous créez un client de service. La configuration par défaut pour la résolution des points de terminaison est généralement correcte, mais il existe plusieurs raisons pour lesquelles vous souhaiterez peut-être modifier la configuration par défaut. Voici deux exemples de raisons :
+ Pour adresser des demandes à une version préliminaire d'un service ou à un déploiement local d'un service.
+ Pour accéder à des fonctionnalités de service spécifiques qui ne sont pas encore modélisées dans le SDK.
**Avertissement**
La résolution des points de terminaison est une rubrique avancée du SDK. Si vous modifiez les paramètres par défaut, vous risquez de casser votre code. Les paramètres par défaut s'appliquent à la plupart des utilisateurs dans les environnements de production.
Les points de terminaison personnalisés peuvent être définis globalement afin qu'ils soient utilisés pour toutes les demandes de service, ou vous pouvez définir un point de terminaison personnalisé pour un point spécifique Service AWS.
Les points de terminaison personnalisés peuvent être configurés à l'aide de variables d'environnement ou de paramètres du AWS `config` fichier partagé. Pour plus d'informations sur cette approche, consultez la section [Points de terminaison spécifiques au service](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html) dans le Guide de référence des *outils AWS SDKs et des outils*. Pour obtenir la liste complète des paramètres de `config` fichiers partagés et des variables d'environnement pour tous Services AWS, consultez la section [Identifiants pour les points de terminaison spécifiques à un service](https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html).
Cette personnalisation peut également être configurée dans votre code, comme indiqué dans les sections suivantes.
## Configuration personnalisée
Vous pouvez personnaliser la résolution des points de terminaison d'un client de service à l'aide de deux méthodes disponibles lorsque vous créez le client :
1. `endpoint_url(url: Into)`
1. `endpoint_resolver(resolver: impl crate::config::endpoint::ResolveEndpoint + `static)`
Vous pouvez définir les deux propriétés. Cependant, le plus souvent, vous n'en fournissez qu'un. Pour un usage général, `endpoint_url` il est le plus souvent personnalisé.
### Définir l'URL du point final
Vous pouvez définir une valeur pour `endpoint_url` pour indiquer un nom d'hôte « de base » pour le service. Cette valeur n'est toutefois pas définitive puisqu'elle est transmise en tant que paramètre à l'`ResolveEndpoint`instance du client. L'`ResolveEndpoint`implémentation peut ensuite inspecter et éventuellement modifier cette valeur pour déterminer le point final.
### Définir le résolveur de point de terminaison
L'`ResolveEndpoint`implémentation d'un client de service détermine le point final résolu que le SDK utilise pour une demande donnée. Un client de service appelle la `resolve_endpoint` méthode pour chaque demande et utilise la [https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html)valeur renvoyée par le résolveur sans autre modification.
L'exemple suivant montre comment fournir une implémentation de résolveur de point de terminaison personnalisée pour un client Amazon S3 qui résout un point de terminaison différent par étape, comme le développement et la production :
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
let stage = &self.stage;
EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
**Note**
Les résolveurs de points de terminaison, et par extension le `ResolveEndpoint` trait, sont spécifiques à chaque service et ne peuvent donc être configurés que dans la configuration du client du service. L'URL du point de terminaison, quant à elle, peut être configurée soit à l'aide d'une configuration partagée (applicable à tous les services dérivés), soit pour un service spécifique.
#### ResolveEndpoint paramètres
La `resolve_endpoint` méthode accepte les paramètres spécifiques au service qui contiennent les propriétés utilisées dans la résolution des points de terminaison.
Chaque service inclut les propriétés de base suivantes :
| Nom | Type | Description |
| --- | --- | --- |
| region | String | Celui du client Région AWS |
| endpoint | String | Une représentation sous forme de chaîne de l'ensemble de valeurs de endpointUrl |
| use\$1fips | Booléen | Si les points de terminaison FIPS sont activés dans la configuration du client |
| use\$1dual\$1stack | Booléen | Si les points de terminaison à double pile sont activés dans la configuration du client |
Services AWS peut spécifier des propriétés supplémentaires requises pour la résolution. Par exemple, les [paramètres du point de terminaison](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/endpoint/struct.Params.html) Amazon S3 incluent le nom du compartiment ainsi que plusieurs paramètres de fonctionnalités spécifiques à Amazon S3. Par exemple, la `force_path_style` propriété détermine si l'adressage d'hôte virtuel peut être utilisé.
Si vous implémentez votre propre fournisseur, vous ne devriez pas avoir à créer votre propre instance de paramètres de point de terminaison. Le SDK fournit les propriétés de chaque demande et les transmet à votre implémentation de`resolve_endpoint`.
### Comparez l'utilisation `endpoint_url` à l'utilisation `endpoint_resolver`
Il est important de comprendre que les deux configurations suivantes, l'une qui utilise `endpoint_url` et l'autre qui utilise`endpoint_resolver`, NE produisent PAS de clients présentant un comportement de résolution de point de terminaison équivalent.
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug, Default)]
struct CustomResolver;
impl ResolveEndpoint for CustomResolver {
fn resolve_endpoint(&self, _params: &Params) -> EndpointFuture<'_> {
EndpointFuture::ready(Ok(Endpoint::builder().url("https://endpoint.example").build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// use endpoint url
aws_sdk_s3::config::Builder::from(&config)
.endpoint_url("https://endpoint.example")
.build();
// Use endpoint resolver
aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(CustomResolver::default())
.build();
```
Le client qui définit le `endpoint_url` spécifie une URL de *base* qui est transmise au fournisseur (par défaut), qui peut être modifiée dans le cadre de la résolution du point de terminaison.
Le client qui définit le `endpoint_resolver` spécifie l'URL *finale* utilisée par le client Amazon S3.
## Exemples
Les points de terminaison personnalisés sont souvent utilisés pour les tests. Au lieu de passer des appels vers le service basé sur le cloud, les appels sont acheminés vers un service simulé hébergé localement. Deux de ces options sont les suivantes :
+ [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) local : version locale du service Amazon DynamoDB.
+ [LocalStack](https://github.com/localstack/localstack): un émulateur de service cloud qui s'exécute dans un conteneur sur votre machine locale.
Les exemples suivants illustrent deux manières différentes de spécifier un point de terminaison personnalisé pour utiliser ces deux options de test.
### Utiliser DynamoDB local directement dans le code
Comme décrit dans les sections précédentes, vous pouvez définir `endpoint_url` directement dans le code le remplacement du point de terminaison de base afin qu'il pointe vers le serveur DynamoDB local. Dans votre code :
```
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.test_credentials()
// DynamoDB run locally uses port 8000 by default.
.endpoint_url("http://localhost:8000")
.load()
.await;
let dynamodb_local_config = aws_sdk_dynamodb::config::Builder::from(&config).build();
let client = aws_sdk_dynamodb::Client::from_conf(dynamodb_local_config);
```
L'[exemple complet](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb/src/bin/list-tables-local.rs) est disponible sur GitHub.
### Utilisation LocalStack à l'aide du `config` fichier
Vous pouvez définir des [points de terminaison spécifiques au service](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html) dans votre fichier partagé. AWS `config` Le profil de configuration suivant est `endpoint_url` configuré pour se connecter `localhost` à un port`4566`. Pour plus d'informations sur la LocalStack configuration, consultez [Accès LocalStack via l'URL du point de terminaison](https://docs.localstack.cloud/references/network-troubleshooting/endpoint-url/) sur le site Web de la *LocalStackdocumentation*.
```
[profile localstack]
region=us-east-1
endpoint_url = http://localhost:4566
```
Le SDK récupérera les modifications apportées au `config` fichier partagé et les appliquera à vos clients du SDK lorsque vous utiliserez le `localstack` profil. En utilisant cette approche, votre code n'a pas besoin d'inclure de référence aux points de terminaison et ressemblerait à ce qui suit :
```
// set the environment variable `AWS_PROFILE=localstack` when running
// the application to source `endpoint_url` and point the SDK at the
// localstack instance
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.force_path_style(true)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
L'[exemple complet](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/localstack) est disponible sur GitHub.
# Remplacer une configuration à opération unique d'un client dans le AWS SDK pour Rust
Une fois que vous avez [créé un client de service](config-code.md), la configuration devient immuable et s'applique à toutes les opérations suivantes. Bien que la configuration ne puisse pas être modifiée à ce stade, elle peut être remplacée au cas par cas.
Chaque générateur d'opérations dispose d'une `customize` méthode permettant de créer un `CustomizableOperation` afin que vous puissiez remplacer une copie individuelle de la configuration existante. La configuration client d'origine ne sera pas modifiée.
L'exemple suivant montre la création d'un client Amazon S3 qui appelle deux opérations, la seconde étant remplacée pour être envoyée à une autre. Région AWS Toutes les invocations d'objets d'Amazon S3 utilisent la `us-east-1` région, sauf lorsque l'appel d'API est explicitement remplacé pour utiliser la région modifiée. `us-west-2`
```
use aws_config::{BehaviorVersion, Region};
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
// Request will be sent to "us-east-1"
s3.list_buckets()
.send()
.await?;
// Unset fields default to using the original config value
let modified = aws_sdk_s3::Config::builder()
.region(Region::from_static("us-west-2"));
// Request will be sent to "us-west-2"
s3.list_buckets()
// Creates a CustomizableOperation
.customize()
.config_override(modified)
.send()
.await?;
```
**Note**
L'exemple précédent concerne Amazon S3, mais le concept est le même pour toutes les opérations. Des méthodes supplémentaires peuvent être activées pour certaines opérations`CustomizeableOperation`.
Pour un exemple d'ajout d'un intercepteur à l'aide `customize` d'une seule opération, consultez[Intercepteur pour une opération spécifique uniquement](interceptors.md#interceptors-registration-specific).
# Configuration des paramètres de niveau HTTP dans le AWS SDK pour Rust
AWS SDK pour Rust fournit une fonctionnalité HTTP intégrée qui est utilisée par les Service AWS clients que vous créez dans votre code.
Par défaut, le SDK pour Rust utilise un client HTTPS basé sur `hyper``rustls`, et`aws-lc-rs`. Ce client devrait fonctionner correctement dans la plupart des cas d'utilisation sans configuration supplémentaire.
+ [https://docs.rs/hyper/latest/hyper/](https://docs.rs/hyper/latest/hyper/)est une bibliothèque HTTP de niveau inférieur pour Rust qui peut être utilisée avec le AWS SDK pour Rust pour effectuer des appels de service d'API.
+ [https://github.com/rustls/rustls](https://github.com/rustls/rustls)est une bibliothèque TLS moderne écrite en Rust qui possède des options intégrées pour les fournisseurs de cryptographie.
+ [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc)est une bibliothèque cryptographique à usage général contenant les algorithmes nécessaires au TLS et aux applications courantes.
+ [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)est un wrapper idiomatique autour de la `aws-lc` bibliothèque dans Rust.
La `aws-smithy-http-client` caisse fournit des options et une configuration supplémentaires si vous souhaitez choisir un autre fournisseur TLS ou cryptographique. Pour les cas d'utilisation plus avancés, nous vous encourageons à implémenter votre propre client HTTP ou à déposer une demande de fonctionnalité pour examen.
## Choisir un autre fournisseur TLS
La `aws-smithy-http-client` caisse fournit quelques fournisseurs TLS alternatifs.
Les fournisseurs suivants sont disponibles :
**`rustls` avec `aws-lc`**
Un fournisseur TLS basé sur [https://github.com/rustls/rustls](https://github.com/rustls/rustls)ce type d'utilisation [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)pour la cryptographie.
Il s'agit du comportement HTTP par défaut du SDK pour Rust. Si vous souhaitez utiliser cette option, vous n'avez aucune action supplémentaire à effectuer dans votre code.
**`s2n-tls`**
Un fournisseur TLS basé sur. [https://github.com/aws/s2n-tls](https://github.com/aws/s2n-tls)
**`rustls` avec `aws-lc-fips`**
Un fournisseur TLS basé sur [https://github.com/rustls/rustls](https://github.com/rustls/rustls)lequel utilise une version conforme à la norme FIPS de pour la cryptographie [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)
**`rustls` avec `ring`**
Un fournisseur TLS basé sur [https://github.com/rustls/rustls](https://github.com/rustls/rustls)ce type d'utilisation [https://github.com/briansmith/ring](https://github.com/briansmith/ring)pour la cryptographie.
### Conditions préalables
Utiliser `aws-lc-rs` ou `s2n-tls` nécessite un compilateur C (Clang ou GCC) pour construire. Pour certaines plateformes, la compilation peut également nécessiter CMake. Construire avec la fonctionnalité « fips » sur n'importe quelle plateforme nécessite CMake et Go. Pour plus d'informations, consultez le référentiel [AWS Libcrypto pour Rust (`aws-lc-rs`)](https://github.com/aws/aws-lc-rs/blob/main/aws-lc-rs/README.md) et les instructions de compilation.
### Comment utiliser un autre fournisseur TLS
La `aws-smithy-http-client` caisse fournit des options TLS supplémentaires. Pour que vos Service AWS clients utilisent un autre fournisseur TLS, remplacez l'`http_client`utilisation du chargeur depuis la `aws_config` caisse. Le client HTTP est utilisé à la fois pour les fournisseurs Services AWS d'informations d'identification.
L'exemple suivant montre comment utiliser le fournisseur `s2n-tls` TLS. Cependant, une approche similaire fonctionne également pour d'autres fournisseurs.
Pour compiler l'exemple de code, exécutez la commande suivante pour ajouter des dépendances à votre projet :
```
cargo add aws-smithy-http-client -F s2n-tls
```
Exemple de code :
```
use aws_smithy_http_client::{tls, Builder};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::S2nTls)
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## Activation du support FIPS
La `aws-smithy-http-client` caisse fournit une option pour activer une implémentation cryptographique conforme à la norme FIPS. Pour que vos Service AWS clients puissent utiliser le fournisseur conforme à la norme FIPS, remplacez l'`http_client`utilisation du chargeur depuis la caisse. `aws_config` Le client HTTP est utilisé à la fois pour les fournisseurs Services AWS d'informations d'identification.
**Note**
Le support FIPS nécessite des dépendances supplémentaires dans votre environnement de construction. Consultez les instructions de [fabrication](https://github.com/aws/aws-lc/blob/main/BUILDING.md) de la `aws-lc` caisse.
Pour compiler l'exemple de code, exécutez la commande suivante pour ajouter des dépendances à votre projet :
```
cargo add aws-smithy-http-client -F rustls-aws-lc-fips
```
L'exemple de code suivant active le support FIPS :
```
// file: main.rs
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder,
};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## Prioriser l'échange de clés post-quantique
Le fournisseur TLS par défaut est basé sur `rustls` l'utilisation de celui `aws-lc-rs` qui prend en charge l'algorithme d'échange de clés `X25519MLKEM768` post-quantique. Pour créer `X25519MLKEM768` l'algorithme ayant la priorité la plus élevée, vous devez ajouter le `rustls` package à votre caisse et activer l'indicateur de `prefer-post-quantum` fonctionnalité. Dans le cas contraire, il est disponible, mais ce n'est pas la priorité la plus élevée. Consultez la `rustls` [documentation](https://docs.rs/rustls/0.23.23/rustls/manual/_05_defaults/index.html#about-the-post-quantum-secure-key-exchange-x25519mlkem768) pour plus d'informations.
**Note**
Cela deviendra la valeur par défaut dans une future version.
## Remplacer le résolveur DNS
Le résolveur DNS par défaut peut être remplacé en configurant le client HTTP manuellement.
Pour compiler l'exemple de code, exécutez les commandes suivantes pour ajouter des dépendances à votre projet :
```
cargo add aws-smithy-http-client -F rustls-aws-lc
cargo add aws-smithy-runtime-api -F client
```
L'exemple de code suivant remplace le résolveur DNS :
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use aws_smithy_runtime_api::client::dns::{DnsFuture, ResolveDns};
use std::net::{IpAddr, Ipv4Addr};
/// A DNS resolver that returns a static IP address (127.0.0.1)
#[derive(Debug, Clone)]
struct StaticResolver;
impl ResolveDns for StaticResolver {
fn resolve_dns<'a>(&'a self, _name: &'a str) -> DnsFuture<'a> {
DnsFuture::ready(Ok(vec![IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))]))
}
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.build_with_resolver(StaticResolver);
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
**Note**
Par défaut, Amazon Linux 2023 (AL2023) ne met pas en cache le DNS au niveau du système d'exploitation.
## Personnalisation des certificats de l'autorité de certification racine
Par défaut, le fournisseur TLS charge les certificats racines natifs du système pour la plate-forme donnée. Pour personnaliser ce comportement afin de charger un bundle CA personnalisé, vous pouvez en configurer un `TlsContext` avec le vôtre`TrustStore`.
Pour compiler l'exemple de code, exécutez les commandes suivantes pour ajouter des dépendances à votre projet :
```
cargo add aws-smithy-http-client -F rustls-aws-lc
```
L'exemple suivant utilise `rustls` avec `aws-lc` mais fonctionnera pour tous les fournisseurs TLS pris en charge :
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use std::fs;
/// read the PEM encoded root CA (bundle) and return a custom TLS context
fn tls_context_from_pem(filename: &str) -> tls::TlsContext {
let pem_contents = fs::read(filename).unwrap();
// Create a new empty trust store (this will not load platform native certificates)
let trust_store = tls::TrustStore::empty()
.with_pem_certificate(pem_contents.as_slice());
tls::TlsContext::builder()
.with_trust_store(trust_store)
.build()
.expect("valid TLS config")
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.tls_context(tls_context_from_pem("my-custom-ca.pem"))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
# Configuration des intercepteurs dans le AWS SDK pour Rust
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. Ainsi, vous pouvez modifier une demande en cours de vol, traiter une demande de débogage, afficher les erreurs, etc.
L'exemple suivant montre un intercepteur simple qui ajoute un en-tête supplémentaire à toutes les demandes sortantes avant que la boucle de nouvelle tentative ne soit entrée :
```
use std::borrow::Cow;
use aws_smithy_runtime_api::client::interceptors::{
Intercept,
context::BeforeTransmitInterceptorContextMut,
};
use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
use aws_smithy_types::config_bag::ConfigBag;
use aws_smithy_runtime_api::box_error::BoxError;
#[derive(Debug)]
struct AddHeaderInterceptor {
key: Cow<'static, str>,
value: Cow<'static, str>,
}
impl AddHeaderInterceptor {
fn new(key: &'static str, value: &'static str) -> Self {
Self {
key: Cow::Borrowed(key),
value: Cow::Borrowed(value),
}
}
}
impl Intercept for AddHeaderInterceptor {
fn name(&self) -> &'static str {
"AddHeader"
}
fn modify_before_retry_loop(
&self,
context: &mut BeforeTransmitInterceptorContextMut<'_>,
_runtime_components: &RuntimeComponents,
_cfg: &mut ConfigBag,
) -> Result<(), BoxError> {
let headers = context.request_mut().headers_mut();
headers.insert(self.key.clone(), self.value.clone());
Ok(())
}
}
```
Pour plus d'informations et pour connaître les hooks d'interception disponibles, consultez le trait [Intercept.](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/interceptors/trait.Intercept.html)
## 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 est différent selon que vous souhaitez que l'intercepteur s'applique à toutes les opérations pour votre client ou uniquement à des opérations spécifiques.
### Intercepteur pour toutes les opérations sur un client de service
Pour enregistrer un intercepteur pour l'ensemble du client, ajoutez-le en utilisant le `Builder` modèle.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// All service operations invoked using 's3' will have the header added.
let s3_conf = aws_sdk_s3::config::Builder::from(&config)
.interceptor(AddHeaderInterceptor::new("x-foo-version", "2.7"))
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_conf);
```
### Intercepteur pour une opération spécifique uniquement
Pour enregistrer un intercepteur pour une seule opération, utilisez l'`customize`extension. Vous pouvez remplacer les configurations de vos clients de service au niveau de chaque opération à l'aide de cette méthode. Pour plus d'informations sur les opérations personnalisables, consultez[Remplacer une configuration à opération unique d'un client dans le AWS SDK pour Rust](peroperation.md).
```
// Only the list_buckets operation will have the header added.
s3.list_buckets()
.customize()
.interceptor(AddHeaderInterceptor::new("x-bar-version", "3.7"))
.send()
.await?;
```