Entiteit invoegen of samenvoegen

Artikel
05/04/2024

De Insert Or Merge Entity bewerking werkt een bestaande entiteit bij of voegt een nieuwe entiteit in als deze niet in de tabel bestaat. Omdat deze bewerking een entiteit kan invoegen of bijwerken, wordt deze ook wel een upsert-bewerking genoemd.

Aanvraag

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

myaccount door de naam van uw opslagaccount
mytable door de naam van uw tabel
myPartitionKey en myRowKey met de naam van de partitiesleutel en rijsleutel voor de entiteit die moet worden bijgewerkt

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

Geëmuleerde opslagservice

Wanneer u een aanvraag indient voor 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
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

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

URI-parameters

U kunt de volgende aanvullende 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 op. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`Date` of `x-ms-date`	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`x-ms-version`	Vereist. Moet zijn 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 Merge Entity bewerking verzendt de entiteit die moet worden ingevoegd als een OData entiteitenset. Deze entiteitsset kan een Atom- of JSON-nettolading 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 (No Content). Zie Status- en foutcodes en Table 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`	Identificeert op unieke wijze 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 in 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.

MERGE 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 ouder dan 2015-12-11)

Hier volgt een voorbeeld van een aanvraag en antwoord waarin Atom wordt gebruikt:

MERGE 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='myrowkey')</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 Merge Entity bewerking maakt gebruik van het MERGE werkwoord. U moet de bewerking aanroepen met de versie 2011-08-18 of hoger. Bovendien wordt voor deze bewerking geen gebruikgemaakt van de If-Match header. Deze kenmerken onderscheiden deze bewerking van de Update Entity bewerking, hoewel de aanvraagbody voor beide bewerkingen hetzelfde is.

Als u de Insert Or Merge Entity bewerking gebruikt om een entiteit samen te voegen, blijven alle eigenschappen van de vorige entiteit behouden als de aanvraag deze niet definieert of opneemt. Eigenschappen met een null waarde blijven ook behouden.

Wanneer u de Insert or Merge 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.

Zowel de PartitionKey waarden als RowKey moeten 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 0000001 om de juiste sortering te garanderen.

Als u expliciet een eigenschap wilt typen, geeft u het juiste OData type 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 MERGE aanvraag kan autoriseren en verzenden, kan een entiteit invoegen of bijwerken.

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

Zie ook

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

Delen via