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

Operace, které upravují data, jsou základní součástí webového rozhraní API. Kromě jednoduchých operací aktualizace a odstranění můžete provádět operace se sloupci jedné tabulky (atributy entit) a vytvářet požadavky upsertu , které aktualizují nebo vkládají data v závislosti na tom, jestli 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í odpověď stav 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 naleznete v tématu Zabránění vytváření v upsertu.

Důležité

Při aktualizaci entity zahrňte pouze vlastnosti, které měníte v textu požadavku. Pokud entitu aktualizujete zahrnutím všech vlastností entity, kterou jste předtím načetli, operace aktualizuje každou vlastnost i v případě, že je hodnota stejná. Tato aktualizace může způsobit systémové události, které aktivují obchodní logiku, která očekává, že se hodnoty změnily. Může to způsobit, že se vlastnosti v datech auditování aktualizují, když se ve skutečnosti nezměnily.

Při aktualizaci statecode vlastnosti vždy nastavte požadovaný statuscode. Hodnoty statecode a statuscode závisejí na sobě navzájem. Pro danou statecode hodnotu může existovat více platných statuscode hodnot. Každý statecode sloupec má ale nakonfigurovanou jednu hodnotu DefaultStatus . Když aktualizujete statecode bez zadání statuscode, systém nastaví výchozí hodnotu stavu. Pokud povolíte auditování v tabulce a statuscode sloupci, změněná hodnota statuscode sloupce se v datech auditu nezachytí, pokud ji nezadáte v operaci aktualizace.

Poznámka:

Definice atributů zahrnuje RequiredLevel vlastnost. Pokud je tato vlastnost nastavena na SystemRequiredhodnotu null, nemůžete tyto atributy nastavit na hodnotu null. Další informace naleznete v tématu Úroveň požadavků atributu.

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 naleznete v tématu Použití jednohodnotových navigačních vlastností.

Aktualizace s vrácenými daty

Pokud chcete načíst data z entity, kterou aktualizujete, vytvořte požadavek PATCH tak, aby vracela data z aktualizovaného záznamu se stavem 200 (OK). K získání tohoto výsledku použijte 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 sady 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. 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 jednu hodnotu vlastnosti, použijte PUT požadavek a přidejte název vlastnosti do identifikátoru URI entity.

Následující příklad aktualizuje vlastnost name existujícího řádku account hodnotou accountid00000000-0000-0000-0000-000000000001.

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 vlastnosti description pro entitu účtu hodnotou accountid00000000-0000-0000-0000-000000000001.

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:

Tento přístup nelze použít s navigační vlastností s jedinou hodnotou k rozpojení dvou entit. Alternativní přístup najdete v tématu Zrušení přidružení pomocí jednohodnotové navigační vlastnosti.

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, nezahrnujte do textu požadavku 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íč. Tento postup je nejlepší, protože systém generuje klíče optimalizované pro index a tato volba zlepš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 chcete provést upsert, ale zabránit jedné z potenciálních operací: buď vytvoření, nebo aktualizaci. Těmto operacím můžete zabránit pomocí If-Match hlaviček.If-None-Match 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 , která je rovna 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

Pokud chcete odstranit více záznamů stejného typu v jednom požadavku, použijte DeleteMultiple akci. Standardní tabulky akci DeleteMultiple nepodporují, ale všechny elastické tabulky ji podporují.

Poznámka:

Pro standardní tabulky použijte akci BulkDelete. Tato akce umožňuje asynchronní odstranění záznamů, které odpovídají dotazu. Další informace najdete v tématu 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, zadejte klíč oddílu při přístupu k datům.

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