Configurer les délais d'expiration dans AWS SDK for Java 2.x

AWS SDK for Java 2.x Il fournit plusieurs niveaux de configuration du délai d'expiration pour vous aider à créer des applications résilientes. Le SDK propose différents types de délais d'attente qui fonctionnent ensemble pour optimiser les performances et la fiabilité de votre application.

Il existe deux catégories principales de délais d'attente dans le SDK :

• Délais d'expiration des clients de service : délais d'expiration élevés qui contrôlent les opérations de l'API

• Temporisations du client HTTP : délais d'expiration de faible niveau qui contrôlent les communications réseau

Délais d'expiration du service client

Les délais d'attente des clients de service fonctionnent au niveau de l'API et contrôlent le comportement global des opérations de service, y compris les nouvelles tentatives et les tentatives multiples.

Délai d'expiration des appels d'API

Le délai d'expiration des appels d'API définit la durée maximale d'une opération d'API complète, y compris toutes les tentatives de nouvelle tentative. Ce délai limite strictement la durée pendant laquelle votre application attend la fin d'une opération.

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofMinutes(2))  // Total time for entire operation, such as when you call the getObject method.
        .build())
    .build();

Caractéristiques principales :

• Inclut toutes les tentatives de nouvelle tentative.

• Inclut le temps passé à attendre entre deux tentatives.

• Fournit un temps d'attente maximal absolu.

• Empêche les opérations de s'exécuter indéfiniment.

Délai d'expiration des tentatives d'appel d'API

Le délai d'expiration des tentatives d'appel d'API définit la durée maximale d'une seule tentative d'opération d'API. Si ce délai est dépassé, le SDK tente à nouveau l'opération (si de nouvelles tentatives sont configurées) plutôt que d'échouer tout l'appel.

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(30))  // Time for single attempt.
        .build())
    .build();

Caractéristiques principales :

• S'applique uniquement aux tentatives individuelles.

• Permet un échec rapide et une nouvelle tentative pour les demandes lentes.

• Doit être inférieur au délai d'expiration de l'appel d'API.

• Permet d'identifier les problèmes transitoires et d'y remédier.

Configurer les délais d'expiration des clients de service

Vous pouvez configurer les délais d'expiration des clients de service globalement pour toutes les opérations ou par demande :

Configuration globale :

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L)))
    .build();
// When you use the s3Client for an API operation, the SDK uses the configured timeout values.

Configuration par demande :

S3Client basicS3Client = S3Client.create();

// The following configuration uses the same settings as shown before, but these settings
// apply to only the `putObject` call. When you use `basicS3Client` in another API call without
// supplying the override configuration, there are no API timeout limits. No timeout limits is the default for the SDK.
AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("amzn-s3-demo-bucket")
        .key("example-key")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));

Bonnes pratiques en matière de délais d'expiration des API

Le SDK pour Java 2.x ne définit pas les délais d'expiration des appels d'API ni les délais d'expiration des tentatives d'appels d'API individuels par défaut. Définissez des délais d'expiration pour les tentatives individuelles et pour l'ensemble de la demande. Cela permet à votre application d'échouer rapidement lorsque des problèmes transitoires prolongent les tentatives de demande ou lorsque des problèmes réseau fatals surviennent.

Expiration des délais du client HTTP

Les délais d'expiration des clients HTTP fonctionnent au niveau du réseau et contrôlent différents aspects de la communication HTTP. Ces délais varient en fonction de l'implémentation du client HTTP que vous utilisez.

Délai de connexion

Le délai d'expiration de la connexion contrôle le temps d'attente lors de l'établissement d'une nouvelle connexion avec le Service AWS point de terminaison.

// Available with all HTTP clients.
ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(5L))
    .build();

Objectif :

• Évite de s'accrocher aux problèmes de connectivité réseau.

• Échoue rapidement lorsque les services sont inaccessibles.

• Essentiel pour les applications nécessitant une gestion réactive des erreurs.

Délai d'expiration du socket (Apache et URLConnection clients)

Le délai d'attente du socket détermine le temps d'attente des données sur une connexion établie.

ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30L))  // Time to wait for response data.
    .build();

Délais de lecture et d'écriture (client Netty)

Le client Netty fournit des délais d'expiration distincts pour les opérations de lecture et d'écriture :

NettyNioAsyncHttpClient.builder()
    .readTimeout(Duration.ofSeconds(30L))   // Reading response data.
    .writeTimeout(Duration.ofSeconds(30L))  // Writing request data.
    .build();

Délai de négociation TLS (client Netty)

Contrôle le temps imparti pour la TLS/SSL poignée de main :

NettyNioAsyncHttpClient.builder()
    .tlsNegotiationTimeout(Duration.ofSeconds(3L))
    .build();

Expiration du pool de connexions

Certains clients HTTP fournissent des délais d'expiration pour les opérations du pool de connexions :

ApacheHttpClient.builder()
    .connectionAcquisitionTimeout(Duration.ofSeconds(10L))  // Wait for pool connection.
    .connectionTimeToLive(Duration.ofMinutes(5L))           // Maximum connection age.
    .connectionMaxIdleTime(Duration.ofSeconds(60L))         // Maximum idle time.
    .build()

Le Configuration des clients HTTP contient plus d'informations sur les clients HTTP dans le AWS SDK for Java 2.x

Interactions et hiérarchie liées au délai d'expiration

Pour une configuration correcte, il est essentiel de comprendre comment les différents délais interagissent :

Hiérarchie des délais

API Call Timeout (2 minutes)
├── Retry Attempt 1
│   ├── API Call Attempt Timeout (45 seconds)
│   └── HTTP Client Timeouts
│       ├── Connection Timeout (5 seconds)
│       ├── TLS Negotiation Timeout (3 seconds)
│       └── Read/Write Timeout (30 seconds)
├── Retry Attempt 2
│   └── [Same structure as Attempt 1]
└── Retry Attempt 3
    └── [Same structure as Attempt 1]

Règles de configuration

Délai d'attente d'appel d'API ≥ délai d'expiration de tentative d'appel d'API

// Correct configuration.
.apiCallTimeout(Duration.ofMinutes(2))         // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds.

Délai d'expiration des tentatives d'appel d'API ≥ délais d'expiration du client HTTP

// HTTP client timeouts must be less than attempt timeout.
.apiCallAttemptTimeout(Duration.ofSeconds(30L))   // 30 seconds.
// HTTP client configuration.
.connectionTimeout(Duration.ofSeconds(5L))        // 5 seconds.
.readTimeout(Duration.ofSeconds(25L))             // 25 seconds (< 30).

Tenez compte de plusieurs tentatives

// If you have 3 retry attempts, each taking up to 30 seconds
// API call timeout must be at least 90 seconds plus overhead.
.apiCallTimeout(Duration.ofMinutes(2L))          // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30))   // 30 seconds per attempt.

Utiliser des paramètres de configuration intelligents par défaut

Le SDK fournit des paramètres par défaut intelligents qui configurent automatiquement les valeurs de délai d'expiration appropriées :

// Enable smart defaults.
S3Client client = S3Client.builder()
    .defaultsMode(DefaultsMode.AUTO)  // Automatically choose appropriate defaults.
    .build();

// Available modes:
// - STANDARD: Balanced defaults
// - IN_REGION: Optimized for same-region calls
// - CROSS_REGION: Optimized for cross-region calls  
// - MOBILE: Optimized for mobile applications
// - AUTO: Automatically detect and choose appropriate mode
// - LEGACY: Provides settings that were used before smart defaults existed.

Les paramètres par défaut intelligents configurent automatiquement :

• Valeurs du délai d'expiration de la connexion.

• Valeurs du délai d'expiration des négociations TLS.

• Autres paramètres du client.

Récapitulatif

Une configuration efficace du délai d'expiration AWS SDK for Java 2.x nécessite de comprendre l'interaction entre les délais d'expiration du client de service et les délais d'expiration du client HTTP :

1. Les délais d'expiration des clients de service contrôlent le comportement de haut niveau de l'API.

2. Les délais d'expiration du client HTTP contrôlent le comportement du réseau de bas niveau.

3. Une hiérarchie appropriée garantit que les délais d'expiration fonctionnent efficacement ensemble.

4. Les valeurs par défaut intelligentes constituent de bons points de départ pour la plupart des applications.

Configurez les délais d'expiration en fonction de votre cas d'utilisation afin de créer des applications à la fois résilientes aux problèmes de réseau et réactives aux utilisateurs.