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. 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. 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 respecter 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 inflight. Voici quelques exemples des différentes combinaisons d'en-têtes conditionnels.

Exemple 1 :

Envisagez une requête Get Blob contenant les en-têtes et If-Modified-Since les If-Match en-têtes. 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)

Lors de l’appel d’opérations de lecture du service Blob (Get Blob and Get Blob Properties) avec des versions antérieures à 2013-08-15, et lors de l’appel d’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-Match et If-Modified-Since, la demande est évaluée en fonction des critères spécifiés dans If-None-Match.

  • Si une demande spécifie les en-têtes If-Match et If-Unmodified-Since, la demande est évaluée en fonction des critères spécifiés dans If-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 2015-02-21 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 2018-03-28 et ultérieures)
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 des métadonnées de 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 une stratégie d’immuabilité d’objet 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 cliente 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))

Étiquettes d’opérations conditionnelles

Outre les 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 ou x-ms-source-if-tags l’en-tête conditionnel est présent dans une requête et que le TagsPredicate résultat est évalué false, le service Blob retourne le code d’erreur 412 (Échec de la condition préalable) pour l’opération.

L’appelant doit avoir l’autorisation de lire les balises sur un objet blob pour utiliser les en-têtes conditionnels ou x-ms-source-if-tags les x-ms-if-tags en-têtes conditionnels.

Syntaxe de prédicat des balises

Le service Blob prend en charge un sous-ensemble de la grammaire de clause ANSI SQL WHERE pour la valeur de l’en-têteTagsPredicate. 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 non-chaînes, y compris les nombres et les dates, le remplissage approprié et la 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 de SQL réguliers, 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 d’étiquette. Les parenthèses (( et )) peuvent être utilisées pour regrouper des expressions logiques et contrôler l’ordre canonique de l’opération. Un TagsPredicate peut inclure au maximum dix (10) opérations logiques.

Le service de stockage rejette toute demande qui contient une expression non valide avec le code d’erreur 400 (requête incorrecte).

Voir aussi

Blob Service Concepts