Megosztás:

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

Az adatokat módosító műveletek a webes API alapvető részei. Az egyszerű frissítési és törlési műveletek mellett egyetlen táblaoszlopon (entitásattribútumokon) is végrehajthat műveleteket, és olyan upsert kéréseket írhat, amelyek frissíthetik vagy beszúrhatjá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. Ha a frissítés sikeres, a válasz a következő állapotot 204 No Contentadja vissza: .

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óért lásd: Létrehozás megakadályozása az upsert műveletben.

Fontos

Egy entitás frissítésekor csak a kérelem törzsében módosítani kívánt tulajdonságokat vegye fel. Ha egy entitást a korábban lekért entitás összes tulajdonságának beleszámításával frissít, a művelet akkor is frissíti az egyes tulajdonságokat, ha az érték megegyezik. Ez a frissítés olyan rendszereseményeket okozhat, amelyek olyan üzleti logikát váltanak ki, amely arra számít, hogy az értékek megváltoztak. Előfordulhat, hogy a tulajdonságok akkor frissülnek a naplózási adatokban, ha azok valójában nem változtak.

A tulajdonság statecode frissítésekor mindig állítsa be a kívánt statuscode értéket. Az statecode és statuscode értékek egymástól függenek. Egy adott statecode értékhez több érvényes statuscode érték is lehet. Azonban minden statecode oszlophoz egyetlen DefaultStatus-érték van konfigurálva. Amikor frissíti a statecode elemet anélkül, hogy megadná a statuscode-t, a rendszer beállítja az alapértelmezett állapotértéket. Továbbá, ha engedélyezi a naplózást a táblán és az statuscode oszlopon, a statuscode oszlop módosított értéke nem kerül rögzítésre a naplózási adatokban, kivéve, ha a frissítési művelet során megadja.

Megjegyzés:

Az attribútumok definíciója tartalmaz egy tulajdonságot RequiredLevel . Ha ez a tulajdonság be van állítva SystemRequired, ezeket az attribútumokat nem állíthatja null értékre. További információ: Attribútumkövetelmények 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éshez való társításáról és leválasztásáról további információt az egyértékű navigációs tulajdonságok használata című témakörben talál.

Frissítés visszaadott adatokkal

Ha adatokat szeretne lekérni egy frissített entitásból, úgy írja meg a PATCH kérést, hogy az adatokat a frissített rekordból 200-as (OK) állapottal adja vissza. Az eredmény eléréséhez használja a kérelem fejlécét Prefer: return=representation .

A visszaadott tulajdonságok szabályozásához fűzze hozzá a $select lekérdezési beállítást az entitáskészlet URL-címéhez. 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. 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

Egyetlen tulajdonságérték frissítéséhez használjon egy kérést PUT , és adja hozzá a tulajdonság nevét az entitás URI-jának.

Az alábbi példa egy meglévő name sor tulajdonságát frissíti account a accountid következő értékkel: 00000000-0000-0000-0000-000000000001: .

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 egy descriptionfiók entitás tulajdonságánakaccountid00000000-0000-0000-0000-000000000001 értékét, amely.

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:

Egyetlen értékű navigációs tulajdonsággal ez a megközelítés nem használható két entitás szétkapcsolásához. Alternatív megközelítésért tekintse meg a Társítás megszüntetése egy egyértékű navigációs tulajdonság használatával című témakört.

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ékeinek használatával 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 . A fejléc használatával választ kap 201 Created egy rekord létrehozásakor, és választ kap 200 OK a rekord frissítésekor. 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álatakor ne vegye fel a másodlagos kulcsértékeket a kérelem törzsébe.

  • 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 engedélyezi a rendszernek, hogy guid értéket rendeljen az elsődleges kulcshoz. Ez a gyakorlat azért a legjobb, mert a rendszer olyan kulcsokat hoz létre, amelyek az indexhez vannak optimalizálva, és ez a választás 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 érdemes elvégezni egy upsert , de megakadályozni az egyik lehetséges műveletet: vagy a létrehozást, vagy a frissítést. Ezeket a műveleteket a If-Match vagy If-None-Match fejlécek használatával megakadályozhatja. 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 olyan fiókentitást, amelynek elsődleges kulcsértéke accountid egyenlő.00000000-0000-0000-0000-000000000001

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

Ha egyetlen kérelemben több azonos típusú rekordot szeretne törölni, használja a DeleteMultiple műveletet. A normál táblák nem támogatják ezt a DeleteMultiple műveletet, de minden rugalmas tábla igen.

Megjegyzés:

Standard táblák esetén használja a BulkDelete műveletet. Ez a művelet 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, az adatok elérésekor adja meg a partíciókulcsot.

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