Méthode PUT (ADO.NET Data Services Framework)

Les listes et exemples suivants décrivent les protocoles employés pour l'utilisation de la méthode PUT par ADO.NET Data Services. Les autres comportements requis par Hypertext Transfer Protocol, RFC 2616 sont décrits dans Spécifications HTTP courantes (ADO.NET Data Services Framework) et PUT, POST et DELETE (ADO.NET Data Services Framework).

Les protocoles suivants s'appliquent aux demandes HTPP qui utilisent la méthode PUT.

• Toutes les demandes PUT réussies retournent un code de réponse 204 (Aucun contenu).

• Une demande PUT sur une ressource ADO.NET Data Services fusionne le contenu de la demande avec l'état actuel de la ressource. La fusion est effectuée en comparant chaque composant du corps de la demande à la ressource telle qu'elle existe sur le serveur.

  • Si l'un des composants du corps de la demande n'est pas dans la ressource, la demande représente une violation de schéma et un code de réponse 422 (Impossible de traiter l'entité) est retourné.

  • Lorsqu'un composant du corps de la demande correspond à un composant de la ressource, le processus de correspondance se poursuit avec les enfants de l'élément dans le corps de la demande.

• Une demande PUT ayant pour but d'affecter la valeur NULL à une ressource lorsque le type de la ressource ne peut pas avoir la valeur NULL provoque un code de retour 422 (Impossible de traiter l'entité).

• Une demande PUT ayant pour but d'affecter une valeur vide à une ressource lorsque le type de la ressource ne définit pas d'état vide provoque un code de retour 422 (Impossible de traiter l'entité).

• Étant donné que PUT doit être idempotent, vous ne pouvez pas l'utiliser pour insérer des ressources dans un jeu de ressources. Autrement dit, PUT ne peut pas implémenter de sémantique de création ou d'ajout semblable à POST.

• Toute annotation de contenu différé dans la charge utile de demande est ignorée.

• Si l'URI de demande dans l'en-tête HTPP ne correspond pas à l'URI associé dans la charge utile de demande, l'URI de demande est prioritaire. La charge utile est traitée comme si elle incluait la valeur de l'URI de demande.

• Si le corps de la demande PUT contient les clés des ressources concernées par l'opération dans le cadre de la sérialisation d'une ressource, ces valeurs de clés sont ignorées. Les valeurs de clés de ressources ne peuvent pas être mises à jour.

Types qui prennent en charge la méthode PUT

Les exemples fournis plus loin dans ce chapitre résument les types de ressources qui prennent en charge la méthode PUT. Une demande PUT concernant un type de ressource qui prend en charge la méthode PUT peut échouer si l'entité demandeuse dispose de droits d'accès à la ressource spécifiée insuffisants. Dans ce cas, comme décrit dans Hypertext Transfer Protocol, RFC 2616, la demande retourne un code de réponse 401 (Accès non autorisé) ou 403 (Accès refusé), selon que la spécification d'une autre entité au service de données est susceptible d'entraîner la réussite de la demande.

Les exemples suivants illustrent les éléments finaux de la syntaxe de chemin d'accès d'URL HTTP qui prennent en charge ou non la méthode PUT. Chaque cas inclut une description d'une demande PUT et les résultats prévisibles.

/<jeu_entités>

Exemple d'élément final d'URI

L'exemple d'URI suivant illustre un jeu d'entités en tant qu'élément final.

/Customers

Description:

La méthode PUT n'est pas prise en charge pour un jeu d'entités en tant qu'élément final. Un code de réponse 405 (Méthode non prise en charge) est retourné.

/<jeu_entités>(keyPredicate)

L'exemple d'URI suivant illustre un keyPredicate en tant qu'élément final.

/Customers('ALFKI') 

Description :

• Prend en charge la méthode PUT.

• Met à jour l'instance de type de ressource unique fournie par le corps de la demande et identifiée par le keyPredicate.

  • Les mises à jour profondes des types associés ne sont pas prises en charge.

  • Prend en charge la liaison du côté d'une relation qui a une cardinalité égale à un.

• Autorise la liaison de la ressource R1 identifiée par le keyPredicate à des ressources existantes :

  • Si R1 contient uniquement l'URI d'une ressource existante R2 comme valeur d'une propriété de navigation ou de lien qui identifie le côté d'une relation qui a une cardinalité égale à un, R1 est liée à R2.

  • Si R1 contient l'URI et le corps de la ressource, on suppose que l'URI représente une ressource existante R2 déjà liée à R1. R2 est alors mise à jour avec les valeurs spécifiées dans le corps.

  • Si R1 contient uniquement le corps et non l'URI d'une ressource connexe R2 comme valeur d'une propriété de navigation ou de lien, un code 400 (Demande incorrecte) est retourné.

• L'envoi d'une charge utile égale à la valeur de littéral de NULL à cette ressource entraîne l'envoi d'un code de réponse 400 (Demande incorrecte).

• La valeur des propriétés qui composent la clé de la ressource ne peut pas être mise à jour. Si de nouvelles valeurs sont présentes dans la charge utile d'une demande PUT, elles sont ignorées.

L'exemple d'URI suivant illustre un prédicat de clé numérique en tant qu'élément final. Le code met à jour le produit n°123 et la catégorie avec laquelle il est associé ; il relie la catégorie associée.

/Products(123)

Format JSON

{
__metadata:{ uri="/Products(123)", 
type="NorthwindModel.Product" },
Name:"New product name"
Category :   { __metadata: {uri:"/Category(2)" } }
}

/<propriété_navigation> ou /<propriété_lien>

Les exemples d'URI suivants illustrent des propriétés de navigation et de lien en tant qu'éléments finaux.

/Customers('ALFKI')/Orders

/Customers('ALKFI')/Orders(1)

/Products(1)/Category (Fonctionne uniquement sur des extrémités de relation avec cardinalité = 1)

Description :

• Prend en charge la méthode PUT.

• Si la propriété de navigation ou de lien identifie une ressource unique ou si l'extrémité d'une relation a une cardinalité égale à un :

  • Utilise la même sémantique que /<ResourceSet>(keyPredicate), hormis le fait qu'un corps de demande qui contient uniquement la valeur NULL sépare la ressource de celle identifiée par l'avant-dernier segment d'URI.

• Si la propriété de navigation ou de lien identifie plusieurs ressources ou l'extrémité « plusieurs » d'une relation :

  • Non pris en charge. Un code de réponse 405 (Méthode non prise en charge) est retourné.

/<type_complexe>

L'exemple d'URI suivant illustre un type complexe en tant qu'élément final.

/Customers('ALFKI')/Address

Description :

• Prend en charge la méthode PUT.

• Met à jour le type complexe identifié par la feuille de l'URI de demande avec le contenu du corps de la demande.

• Prend en charge les mises à jour profondes.

• La charge utile de demande peut contenir du contenu pouvant être mis à jour de types complexes imbriqués. Aucune profondeur maximale n'est définie pour de telles mises à jour, tant que la profondeur demeure dans les limites de l'instance de type de ressource contenante.

/<propriété>

L'exemple d'URI suivant illustre une propriété en tant qu'élément final :

/Customers('ALFKI')/FirstName

Description :

• Prend en charge la méthode PUT.

• Prend en charge la mise à jour de la valeur de la propriété.

• La propriété peut avoir la valeur NULL.

  • JSON utilise la primitive NULL.

/<propriété>/$value

L'exemple d'URI suivant illustre une valeur de propriété en tant qu'élément final :

/Customers('ALFKI')/FirstName/$value

Description :

• Prend en charge la méthode PUT.

• Prend en charge la mise à jour de la valeur brute de la propriété.

• N'offre pas de possibilité de définir la valeur à NULL.

• Le type MIME du corps de la demande doit correspondre à celui du type de ressource sur le serveur.

• Un corps de demande de zéro octet définit la valeur de la propriété à « vide » si le type de la propriété définit un état vide ; autrement, un code de réponse 422 (Impossible de traiter l'entité) est retourné.

/<nom_opération_service>

L'exemple d'URI suivant illustre un nom d'opération de service en tant qu'élément final :

/CustomersByCity?city='London'

Description :

• Ne prend pas en charge la méthode PUT.

• Le verbe PUT n'est pas défini pour les opérations ADO.NET Data Services.

• Retourne un code de réponse 405 (Méthode non prise en charge).

Limitation d'aller-retour applicables aux demandes PUT

ADO.NET Data Services Framework prend en charge un scénario d'aller-retour qui utilise une demande GET sur un URI particulier pour retourner une charge utile. Un scénario courant consiste à modifier certaines des données et à passer la même charge utile dans une demande PUT sur cet URI. Cela ne fonctionne pas lorsqu'une propriété dans un entité n'est pas une clé mais une colonne d'identité. La seule solution de contournement consiste à modifier la colonne d'identité dans le fichier SSDL (Store Schema Definition Language) en une propriété calculée.

Voir aussi

Concepts

HttpWebRequest GET (ADO.NET Data Services Framework)
HttpWebRequest PUT (ADO.NET Data Services Framework)
HttpWebRequest POST (ADO.NET Data Services Framework)
HttpWebRequest DELETE (ADO.NET Data Services Framework)
PUT, POST et DELETE (ADO.NET Data Services Framework)