Insertion ou remplacement d'entité

L'opération Insert Or Replace Entity remplace une entité existante ou insère une nouvelle entité si elle n'existe pas dans la table. Dans la mesure où cette opération peut insérer ou mettre à jour une entité, elle est également connue sous le nom d'opération upsert.

Requête

La demande Insert Or Replace Entity peut être construite comme indiqué ci-dessous. HTTPS est recommandé. Remplacez les valeurs suivantes par les vôtres :

  • myaccount par le nom de votre compte de stockage

  • mytable par le nom de votre table

  • myPartitionKey et myRowKey par le nom de la clé de partition et de la clé de ligne pour l'entité à mettre à jour

Méthode URI de demande Version HTTP
PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

Service de stockage émulé

Lorsque vous élaborez une demande pour le service de stockage émulé, spécifiez le nom d'hôte de l'émulateur et le port de service Table sous la forme 127.0.0.1:10002, suivi du nom de compte de stockage émulé.

Méthode URI de demande Version HTTP
PUT http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

Le service Table dans l'émulateur de stockage et le service Table de Windows® Azure™ diffèrent sur plusieurs points. pour plus d’informations, consultez différences entre les Services Stockage Emulator et stockage Azure.

Paramètres URI

Les paramètres supplémentaires suivants peuvent être spécifiés dans l'URI de la demande.

Paramètre Description
timeout facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez définition de délais d’attente pour les opérations de service de table.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires ou facultatifs.

En-tête de requête Description
Authorization Obligatoire. Spécifie le schéma d’autorisation, le nom de compte et la signature. pour plus d’informations, consultez autoriser les demandes à stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. pour plus d’informations, consultez autoriser les demandes à stockage Azure.
x-ms-version Obligatoire, version du 18/08/2011 ou ultérieure. Spécifie la version de l'opération à utiliser pour cette demande. pour plus d’informations, consultez contrôle de version pour les Services stockage Azure.
Content-Type Obligatoire. Spécifie le type de contenu de la charge utile. Les valeurs possibles sont application/atom+xml et application/json.

Pour plus d’informations sur les types de contenu valides, consultez format de charge utile pour les opérations de service de table.
Content-Length Obligatoire. Longueur du corps de la demande.
x-ms-client-request-id Facultatif. Fournit une valeur opaque générée par le client avec une limite de 1 Kio de caractères qui est enregistrée dans les journaux d’analyse lorsque la journalisation de l’analyse de stockage est activée. L’utilisation de cet en-tête est fortement recommandée pour la mise en corrélation des activités côté client avec les requêtes reçues par le serveur. pour plus d’informations, consultez à propos de la journalisation des Storage Analytics et de la journalisation Azure : utilisation des journaux pour suivre les demandes de Stockage.

Corps de la demande

L'opération Insert Or Replace Entity envoie l'entité à insérer en tant que jeu d'entités OData, qui est un flux JSON ou Atom. Pour plus d’informations, consultez insertion et mise à jour des entités.

Notes

JSON est le format de charge utile recommandé, et est le seul format pris en charge pour les versions 2015-12-11 et ultérieures.

Réponse

La réponse inclut un code d'état HTTP et un ensemble d'en-têtes de réponse.

Code d’état

Une opération réussie renvoie le code d'état 204 (Aucun contenu).

Pour plus d’informations sur les codes d’État, consultez codes d’État et d’erreur et codes d’erreur du service de table.

En-têtes de réponse

Cette réponse comprend les en-têtes suivants. La réponse peut aussi inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

En-tête de réponse Description
ETag ETag pour l'entité.
x-ms-request-id Cet en-tête identifie de façon unique la demande qui a été effectuée et peut être utilisé pour résoudre les problèmes de la demande. Pour plus d’informations, consultez Troubleshooting API Operations.
x-ms-version Indique la version du service de Table utilisée pour exécuter la demande. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version ultérieure.
Date Une valeur de date/heure UTC générée par le service qui indique le moment auquel la réponse a été initiée.
x-ms-client-request-id Cet en-tête peut être utilisé pour dépanner les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l' x-ms-client-request-id en-tête si elle est présente dans la demande et que la valeur est supérieure à 1024 caractères ASCII visibles. Si l' x-ms-client-request-id en-tête n’est pas présent dans la demande, cet en-tête ne sera pas présent dans la réponse.

Corps de la réponse

Aucun.

Autorisation

Cette opération peut être exécutée par le propriétaire du compte et par toute personne qui dispose d'une signature d'accès partagé qui a l'autorisation d'exécuter cette opération.

Exemple de demande et de réponse

Les exemples ci-dessous montrent des exemples de demandes utilisant à la fois des flux JSON et Atom.

Notes

JSON est le format de charge utile recommandé, et est le seul format pris en charge pour les versions 2015-12-11 et ultérieures.

JSON (versions 2013-08-15 et ultérieures)

Voici un exemple de demande et de réponse utilisant JSON.

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')  

La demande est envoyée avec les en-têtes suivants :

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  

La demande est envoyée avec le corps JSON suivant :

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}  

Une fois la demande envoyée, la réponse suivante est renvoyée :

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0  

Flux Atom (versions antérieures à 2015-12-11)

Voici un exemple de demande et de réponse utilisant Atom.

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')  

La demande est envoyée avec les en-têtes suivants :

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  

La demande est envoyée avec le corps XML suivant :

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>  

Une fois la demande envoyée, la réponse suivante est renvoyée :

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0  

Remarques

L'opération Insert Or Replace Entity n'utilise pas l'en-tête If-Match et elle doit être appelée en utilisant la version du 18/08/2011 ou une version ultérieure. Ces attributs distinguent cette opération de l’opération mettre à jour l’entité .

Si l'opération Insert Or Replace Entity est utilisée pour remplacer une entité, les propriétés de l'entité précédente seront supprimées si la nouvelle entité ne les définit pas. Les propriétés avec une valeur null sont également supprimées.

Lors de l'appel de l'opération Insert or Replace Entity, vous devez spécifier des valeurs pour les propriétés système PartitionKey et RowKey. Ces propriétés forment la clé primaire et doivent être uniques au sein de la table.

Les PartitionKey valeurs et RowKey doivent être des valeurs de chaîne ; chaque valeur de clé peut avoir une taille maximale de 64 Kio. Si vous utilisez une valeur entière pour la valeur de clé, vous devez convertir l'entier en une chaîne de largeur fixe, car elles sont triées de façon canonique. Par exemple, vous devez convertir la valeur 1 en 0000001 pour garantir un tri correct.

Pour typer explicitement une propriété, spécifiez le type de données OData approprié en définissant l'attribut m:type au sein de la définition de la propriété dans le flux Atom. Pour plus d’informations sur la saisie des propriétés, consultez insertion et mise à jour des entités.

Toute application pouvant autoriser et envoyer une requête HTTP PUT peut insérer ou remplacer une entité.

Pour plus d’informations sur l’exécution d’opérations batch Upsert, consultez exécution de transactions de groupe d’entités.

Voir aussi

autoriser les demandes à stockage Azure
Définition des en-têtes de version du service de données OData
Insertion et mise à jour d’entités
Codes d’État et d’erreur
Codes d’erreur de service de Table