En-tête Range
Baseline
Widely available
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
L'en-tête de requête HTTP Range indique la partie d'une ressource que le serveur doit retourner.
Plusieurs parties peuvent être demandées en même temps dans un seul en-tête Range, et le serveur peut renvoyer ces plages dans un document multipartie.
Si le serveur renvoie des plages, il utilise le code d'état 206 Partial Content pour la réponse.
Si les plages sont invalides, le serveur retourne l'erreur 416 Range Not Satisfiable.
Un serveur qui ne prend pas en charge les requêtes de plage peut ignorer l'en-tête Range et retourner la ressource entière avec un code d'état 200.
Les anciens navigateurs utilisaient un en-tête de réponse Accept-Ranges: none pour désactiver des fonctionnalités comme « pause » ou « reprendre » dans les gestionnaires de téléchargement, mais comme le fait qu'un serveur ignore l'en-tête Range a la même signification que de répondre avec Accept-Ranges: none, cet en-tête est rarement utilisé de cette manière.
Actuellement, seules les unités bytes sont enregistrées (angl.), ce sont des décalages (indexés à partir de zéro et inclusifs).
Si les données demandées ont un codage de contenu appliqué, chaque plage d'octets représente la séquence d'octets encodés, et non les octets obtenus après décodage.
L'en-tête est un en-tête de requête autorisé par CORS lorsque la directive spécifie une seule plage d'octets.
| Type d'en-tête | En-tête de requête |
|---|---|
| En-tête de requête interdit | Non |
Syntaxe
Range: <unit>=<range-start>-
Range: <unit>=<range-start>-<range-end>
Range: <unit>=<range-start>-<range-end>, …, <range-startN>-<range-endN>
Range: <unit>=-<suffix-length>
Directives
<unit>-
L'unité dans laquelle les plages sont définies. Actuellement, seule l'unité
bytesest enregistrée. <range-start>-
Un entier dans l'unité donnée indiquant la position de début de la plage demandée.
<range-end>-
Un entier dans l'unité donnée indiquant la position de fin de la plage demandée. Cette valeur est optionnelle et, si elle est omise, la fin de la ressource est utilisée comme fin de la plage.
<suffix-length>-
Un entier indiquant le nombre d'unités à la fin de la ressource à retourner.
Exemples
Les exemples suivants montrent comment effectuer des requêtes en utilisant l'en-tête Range pour des requêtes autorisées par CORS, et pour demander plusieurs plages.
D'autres exemples sont disponibles dans le guide Requêtes de plage HTTP.
Plages d'octets uniques et requêtes autorisées par CORS
L'en-tête Range est un en-tête de requête autorisé par CORS lorsque la valeur est une seule plage d'octets.
Cela signifie qu'il peut être utilisé dans des requêtes inter-origines sans déclencher de pré-vérification, ce qui est utile pour demander des médias et reprendre des téléchargements.
L'exemple suivant demande les 500 premiers octets d'une ressource :
Range: bytes=0-499
Pour demander les 500 octets suivants :
Range: bytes=500-999
Omettre la position de fin demande toutes les unités restantes de la ressource, ainsi les 100 derniers octets d'une ressource de 1000 octets peuvent être demandés avec :
Range: bytes=900-
Sinon, si la taille d'une ressource est inconnue, les n derniers octets peuvent être demandés en utilisant une plage suffixe de -n :
Range: bytes=-100
Demander plusieurs plages
Pour une ressource d'une longueur de 10 000 octets, l'exemple suivant demande trois plages distinctes ; 200-999 (800 octets), 2000-2499 (500 octets), et enfin 9500-.
La valeur de spécification de plage 9500- omet une position de fin ce qui indique que tous les octets à partir de 9500 font partie de la troisième plage (500 octets).
Range: bytes=200-999, 2000-2499, 9500-
Cet exemple demande les 500 premiers et les 500 derniers octets du fichier. La requête peut être rejetée par le serveur si ces plages se chevauchent (par exemple, si la ressource demandée fait moins de 1000 octets).
Range: bytes=0-499, -500
Vérifier si un serveur prend en charge les requêtes de plage
La commande curl suivante effectue une requête HEAD pour une image :
curl -v --http1.1 -I https://i.imgur.com/z4d4kWk.jpg
# ou en utilisant la méthode OPTIONS :
# curl -v --http1.1 -X OPTIONS https://i.imgur.com/z4d4kWk.jpg
Ceci donne la requête HTTP suivante :
HEAD /z4d4kWk.jpg HTTP/1.1
Host: i.imgur.com
User-Agent: curl/8.7.1
Accept: */*
Le serveur répond avec un code 200, et l'en-tête Accept-Ranges: bytes est présent (certains en-têtes sont omis pour la clarté) :
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 146515
Content-Type: image/jpeg
…
Accept-Ranges: bytes
Récupérer une plage depuis une URL blob
L'URL blob: prend également en charge les requêtes de plage en utilisant fetch().
const blob = new Blob(["Hello, world!"], { type: "text/plain" });
const url = URL.createObjectURL(blob);
fetch(url, {
headers: {
Range: "bytes=7-11",
},
})
.then((response) => response.text())
.then((text) => console.log(text)); // "world"
Spécifications
| Specification |
|---|
| HTTP Semantics # field.range |
Compatibilité des navigateurs
Voir aussi
- L'en-tête conditionnel
If-Range - L'en-tête de réponse
Content-Range - L'en-tête
Content-Type - L'en-tête
Accept-Ranges - Le code de statut
206 Partial Content - Le code de statut
416 Range Not Satisfiable - Le guide des requêtes de plage HTTP
- L'entrée de glossaire En-tête de requête autorisé par CORS