Megosztás:

Táblasorok frissítése és törlése a Webes API használatával

Az adatok módosítására vonatkozó műveletek a webes API alapvető részei. Az egyszerű frissítési és törlési műveletek mellett műveleteket hajthat végre egyetlen táblaoszlopon (entitásattribútumokon) és olyan upsert kéréseket írhat, amelyek frissítik vagy beszúrják az adatokat attól függően, hogy léteznek-e.

Alapvető frissítés

A frissítési műveletek a HTTP-parancsot PATCH használják. Adjon át egy JSON-objektumot, amely tartalmazza a frissíteni kívánt tulajdonságokat a rekordot képviselő URI-nak. Sikeres frissítés esetén egy 204 No Content állapotú válasz kerül visszaküldésre.

A If-Match: * fejléc gondoskodik arról, hogy ne hozzon létre új rekordot, ha véletlenül végrehajt egy upsert műveletet. További információ: A létrehozás megakadályozása az upsertben.

Fontos

Egy entitás frissítésekor csak a kérelem törzsében módosítani kívánt tulajdonságokat vegye fel. Egyszerűen frissítse a korábban lekért entitás tulajdonságait, és az aktualizált JSON-t vegye bele a kérelembe; minden egyes tulajdonság frissülni fog, még akkor is, ha az érték változatlan. Ez olyan rendszereseményeket okozhat, amelyek olyan üzleti logikát indíthatnak el, amely arra számít, hogy az értékek megváltoztak. Ez azt eredményezheti, hogy a tulajdonságok úgy tűnhetnek, hogy frissültek a naplózási adatokban, amikor valójában nem változtak.

Amikor frissíti a statecode tulajdonságot, fontos, hogy mindig megadja a kívánt statuscode értéket. statecode és statuscode függő értékekkel rendelkezik. Egy adott statuscode értékhez több érvényes statecode érték is lehet, de minden statecode oszlophoz egyetlen DefaultStatus-érték van konfigurálva. Ha úgy frissíti a statecode, hogy nem ad meg statuscode, akkor a rendszer automatikusan beállítja az alapértelmezett állapotértéket. Ezen kívül, ha a naplózás engedélyezve van a táblában és az statuscode oszlopban, az statuscode oszlop módosított értéke nem lesz rögzítve a naplózási adatokban, hacsak külön nincs megadva a művelet során.

Megjegyzés:

Az attribútumok definíciója tartalmaz egy tulajdonságot RequiredLevel . Ha ez a beállítás be van állítva SystemRequired, ezeket az attribútumokat nem állíthatja null értékre. További információ: Attribútumkövetelmény szintje

Ez a példa egy meglévő fiókrekordot accountid frissít 000000000-0000-0000-0000-00000000001 értékkel.

Kérés:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

Válasz:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Megjegyzés:

Az entitások frissítéskor való társításáról és leválasztásáról az egyértékű navigációs tulajdonságok használata című témakörben olvashat.

Frissítés visszaadott adatokkal

Ha adatokat szeretne lekérni egy frissítendő entitásból, megadhatja a kérést PATCH , hogy a létrehozott rekordból származó adatok 200 -os állapotú (OK) állapotban lesznek visszaadva. Az eredmény eléréséhez a kérelem fejlécét Prefer: return=representation kell használnia.

A visszaadott tulajdonságok szabályozásához fűzze hozzá a $select lekérdezési beállítást az URL-címhez az entitáskészlethez. A $expand lekérdezési beállítás használata esetén a rendszer figyelmen kívül hagyja a lekérdezési beállítást.

Ez a példa frissíti a fiókentitást, és a válaszban visszaadja a kért adatokat.

Kérés:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Válasz:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Több rekord frissítése egyetlen kérelemben

Egyetlen kérelemben több azonos típusú rekord frissítésének leggyorsabb módja az UpdateMultiple művelet használata. Az írás időpontjában az UpdateMultiple művelet. Ezt a műveletet nem minden szabványos tábla támogatja, de minden rugalmas tábla igen.

További információ:

Egyetlen tulajdonságérték frissítése

Ha csak egyetlen tulajdonságértéket szeretne frissíteni, használjon egy kérést PUT az entitás URI-jának hozzáfűzett tulajdonságnévvel.

Az alábbi példa egy meglévő name sor account tulajdonságát frissíti accountid 00000000-0000-0000-0000-0000000001 értékkel.

Kérés:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Válasz:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Egyetlen tulajdonságérték törlése

Egyetlen tulajdonság értékének törléséhez használjon egy DELETE kérelmet az entitás URI-jának hozzáfűzött tulajdonságnévvel.

Az alábbi példa törli a fiók entitás description tulajdonságának értékét, amelynek azonosítója accountid 00000000-0000-0000-0000-000000000001.

Kérés:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Válasz:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Megjegyzés:

Ez nem használható egyetlen értékű navigációs tulajdonsággal két entitás kapcsolatának megszüntetésére. Alternatív megközelítésért lásd: Társítás megszüntetése egy egyértékű navigációs tulajdonsággal.

Táblázatsor beszúrása vagy frissítése

Az upsert művelet hasonló a frissítéshez. Egy kérést PATCH használ, és egy URI segítségével hivatkozik egy adott rekordra. A különbség az, hogy ha a rekord nem létezik, akkor létrejön. Ha már létezik, frissítve lesz.

Az Upsert hasznos az adatok külső rendszerek közötti szinkronizálása során. Előfordulhat, hogy a külső rendszer nem tartalmaz hivatkozást a Dataverse-tábla elsődleges kulcsára, így a dataverse tábla alternatív kulcsait a külső rendszer értékei alapján konfigurálhatja, amelyek egyedileg azonosítják a rekordot mindkét rendszeren. További információ: Alternatív kulcsok definiálása a sorok hivatkozásához

A $metadata szolgáltatásdokumentum entitástípusának megjegyzéseiben minden olyan másodlagos kulcs látható, amely egy táblához van definiálva. További információ: Alternatív kulcsok.

A következő példában van egy tábla, amelynek neve sample_thing egy másodlagos kulccsal rendelkezik, amely két oszlopra hivatkozik: sample_key1 és sample_key2mindkettő az egész szám értékeinek tárolására van definiálva.

Kérés:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

A létrehozási vagy frissítési műveletek esetében is ugyanazt a választ kapja. Figyelje meg, hogy a OData-EntityId válaszfejléc hogyan használja a kulcsértékeket a rekord GUID elsődleges kulcsazonosítója helyett.

Válasz:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Mivel a válasz ugyanaz, nem tudhatja, hogy a művelet Create vagy Update műveletet képviselt-e.

Ha tudnia kell, használhatja a kérelem fejlécét Prefer: return=representation . Ezzel a fejléccel 201 Created választ kap egy rekord létrehozásakor, és 200 OK választ kap, amikor a rekord frissül. Ez a beállítás hozzáad egy Retrieve műveletet, amely hatással van a teljesítményre. Ha a kérelem fejlécét Prefer: return=representation használja, győződjön meg arról, hogy a $select minimális mennyiségű adatot tartalmazza, lehetőleg csak az elsődleges kulcs oszlopát. További információ: Frissítés visszaadott adatokkal és létrehozás visszaadott adatokkal.

Alternatív kulcsok használata esetén nem szabad az alternatív kulcsértékeket a kérés törzsében szerepeltetni.

  • Ha egy upsert egy Updateértéket jelöl, a rendszer figyelmen kívül hagyja ezeket az alternatív kulcsértékeket. A rekord azonosításához nem frissíthet másodlagos kulcsértékeket.
  • Ha egy upsert egy Create értéket jelöl, az URL-cím kulcsértékei akkor lesznek beállítva a rekordhoz, ha nem szerepelnek a törzsben. Ezért nem kell őket belefoglalni a kérelem törzsébe.

További információ: Rekord létrehozása vagy frissítése az Upsert használatával

Megjegyzés:

Új rekord létrehozásakor általában a rendszer guid értéket rendel az elsődleges kulcshoz. Ez az ajánlott eljárás, mivel a rendszer olyan kulcsokat hoz létre, amelyek az indexhez vannak optimalizálva, és ez javítja a teljesítményt. Ha azonban egy adott elsődleges kulcsértékkel rendelkező rekordot kell létrehoznia, például amikor a kulcs GUID-értékét egy külső rendszer hozza létre, a upsert művelet módot ad erre.

Új vagy meglévő rekord módosításának elkerülése upsert alkalmazásával

Néha vannak olyan helyzetek, amikor végre szeretne hajtani egy upsertműveletet, de meg szeretné akadályozni az egyik lehetséges műveletet: a létrehozást vagy a frissítést. Az If-Match vagy If-None-Match fejlécek használatával teheti meg ezt. További információ: Upsert-műveletek korlátozása.

Alapszintű törlés

A törlési művelet egyszerű. Használja az DELETE igét a törölni kívánt entitás URI-jával. Ez a példaüzenet töröl egy 000000000-0000-0000-0000-0000-00000000001 elsődleges accountid kulcsértékkel rendelkező fiókentitást.

Kérés:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Válasz:

Ha az entitás létezik, a 204-s állapotú normál választ kap, amely jelzi, hogy a törlés sikeres volt. Ha az entitás nem található, a 404-ben megadott állapotú választ kap.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Ismétlődő rekordok keresése

Az ismétlődő rekordok frissítési művelet során történő ellenőrzéséről további információt a Webes API-val végzett Frissítési művelet során ismétlődő rekordok észlelése című témakörben talál.

Több rekord törlése egyetlen kérelemben

Egy kérelemben az azonos típusú rekordok törlésének leggyorsabb módja a DeleteMultiple művelet használata. Az írás időpontjában a DeleteMultiple művelet egy előzetes verziójú funkció. A normál táblák nem támogatják ezt a műveletet, de minden rugalmas tábla igen.

Megjegyzés:

Normál táblák esetén a BulkDelete művelet használatát javasoljuk, amely lehetővé teszi a lekérdezésnek megfelelő rekordok aszinkron törlését. További információ: Adatok tömeges törlése

További információ:

Dokumentumok frissítése és törlése a tárolási partíciókban

Ha partíciókban tárolt rugalmas táblaadatokat frissít vagy töröl, mindenképpen adja meg a partíciókulcsot az adatok elérésekor.

További információ: PartitionId-érték kiválasztása

Lásd még

Webes API alapműveleti minta (C#)
Webes API alapműveleti minta (ügyféloldali JavaScript)
Műveletek végrehajtása a webes API segítségével
Http-kérések írása és hibák kezelése
Adatok lekérdezése webes API-val
Táblasor létrehozása a webes API-val
Táblázatsor lekérése a Webes API használatával
Táblasorok társítása és szétválasztása a Webes API használatával
Webes API-függvények használata
Web API-műveletek használata
Kötegelt műveletek végrehajtása a Webes API használatával
Másik felhasználó megszemélyesítése a Webes API használatával
Feltételes műveletek végrehajtása a Webes API használatával

  • Last updated on