Entiteit invoegen of vervangen

  • Artikel

De Insert Or Replace Entity bewerking vervangt een bestaande entiteit of voegt een nieuwe entiteit in als deze niet in de tabel bestaat. Omdat met deze bewerking een entiteit kan worden ingevoegd of bijgewerkt, wordt deze ook wel een upsert-bewerking genoemd.

Aanvraag

U kunt de Insert Or Replace Entity aanvraag als volgt samenstellen. HTTPS wordt aanbevolen. Vervang de volgende waarden door uw eigen waarden:

  • myaccount met de naam van uw opslagaccount

  • mytable door de naam van de tabel

  • myPartitionKey en myRowKey met de naam van de partitiesleutel en rijsleutel voor de entiteit die moet worden bijgewerkt

Methode Aanvraag-URI HTTP-versie
PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

Geëmuleerde opslagservice

Wanneer u een aanvraag indient bij de geëmuleerde opslagservice, geeft u de hostnaam van de emulator en de Azure Table Storage-poort op als 127.0.0.1:10002, gevolgd door de naam van het geëmuleerde opslagaccount.

Methode Aanvraag-URI HTTP-versie
PUT http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

Table Storage in de Storage-emulator verschilt op verschillende manieren van Azure Table Storage. Zie Verschillen tussen de Opslagemulator en Azure Storage-services voor meer informatie.

URI-parameters

U kunt de volgende extra parameter opgeven voor de aanvraag-URI.

Parameter Beschrijving
timeout Optioneel. De timeout parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Table Storage-bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader Beschrijving
Authorization Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
Date of x-ms-date Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
x-ms-version Vereist. Moet worden ingesteld op 2011-08-18 of hoger. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
Content-Type Vereist. Hiermee geeft u het inhoudstype van de payload op. Mogelijke waarden zijn application/atom+xml en application/json.

Zie Payload-indeling voor Table Storage-bewerkingen voor meer informatie over geldige inhoudstypen.
Content-Length Vereist. De lengte van de aanvraagtekst.
x-ms-client-request-id Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Table Storage bewaken voor meer informatie.

Aanvraagbody

De Insert Or Replace Entity bewerking verzendt de entiteit die moet worden ingevoegd als een OData entiteitenset. Deze entiteitsset kan een JSON- of een Atom-feed zijn. Zie Entiteiten invoegen en bijwerken voor meer informatie.

Notitie

JSON is de aanbevolen nettoladingindeling en is de enige indeling die wordt ondersteund voor versie 2015-12-11 en hoger.

Antwoord

Het antwoord bevat een HTTP-statuscode en een set antwoordheaders.

Statuscode

Een geslaagde bewerking retourneert statuscode 204 (Geen inhoud). Zie Status- en foutcodes enTable Storage-foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord bevat de volgende headers. Het antwoord kan ook extra, standaard HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader Description
ETag De ETag voor de entiteit.
x-ms-request-id Uniek identificeert de aanvraag die is gedaan en kan worden gebruikt voor het oplossen van problemen met de aanvraag. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
x-ms-version Geeft de versie van Table Storage aan die wordt gebruikt om de aanvraag uit te voeren. Deze header wordt geretourneerd voor aanvragen die zijn gedaan op basis van versie 2009-09-19 en hoger.
Date Een UTC-datum/tijd-waarde die de tijd aangeeft waarop het antwoord is gestart. De service genereert deze waarde.
x-ms-client-request-id Kan worden gebruikt om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de x-ms-client-request-id header, als deze aanwezig is in de aanvraag. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de x-ms-client-request-id header niet aanwezig is in de aanvraag, is deze niet aanwezig in het antwoord.

Hoofdtekst van de reactie

Geen.

Autorisatie

De accounteigenaar kan deze bewerking uitvoeren. Bovendien kan iedereen met een shared access signature die gemachtigd is om deze bewerking uit te voeren, dit doen.

Voorbeeld van aanvraag en antwoord

In de volgende voorbeelden ziet u voorbeeldaanvragen die gebruikmaken van JSON- en Atom-feeds.

Notitie

JSON is de aanbevolen nettoladingindeling en is de enige indeling die wordt ondersteund voor versie 2015-12-11 en hoger.

JSON (versie 2013-08-15 en hoger)

Hier volgt een voorbeeld van een aanvraag en antwoord dat gebruikmaakt van JSON.

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

De aanvraag wordt verzonden met de volgende headers:

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

De aanvraag wordt verzonden met de volgende JSON-hoofdtekst:

{  
   "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"  
}

Nadat de aanvraag is verzonden, wordt het volgende antwoord geretourneerd:

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

Atom-feed (versies vóór 2015-12-11)

Hier volgt een voorbeeld van een aanvraag en antwoord dat gebruikmaakt van Atom.

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

De aanvraag wordt verzonden met de volgende headers:

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

De aanvraag wordt verzonden met de volgende XML-hoofdtekst:

<?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>

Nadat de aanvraag is verzonden, wordt het volgende antwoord geretourneerd:

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

Opmerkingen

De Insert Or Replace Entity bewerking maakt geen gebruik van de If-Match header. U moet deze bewerking aanroepen met de versie 2011-08-18 of hoger. Deze kenmerken onderscheiden deze bewerking van de bewerking Entiteit bijwerken .

Als u de Insert Or Replace Entity bewerking gebruikt om een entiteit te vervangen, worden alle eigenschappen van de vorige entiteit verwijderd als de nieuwe entiteit deze niet definieert. Eigenschappen met een null waarde worden ook verwijderd.

Wanneer u de Insert or Replace Entity bewerking aanroept, moet u waarden opgeven voor de PartitionKey systeemeigenschappen en RowKey . Deze eigenschappen vormen samen de primaire sleutel en moeten uniek zijn binnen de tabel.

PartitionKey De waarden en RowKey moeten zowel tekenreekswaarden zijn. PartitionKey en RowKey waarden kunnen maximaal 1024 tekens groot zijn. Als u een geheel getal gebruikt voor de sleutelwaarde, moet u het gehele getal converteren naar een tekenreeks met vaste breedte. Dit komt omdat ze canoniek zijn gesorteerd. Converteer bijvoorbeeld de waarde 1 naar 0000001om de juiste sortering te garanderen.

Als u expliciet een eigenschap wilt typen, geeft u het juiste OData gegevenstype op door het kenmerk in te m:type stellen binnen de eigenschapsdefinitie in de Atom-feed. Zie Entiteiten invoegen en bijwerken voor meer informatie over het typen van eigenschappen.

Elke toepassing die een HTTP PUT aanvraag kan autoriseren en verzenden, kan een entiteit invoegen of vervangen.

Zie Entiteitsgroeptransacties uitvoeren voor meer informatie over het uitvoeren van batch-upsert-bewerkingen.

Zie ook

Aanvragen voor Azure Storage autoriseren
De headers van de OData-gegevensserviceversie instellen
Entiteiten invoegen en bijwerken
Status en foutcodes
Table Storage-foutcodes