Entitás beszúrása vagy cseréje

Cikk
08/05/2023

A Insert Or Replace Entity művelet lecserél egy meglévő entitást, vagy új entitást szúr be, ha az nem szerepel a táblában. Mivel ez a művelet beszúrhat vagy frissíthet egy entitást, upsert műveletnek is nevezik.

Kérés

A kérést a Insert Or Replace Entity következőképpen hozhatja létre. A HTTPS használata ajánlott. Cserélje le a következő értékeket a saját értékére:

myaccount a tárfiók nevével
mytable a tábla nevével
myPartitionKey és myRowKey a frissíteni kívánt entitás partíciókulcsának és sorkulcsának nevével

Metódus	Kérés URI-ja	HTTP-verzió
`PUT`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Emulált tárolási szolgáltatás

Amikor kérést küld az emulált tárolási szolgáltatásra, adja meg az emulátor gazdagépnevét és az Azure Table Storage-portot 127.0.0.1:10002 formátumban, majd az emulált tárfiók nevét.

Metódus	Kérés URI-ja	HTTP-verzió
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

A Storage emulátorban található Table Storage többféleképpen különbözik az Azure Table Storage-tól. További információ: A Storage emulátor és az Azure Storage-szolgáltatások közötti különbségek.

URI-paraméterek

A kérelem URI-ja a következő további paramétert adhatja meg.

Paraméter	Leírás
`timeout`	Választható. A `timeout` paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása a Table Storage-műveletekhez.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérések engedélyezése az Azure Storage-ba.
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérések engedélyezése az Azure Storage-ba.
`x-ms-version`	Kötelező. 2011.08.18-ra vagy újabbra kell állítani. A kérelemhez használni kívánt művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`Content-Type`	Kötelező. Megadja a hasznos adat tartalomtípusát. A lehetséges értékek a és `application/json`a.`application/atom+xml` Az érvényes tartalomtípusokról további információt a Table Storage-műveletek hasznos adatformátuma című témakörben talál.
`Content-Length`	Kötelező. A kérelem törzsének hossza.
`x-ms-client-request-id`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kib-os (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel. További információ: Az Azure Table Storage monitorozása.

A kérés törzse

A Insert Or Replace Entity művelet elküldi a beszúrni kívánt entitást egy entitáskészletként OData . Ez az entitáskészlet lehet JSON vagy Atom-hírcsatorna. További információ: Entitások beszúrása és frissítése.

Megjegyzés

A JSON az ajánlott hasznos adatformátum, és ez az egyetlen támogatott formátum a 2015-12-11-es és újabb verziókban.

Reagálás

A válasz tartalmaz egy HTTP-állapotkódot és egy válaszfejléceket.

Állapotkód

A sikeres művelet a 204-ben (tartalom nélkül) visszaadott állapotkódot adja vissza. Az állapotkódokról további információt az Állapot- és hibakódok, valamint a Table Storage hibakódjai című témakörben talál.

Válaszfejlécek

A válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Válaszfejléc	Description
`ETag`	Az `ETag` entitáshoz tartozó.
`x-ms-request-id`	Egyedileg azonosítja a végrehajtott kérést, és a kérés hibaelhárításához használható. További információ: API-műveletek hibaelhárítása.
`x-ms-version`	A Table Storage kérés futtatásához használt verzióját jelzi. A rendszer ezt a fejlécet adja vissza a 2009-09-19-es és újabb verzióval kapcsolatos kérésekhez.
`Date`	Utc dátum/idő érték, amely a válasz indításának időpontját jelzi. A szolgáltatás létrehozza ezt az értéket.
`x-ms-client-request-id`	A kérések és a kapcsolódó válaszok hibaelhárítására használható. A fejléc értéke megegyezik a fejléc értékével `x-ms-client-request-id` , ha az szerepel a kérelemben. Az érték legfeljebb 1024 látható ASCII-karakter lehet. Ha a `x-ms-client-request-id` fejléc nem szerepel a kérelemben, az nem jelenik meg a válaszban.

Választörzs

Nincsenek.

Engedélyezés

A fióktulajdonos végrehajthatja ezt a műveletet. Emellett bárki, aki rendelkezik a művelet végrehajtásához engedéllyel rendelkező közös hozzáférésű jogosultsággal, megteheti.

Mintakérés és válasz

Az alábbi példák JSON- és Atom-hírcsatornákat használó mintakéréseket mutatnak be.

Megjegyzés

A JSON az ajánlott hasznos adatformátum, és ez az egyetlen támogatott formátum a 2015-12-11-es és újabb verziókban.

JSON (2013-08-15-es és újabb verzió)

Az alábbiakban egy JSON-t használó mintakérést és választ láthat.

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

A kérést a rendszer a következő fejlécekkel küldi el:

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

A kérést a következő JSON-törzs küldi el:

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

A kérés elküldése után a rendszer a következő választ adja vissza:

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

Atomcsatorna (2015-12-11 előtti verziók)

Az alábbiakban egy Atomot használó mintakérés és válasz látható.

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

A kérés a következő fejlécekkel lesz elküldve:

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

A kérés a következő XML-törzstel lesz elküldve:

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

A kérés elküldése után a rendszer a következő választ adja vissza:

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

Megjegyzések

A Insert Or Replace Entity művelet nem használja a fejlécet If-Match . Ezt a műveletet a 2011-08-18-es vagy újabb verzióval kell meghívnia. Ezek az attribútumok megkülönböztetik ezt a műveletet az Entitás frissítése művelettől.

Ha a Insert Or Replace Entity műveletet egy entitás cseréjére használja, az előző entitás minden tulajdonsága törlődik, ha az új entitás nem definiálja őket. Az értékekkel rendelkező null tulajdonságok is törlődnek.

A művelet meghívásakor Insert or Replace Entity meg kell adnia a és RowKey a PartitionKey rendszertulajdonságok értékeit. Ezek a tulajdonságok együttesen alkotják az elsődleges kulcsot, és egyedinek kell lenniük a táblában.

A és RowKey az PartitionKey értéknek sztringértéknek kell lennie. Minden kulcsérték legfeljebb 64 KiB méretű lehet. Ha egész számot használ a kulcsértékhez, az egész számot egy rögzített szélességű sztringgé kell alakítania. Ennek az az oka, hogy azok canonically rendezve. A megfelelő rendezés biztosításához például konvertálja az értéket 10000001értékké.

A tulajdonság explicit beírásához adja meg a megfelelő OData adattípust az m:type Atom-hírcsatorna tulajdonságdefiníciójában található attribútum beállításával. További információ a tulajdonságok beírásáról: Entitások beszúrása és frissítése.

Bármely alkalmazás, amely engedélyezheti és elküldheti a kérést HTTP PUT , beszúrhat vagy lecserélhet egy entitást.

További információ a kötegelt upsert műveletek végrehajtásáról: Entitáscsoport-tranzakciók végrehajtása.

Lásd még

Kérések engedélyezése az Azure Storage-nak
Az OData-adatszolgáltatás verziófejléceinek beállítása
Entitások beszúrása és frissítése
Állapot- és hibakódok
Table Storage-hibakódok