Spécification d’en-têtes conditionnels pour les opérations de service Blob
Plusieurs opérations de service BLOB prennent en charge l'utilisation des en-têtes conditionnels. Vous pouvez spécifier des en-têtes conditionnels pour effectuer une opération uniquement si une condition spécifiée a été remplie.
Le service Blob suit la spécification du protocole HTTP/1.1 pour les en-têtes conditionnels.
En-têtes conditionnels pris en charge
Les en-têtes conditionnels pris en charge sont décrits dans le tableau suivant.
| En-tête conditionnel | Description |
|---|---|
If-Modified-Since |
Valeur DateTime. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez Représentation de valeurs date-heure dans les en-têtes. Spécifiez cet en-tête pour exécuter l'opération uniquement si la ressource a été modifiée depuis le temps indiqué. |
If-Unmodified-Since |
Valeur DateTime. Le format de date est conforme à la RFC 1123. Pour plus d’informations, consultez Représentation de valeurs date-heure dans les en-têtes. Spécifiez cet en-tête pour exécuter l'opération uniquement si la ressource n'a pas été modifiée depuis la date/l'heure indiquées. |
If-Match |
Spécifiez une valeur ETag. Spécifiez cet en-tête pour exécuter l'opération uniquement si l'ETag de la ressource correspond à la valeur spécifiée. Pour les versions du 18/08/2011 et ultérieures, l'ETag peut être spécifié entre guillemets. |
If-None-Match |
Spécifiez une valeur ETag ou le caractère générique *. Spécifiez cet en-tête pour exécuter l'opération uniquement si l'ETag de la ressource ne correspond pas à la valeur spécifiée. Pour les versions du 18/08/2011 et ultérieures, l'ETag peut être spécifié entre guillemets. Spécifiez le caractère générique (*) pour exécuter l'opération uniquement si la ressource n'existe pas, et faire échouer l'opération si elle existe. |
Spécification des en-têtes conditionnels pour les opérations de lecture du service BLOB dans la version du 15/08/2013 ou les versions ultérieures
À compter de la version 2013-08-15, les opérations Get Blob et Get Blob Properties prennent en charge plusieurs en-têtes conditionnels. Spécifiez n'importe quelle combinaison d'en-têtes conditionnels pris en charge. Le service BLOB évalue ces conditions d'après l'expression suivante :
If-Match && If-Unmodified-Since && (If-None-Match || If-Modified-Since)
Vous pouvez également fournir plusieurs valeurs séparées par des virgules pour If-Match et If-None-Match. Si vous spécifiez plusieurs valeurs pour If-Match, le service BLOB exécute une opération OR logique sur toutes les valeurs fournies avant d'évaluer l'expression entière. Si vous spécifiez plusieurs valeurs pour if-None-Match, le service exécute une opération AND logique avant d'évaluer l'expression entière. La spécification de plusieurs valeurs pour If-Modified-Since et If-Unmodified-Since n'est pas prise en charge et génère le code d'erreur 400 (Bad Request).
Cette fonctionnalité est activée afin de se conformer à la spécification HTTP/1.1 et de répondre aux scénarios où un réseau de distribution de contenu (CDN) ou un serveur proxy ajoute des en-têtes conditionnels supplémentaires à une demande en vol. Voici quelques exemples des différentes combinaisons d'en-têtes conditionnels.
Exemple 1 :
Envisagez une requête Get Blob contenant les If-Match en-têtes et If-Modified-Since . Le tableau suivant indique le résultat si les en-têtes sont évalués individuellement, et le résultat s'ils sont évalués combinés.
| En-têtes conditionnels | Résultat en cas d'évaluation individuelle | Résultat en cas d'évaluation combinée |
|---|---|---|
If-Match |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-Match |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
304 (Non modifié) | 412 (Échec de la précondition) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 304 (Non modifié) |
If-Modified-Since |
304 (Non modifié) | 304 (Non modifié) |
Exemple 2 :
Examinez une demande contenant les en-têtes If-None-Match et If-Modified-Since.
| En-têtes conditionnels | Résultat en cas d'évaluation individuelle | Résultat en cas d'évaluation combinée |
|---|---|---|
If-None-Match |
304 (Non modifié) | 200 (OK) |
If-Modified-Since |
200 (OK) | 200 (OK) |
If-None-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
200 (OK) | 200 (OK) |
If-None-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
304 (Non modifié) | 200 (OK) |
If-None-Match |
304 (Non modifié) | 304 (Non modifié) |
If-Modified-Since |
304 (Non modifié) | 304 (Non modifié) |
Exemple 3 :
Examinez une demande contenant les en-têtes If-Modified-Since, If-Match et If-Unmodified-Since.
| En-têtes conditionnels | Résultat en cas d'évaluation individuelle | Résultat en cas d'évaluation combinée |
|---|---|---|
If-Modified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-Match |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Unmodified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-Modified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-Match |
200 (OK) | 412 (Échec de la précondition) |
If-Unmodified-Since |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
304 (Non modifié) | 412 (Échec de la précondition) |
If-Match |
200 (OK) | 412 (Échec de la précondition) |
If-Unmodified-Since |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
304 (Non modifié) | 304 (Non modifié) |
If-Match |
200 (OK) | 304 (Non modifié) |
If-Unmodified-Since |
200 (OK) | 304 (Non modifié) |
Exemple 4 :
Examinez une demande contenant les en-têtes If-Modified-Since, If-None-Match, If-Unmodified-Since et If-Match.
| Combinaison | Code d'état HTTP individuel | Résultat d'état Get Blob |
|---|---|---|
If-Modified-Since |
200 (OK) | 200 (OK) |
If-None-Match |
200 (OK) | 200 (OK) |
If-Unmodified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-None-Match |
304 (Non modifié) | 412 (Échec de la précondition) |
If-Unmodified-Since |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Match |
200 (OK) | 412 (Échec de la précondition) |
If-Modified-Since |
200 (OK) | 200 (OK) |
If-None-Match |
304 (Non modifié) | 200 (OK) |
If-Unmodified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
304 (Non modifié) | 412 (Échec de la précondition) |
If-None-Match |
200 (OK) | 412 (Échec de la précondition) |
If-Unmodified-Since |
200 (OK) | 412 (Échec de la précondition) |
If-Match |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
304 (Non modifié) | 412 (Échec de la précondition) |
If-None-Match |
200 (OK) | 412 (Échec de la précondition) |
If-Unmodified-Since |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Match |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Modified-Since |
304 (Non modifié) | 200 (OK) |
If-None-Match |
200 (OK) | 200 (OK) |
If-Unmodified-Since |
200 (OK) | 200 (OK) |
If-Match |
200 (OK) | 200 (OK) |
If-Modified-Since |
304 (Non modifié) | 412 (Échec de la précondition) |
If-None-Match |
304 (Non modifié) | 412 (Échec de la précondition) |
If-Unmodified-Since |
412 (Échec de la précondition) | 412 (Échec de la précondition) |
If-Match |
200 (OK) | 412 (Échec de la précondition) |
Spécification d'en-têtes conditionnels pour les opérations de lecture dans les versions antérieures à la version du 15/08/2013 et pour les opérations d'écriture (toutes les versions)
Lorsque vous appelez des opérations de lecture du service Blob (Obtenir des propriétés Blob et Obtenir des objets blob) avec des versions antérieures au 15/08/2013, et lorsque vous appelez une opération d’écriture quelle que soit la version, gardez à l’esprit les points suivants :
Si une demande spécifie les en-têtes
If-None-MatchetIf-Modified-Since, la demande est évaluée en fonction des critères spécifiés dansIf-None-Match.Si une demande spécifie les en-têtes
If-MatchetIf-Unmodified-Since, la demande est évaluée en fonction des critères spécifiés dansIf-Match.À l'exception des deux combinaisons d'en-têtes conditionnels répertoriées ci-dessus, une demande peut spécifier uniquement un en-tête conditionnel. La spécification de plusieurs en-têtes conditionnels entraîne un code d'état 400 (
Bad Request).Si une réponse comprend un ETag, vérifiez la version de la demande et la réponse avant de traiter l'ETag. Par exemple, la version 2011-08-18 et les versions ultérieures renvoient un ETag entre guillemets, mais les versions antérieures ne le font pas. Vérifiez que votre application peut traiter les deux formats d'ETag avant qu'ils soient évalués.
RFC 2616 autorise plusieurs valeurs ETag dans un seul en-tête, mais les demandes adressées au service Blob ne peuvent inclure qu’une seule valeur ETag. La spécification de plusieurs valeurs d'ETag entraîne un code d'état 400 (
Bad Request).
Opérations prenant en charge les en-têtes conditionnels
Les opérations qui prennent en charge les en-têtes conditionnels sont décrites dans le tableau suivant.
| Opération REST | Type d'opération | En-têtes conditionnels pris en charge |
|---|---|---|
| Append Block (version 21-02-2015 et ultérieure) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Append Block From URL (version 2018-11-09 et ultérieure) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Copy Blob | Lire et écrire | Pour les conditions sur l'objet blob de destination : - If-Modified-Since - If-Unmodified-Since - If-Match - If-None-Match - x-ms-if-tags Pour les conditions sur l'objet blob source : - x-ms-source-if-modified-since - x-ms-source-if-unmodified-since - x-ms-source-if-match - x-ms-source-if-none-match - x-ms-source-if-tags |
| Delete Blob | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Delete Container | Write | If-Modified-Since If-Unmodified-Since |
| Get Blob | Lire | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Get Blob Metadata | Lire | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Get Blob Properties | Lire | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Obtenir les étiquettes d’objet blob (version 2019-12-12 et ultérieure) |
Lire | x-ms-if-tags |
| Get Block List | Lire | x-ms-if-tags |
| Obtenir les portées de page | Lire | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Bail Blob | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Lease Container | Write | If-Modified-Since If-Unmodified-Since |
| Placer un objet blob à partir d’une URL | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match Pour les conditions sur l'objet blob source : - x-ms-source-If-Modified-Since - x-ms-source-if-Unmodified-Since - x-ms-source-If-Match - x-ms-source-If-None-Match |
| Put Blob | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Put Block From URL (version 28-03-2018 et ultérieure) |
Write | x-ms-source-If-Modified-Since x-ms-source-If-Unmodified-Since x-ms-source-If-Match x-ms-source-If-None-Match |
| Put Block List | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Put Page | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Put Page From URL (version 2018-11-09 et ultérieure) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Blob Metadata | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Blob Properties | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Container ACL | Write | If-Modified-Since If-Unmodified-Since |
| Définir les métadonnées du conteneur | Write | If-Modified-Since |
| Définir des étiquettes d’objet blob (version 2019-12-12 et ultérieure) |
Write | x-ms-if-tags |
| Set Blob Tier | Lecture ou écriture | x-ms-if-tags |
| Snapshot Blob | Lire | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Définir la stratégie d’immuabilité des objets blob | Write | If-Unmodified-Since |
Les opérations de données du service BLOB suivantes ne prennent actuellement pas en charge les en-têtes conditionnels :
Codes de réponse HTTP pour les opérations prenant en charge les en-têtes conditionnels
Si la demande comprend un en-tête conditionnel et que la condition spécifiée n'est pas remplie par la ressource qui est demandée, le service BLOB renvoie un code de réponse HTTP. Les codes de réponse renvoyés sont conformes à la spécification du protocole HTTP/1.1 (RFC 2616).
Les méthodes de la bibliothèque de client Azure .NET convertissent ces codes de réponse d’erreur en objet StorageException.
Opérations de lecture
Le tableau suivant indique les codes de réponse renvoyés pour une condition non remplie pour chaque en-tête conditionnel lorsque l'opération est une opération de lecture. Les opérations de lecture utilisent les verbes GET ou HEAD.
| En-tête conditionnel | Le code de réponse si la condition n'a pas été remplie |
|---|---|
If-Modified-Since |
Non modifié (304 (Not Modified)) |
If-Unmodified-Since |
Échec de la précondition (412 (Precondition Failed)) |
If-Match |
Échec de la précondition (412 (Precondition Failed)) |
If-None-Match |
Non modifié (304 (Not Modified)) |
Reportez-vous aux exemples ci-dessus pour obtenir les résultats en utilisant plusieurs en-têtes avec la version du 15/08/2013 ou les versions ultérieures.
Opérations d'écriture
Le tableau suivant indique les codes de réponse renvoyés pour une condition non remplie pour chaque en-tête conditionnel lorsque l'opération est une opération d'écriture. Les opérations d'écriture utilisent les verbes PUT ou DELETE.
| En-tête conditionnel | Le code de réponse si la condition n'a pas été remplie |
|---|---|
If-Modified-Since |
Échec de la précondition (412 (Precondition Failed)) |
If-Unmodified-Since |
Échec de la précondition (412 (Precondition Failed)) |
If-Match |
Échec de la précondition (412 (Precondition Failed)) |
If-None-Match |
Échec de la précondition (412 (Precondition Failed)) |
Opérations de copie
Le tableau suivant indique les codes de réponse renvoyés pour une condition non remplie pour chaque en-tête conditionnel lorsque l'opération est une opération de copie. L’opération Copier l’objet blob utilise les verbes PUT.
| En-tête conditionnel | Le code de réponse si la condition n'a pas été remplie |
|---|---|
If-Modified-Since |
Échec de la précondition (412 (Precondition Failed)) |
If-Unmodified-Since |
Échec de la précondition (412 (Precondition Failed)) |
If-Match |
Échec de la précondition (412 (Precondition Failed)) |
If-None-Match |
Échec de la précondition (412 (Precondition Failed)) |
x-ms-source-if-modified-since |
Échec de la précondition (412 (Precondition Failed)) |
x-ms-source-if-unmodified-since |
Échec de la précondition (412 (Precondition Failed)) |
x-ms-source-if-match |
Échec de la précondition (412 (Precondition Failed)) |
x-ms-source-if-none-match |
Échec de la précondition (412 (Precondition Failed)) |
Opérations conditionnelles de balises
En plus des en-têtes conditionnels HTTP standard pris en charge par le service Blob, plusieurs opérations prennent également en charge les conditions par rapport aux balises sur une ressource d’objet blob.
| En-tête conditionnel | Description |
|---|---|
x-ms-if-tags |
Version 2019-12-12 et ultérieure. Valeur TagsPredicate. Spécifiez cet en-tête pour effectuer l’opération uniquement si le prédicat est évalué par rapport aux true balises de l’objet blob. |
x-ms-source-if-tags |
Version 2019-12-12 et ultérieure. S’applique uniquement à Copier l’objet blob. Valeur TagsPredicate. Spécifiez cet en-tête pour effectuer l’opération uniquement si le prédicat est évalué par rapport aux true balises de l’objet blob source. |
Si l’en-tête x-ms-if-tags conditionnel ou x-ms-source-if-tags est présent dans une demande et que le TagsPredicate prend falsela valeur , le service Blob retourne le code d’erreur 412 (Échec de la condition préalable) pour l’opération.
L’appelant doit être autorisé à lire les balises sur un objet blob pour utiliser les x-ms-if-tags en-têtes conditionnels ou x-ms-source-if-tags .
Syntaxe des prédicats de balises
Le service Blob prend en charge un sous-ensemble de la grammaire de la clause WHERE ANSI SQL pour la valeur de l’en-tête TagsPredicate . Les opérateurs suivants sont pris en charge :
| Opérateur | Description | Exemple |
|---|---|---|
= |
Égal à | Status = 'In Progress' |
<> |
Différent de | Status <> 'Done' |
> |
Supérieur à | LastModified > '2018-06-18 20:51:26Z' |
>= |
Supérieur ou égal à | Priority >= '05' |
< |
Inférieur à | Age < '032' |
<= |
Inférieur ou égal à | Reviewer <= 'Smith' |
AND |
ET logique | Name > 'C' AND Name < 'D'Age > '032' AND Age < '100' |
OR |
OU logique | Status = 'Done' or LastModified > '2018-06-18 20:51:26Z' |
Toutes les valeurs de balise sont des chaînes, et les opérateurs relationnels binaires pris en charge utilisent un tri lexicographique des valeurs de balise. Pour prendre en charge les types de données autres que les chaînes, y compris les nombres et les dates, un remplissage approprié et une mise en forme triable doivent être utilisés. Les valeurs de balise doivent être placées entre guillemets simples.
Si les noms de balise sont des identificateurs SQL standard, ils peuvent être présents sans échappement . s’ils contiennent des caractères spéciaux, ils doivent être délimités par des guillemets doubles (par exemple, « TagName » = 'TagValue').
Les expressions peuvent inclure des comparaisons pour plusieurs noms et valeurs de balise. Les parenthèses (( et )) peuvent être utilisées pour regrouper des expressions logiques et contrôler l’ordre canonique de fonctionnement. Un TagsPredicate peut inclure au plus dix (10) opérations logiques.
Le service de stockage rejette toute requête qui contient une expression non valide avec le code d’erreur 400 (Demande incorrecte).