Aktualizace a odstranění řádků tabulky pomocí webového rozhraní API

Operace pro úpravu dat jsou základní součástí webového rozhraní API. Kromě jednoduchých operací aktualizace a odstranění můžete provádět operace na jednotlivých sloupcích tabulky (atributy entit) a vytvářet požadavky upsertu, které buď aktualizují, nebo vloží data podle toho, zda data existují.

Základní aktualizace

Operace aktualizace používají příkaz HTTP PATCH . Předejte objekt JSON obsahující vlastnosti, které chcete aktualizovat na identifikátor URI, který představuje záznam. Pokud je aktualizace úspěšná, vrátí se odpověď se stavem 204 No Content .

Hlavička If-Match: * zajišťuje, že nevytvoříte nový záznam náhodným provedením operace typu upsert. Další informace: Zabránění vytváření v operaci upsert

Důležité

Při aktualizaci entity zahrňte pouze vlastnosti, které měníte v textu požadavku. Jednoduchým aktualizováním vlastností entity, kterou jste předtím načetli, a jejich zahrnutím do vašeho požadavku ve formátu JSON, budou aktualizovány každá vlastnost, i přesto že je hodnota stejná. To může způsobit systémové události, které můžou aktivovat obchodní logiku, která očekává, že se hodnoty změnily. To může způsobit, že se vlastnosti v datech auditování aktualizovaly, když se ve skutečnosti nezměnily.

Při aktualizaci statecode vlastnosti je důležité vždy nastavit požadované statuscode. statecode a statuscode mají závislé hodnoty. Pro danou statuscode hodnotu může existovat více platných statecode hodnot, ale každý statecode sloupec má nakonfigurovanou jednu hodnotu DefaultStatus. Když aktualizujete statecode bez zadání statuscode, systém nastaví výchozí stavovou hodnotu. Pokud je v tabulce a statuscode sloupci povolené auditování, změněná hodnota pro statuscode sloupec se v datech auditu nezadá, pokud není zadána v operaci aktualizace.

Poznámka:

Definice atributů zahrnuje RequiredLevel vlastnost. Pokud je tato možnost nastavena na SystemRequired, nelze tyto atributy nastavit na hodnotu null. Další informace: Úroveň požadavků na atribut

Tento příklad aktualizuje existující záznam účtu s accountid hodnotou 00000000-0000-0000-0000-0000-000000000001.

Prosba:

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  
}  

Odpověď:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Poznámka:

Informace o přidružení a zrušení přidružení entit při aktualizaci najdete v tématu Použití vlastností navigace s jednou hodnotou .

Aktualizace s vrácenými daty

Pokud chcete načíst data z entity, kterou aktualizujete, můžete vytvořit PATCH požadavek tak, aby se data z vytvořeného záznamu vrátila se stavem 200 (OK). Pokud chcete získat tento výsledek, musíte použít hlavičku Prefer: return=representation požadavku.

Pokud chcete určit, které vlastnosti se vrátí, připojte $select možnost dotazu k adrese URL k sadě entit. Možnost $expand dotazu se při použití ignoruje.

Tento příklad aktualizuje entitu účtu a vrátí požadovaná data v odpovědi.

Prosba:

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

Odpověď:

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

Aktualizace více záznamů v jednom požadavku

Nejrychlejší způsob, jak aktualizovat více záznamů stejného typu v jednom požadavku, je použít akci UpdateMultiple. K okamžiku, kdy byl tento text napsán akce UpdateMultiple. Ne všechny standardní tabulky tuto akci podporují, ale všechny elastické tabulky ji podporují.

Další informace:

• Zprávy hromadných operací
• Ukázka: Použití hromadného provozu webového rozhraní API
• Použijte updateMultiple s elastickými tabulkami

Aktualizace jedné hodnoty vlastnosti

Pokud chcete aktualizovat pouze jednu hodnotu vlastnosti, použijte PUT požadavek s názvem vlastnosti připojeným k identifikátoru URI entity.

Následující příklad aktualizuje name vlastnost existujícího account řádku s accountid hodnotou 000000000-0000-0000-0000-0000-00000000001.

Prosba:

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

Odpověď:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Odstranění jedné hodnoty vlastnosti

Pokud chcete odstranit hodnotu jedné vlastnosti, použijte DELETE požadavek s názvem vlastnosti připojeným k identifikátoru URI entity.

Následující příklad odstraní hodnotu description vlastnosti entity účtu s accountid hodnotou 000000000-0000-0000-0000-0000-00000000000001.

Prosba:

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  

Odpověď:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Poznámka:

Tuto možnost nelze použít s navigační vlastností s jednou hodnotou pro oddělení dvou entit. Alternativní přístup naleznete v tématu Odpojení s navigační vlastností s jedinou hodnotou .

Upsert řádku tabulky

Operace upsert je podobná aktualizaci. Použije PATCH požadavek a pomocí identifikátoru URI odkazuje na konkrétní záznam. Rozdíl je v tom, že pokud záznam neexistuje, vytvoří se. Pokud už existuje, aktualizuje se.

Upsert je cenný při synchronizaci dat mezi externími systémy. Externí systém nemusí obsahovat odkaz na primární klíč tabulky Dataverse, takže můžete nakonfigurovat alternativní klíče pro tabulku Dataverse pomocí hodnot z externího systému, které jednoznačně identifikují záznam v obou systémech. Další informace: Definování alternativních klíčů pro referenci řádků

Všechny alternativní klíče definované pro tabulku můžete zobrazit v poznámkách pro typ entity v dokumentu služby $metadata. Další informace: Alternativní klíče

V následujícím příkladu je tabulka s názvem sample_thing , který má alternativní klíč odkazující na dva sloupce: sample_key1 a sample_key2, které jsou definovány pro ukládání celočíselné hodnoty.

Prosba:

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

U operací vytvoření nebo aktualizace získáte stejnou odpověď. Všimněte si, že hlavička OData-EntityId odpovědi používá hodnoty klíče místo identifikátoru primárního klíče GUID pro záznam.

Odpověď:

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)

Vzhledem k tomu, že odpověď je stejná, nemůžete zjistit, jestli operace reprezentovala Create operaci nebo Update operaci.

Pokud potřebujete vědět, můžete použít hlavičku Prefer: return=representation požadavku. Pomocí této hlavičky získáte 201 Created odpověď při vytvoření záznamu a 200 OK odpovědi při aktualizaci záznamu. Tato možnost přidá Retrieve operaci, která má vliv na výkon. Pokud použijete hlavičku Prefer: return=representation požadavku, ujistěte se, že $select obsahuje minimální množství dat, nejlépe jenom sloupec primárního klíče. Další informace: Aktualizujte vrácená data a vytvořte s vrácenými daty.

Pokud používáte alternativní klíče, neměli byste do textu požadavku zahrnout hodnoty alternativního klíče.

• Pokud upsert představuje Update, tyto alternativní hodnoty klíče jsou ignorovány. Alternativní hodnoty klíče nemůžete aktualizovat při jejich použití k identifikaci záznamu.
• Pokud upsert představuje Create, klíčové hodnoty v adrese URL jsou nastaveny pro tento záznam, pokud nejsou přítomné v těle. Není tedy nutné je zahrnout do textu žádosti.

Další informace: Použití funkce Upsert k vytvoření nebo aktualizaci záznamu

Poznámka:

Při vytváření nového záznamu obvykle umožníte systému přiřadit hodnotu GUID pro primární klíč. Toto je osvědčený postup, protože systém generuje klíče, které jsou optimalizované pro index, a tím se zvyšuje výkon. Pokud ale potřebujete vytvořit záznam s konkrétní hodnotou primárního klíče, například když je hodnota GUID klíče generována externím systémem, poskytuje operace způsob, upsert jak to provést.

Zabránění vytvoření nebo aktualizaci pomocí upsert

Někdy existují situace, kdy chcete provést operaci upsert, ale chcete zabránit některé z možných operací: vytvoření nebo aktualizace. Můžete to udělat pomocí If-Match záhlaví nebo If-None-Match záhlaví. Další informace naleznete v tématu Omezení operací upsert.

Základní smazání

Operace odstranění je jednoduchá. Použijte sloveso DELETE s identifikátorem URI entity, kterou chcete odstranit. Tato ukázková zpráva odstraní entitu účtu s hodnotou primárního klíče accountid rovnou 00000000-0000-0000-0000-000000000001.

Prosba:

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  

Odpověď:

Pokud entita existuje, získáte normální odpověď se stavem 204, který indikuje, že odstranění bylo úspěšné. Pokud se entita nenajde, zobrazí se odpověď se stavem 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0  

Kontrola duplicitních záznamů

Další informace o tom, jak zkontrolovat duplicitní záznamy během operace aktualizace, naleznete v tématu Zjištění duplicit během operace aktualizace pomocí webového rozhraní API.

Odstranění více záznamů v jednom požadavku

Nejrychlejší způsob, jak odstranit více záznamů stejného typu v jednom požadavku, je použít DeleteMultiple akci. K době napsání tohoto textu je akce DeleteMultiple funkce Preview. Standardní tabulky tuto akci nepodporují, ale elastické tabulky ano.

Poznámka:

U standardních tabulek doporučujeme použít akci BulkDelete, která umožňuje asynchronní odstranění záznamů, které odpovídají dotazu. Další informace: Hromadné odstranění dat

Další informace:

• Zprávy hromadných operací
• Ukázkový kód elastické tabulky
• Použití DeleteMultiple s elastickými tabulkami

Aktualizace a odstranění dokumentů v oddílech úložiště

Pokud aktualizujete nebo odstraňujete data elastické tabulky uložená v oddílech, nezapomeňte při přístupu k datům zadat klíč oddílu.

Další informace: Volba hodnoty PartitionId

Viz také

Ukázka základního provozu webového rozhraní API (C#)
Ukázka základního provozu webového rozhraní API (JavaScript na straně klienta)
Provádění operací pomocí webového rozhraní API
Vytváření požadavků HTTP a zpracování chyb
Dotazování na data pomocí webového rozhraní API
Vytvoření řádku tabulky pomocí webového rozhraní API
Načtení řádku tabulky pomocí webového rozhraní API
Spojení a odpojení řádků tabulky pomocí API
Použití funkcí webového rozhraní API
Použít akce webového rozhraní API
Spouštění dávkových operací pomocí webového rozhraní API
Zosobnění jiného uživatele pomocí webového rozhraní API
Provádění podmíněných operací pomocí webového rozhraní API