Dela via

Uppdatera och ta bort tabellrader med hjälp av webb-API:et

Åtgärder för att ändra data är en viktig del av webb-API:et. Förutom enkla åtgärder för uppdatering och borttagning kan du utföra åtgärder på enskilda tabellkolumner (entitetsattribut) och skapa upsert-begäranden som antingen uppdaterar eller infogar data beroende på om de finns.

Enkel uppdatering

Uppdateringsåtgärder använder HTTP-verbet PATCH . Skicka ett JSON-objekt som innehåller de egenskaper som du vill uppdatera till den URI som representerar posten. Ett svar med statusen 204 No Content returneras om uppdateringen lyckas.

Rubriken If-Match: * ser till att du inte skapar en ny post genom att av misstag utföra en upsert-åtgärd. Mer information: Förhindra att skapa i upsert.

Viktigt!

När du uppdaterar en entitet tar du bara med de egenskaper som du ändrar i begärandetexten. Om du bara uppdaterar egenskaperna för en entitet som du tidigare hämtade, och inklusive den JSON-filen i din begäran, uppdateras varje egenskap även om värdet är detsamma. Detta kan orsaka systemhändelser som kan utlösa affärslogik som förväntar sig att värdena har ändrats. Detta kan göra att egenskaperna verkar ha uppdaterats i granskningsdata när de faktiskt inte har ändrats.

När du uppdaterar statecode egenskapen är det viktigt att alltid ange önskad statuscode. statecode och statuscode har beroende värden. Det kan finnas flera giltiga statuscode värden för ett angivet statecode värde, men varje statecode kolumn har ett enda DefaultStatus-värde konfigurerat. När du uppdaterar statecode utan att ange ett statuscodeanges standardstatusvärdet av systemet. När granskning är aktiverat i tabellen och statuscode kolumnen registreras inte det ändrade värdet för statuscode kolumnen i granskningsdata om det inte anges i uppdateringsåtgärden.

Anmärkning

Definitionen för attribut innehåller en RequiredLevel egenskap. När detta är inställt på SystemRequiredkan du inte ange dessa attribut till ett null-värde. Mer information: Kravnivå för attribut

Det här exemplet uppdaterar en befintlig kontopost med accountid värdet 00000000-0000-0000-0000-0000-0000000001.

Begäran:

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  
}

Svar:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Anmärkning

Se Använda navigeringsegenskaper med enkelvärde för information om hur du associerar och kopplar bort entiteter vid uppdatering.

Uppdatera med data som returneras

Om du vill hämta data från en entitet som du uppdaterar kan du skriva din PATCH begäran så att data från den skapade posten returneras med statusen 200 (OK). För att få det här resultatet måste du använda begärandehuvudet Prefer: return=representation .

Om du vill kontrollera vilka egenskaper som returneras lägger du till frågealternativet $select i URL:en till entitetsuppsättningen. Frågealternativet $expand ignoreras om det används.

Det här exemplet uppdaterar en kontoentitet och returnerar begärda data i svaret.

Begäran:

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

Svar:

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

Uppdatera flera poster i en enda begäran

Det snabbaste sättet att uppdatera flera poster av samma typ i en enda begäran är att använda åtgärden UpdateMultiple. Vid tidpunkten för denna skrivning åtgärden UpdateMultiple. Alla standardtabeller stöder inte den här åtgärden, men alla elastiska tabeller gör det.

Mer information:

Uppdatera ett enda egenskapsvärde

När du bara vill uppdatera ett enda egenskapsvärde använder du en PUT begäran med egenskapsnamnet som läggs till i entitetens URI.

I följande exempel uppdateras egenskapen för name en befintlig account rad med accountid värdet 00000000-0000-0000-0000-0000-0000000001.

Begäran:

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

Svar:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Ta bort ett enda egenskapsvärde

Om du vill ta bort värdet för en enskild egenskap använder du en DELETE begäran med egenskapsnamnet som läggs till i entitetens URI.

I följande exempel raderas värdet för description egenskapen för en kontoentitet med värdet accountid 00000000-0000-0000-0000-000000000001.

Begäran:

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

Svar:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Anmärkning

Detta kan inte användas med en enkelvärd navigeringsegenskap för att avgränsa två entiteter. En alternativ metod finns i Koppla bort med en enkelvärd navigeringsegenskap.

Upsert en rad i tabellen

En upsert-åtgärd liknar en uppdatering. Den gör en PATCH-begäran och använder en URI för att referera till en specifik post. Skillnaden är att om posten inte finns skapas den. Om den redan finns uppdateras den.

Upsert är värdefullt när du synkroniserar data mellan externa system. Det externa systemet kanske inte innehåller någon referens till den primära nyckeln i tabellen Dataverse, så du kan konfigurera alternativa nycklar för Dataverse-tabellen med värden från det externa systemet som unikt identifierar posten i båda systemen. Mer information: Definiera alternativa nycklar till referensrader

Du kan se eventuella alternativa nycklar som har definierats för en tabell i anteckningarna för entitetstypen i $metadata-tjänstdokumentet. Mer information: Alternate Keys.

I följande exempel finns det en tabell med namnet sample_thing som har en alternativ nyckel som refererar till två kolumner: sample_key1 och sample_key2, som båda definieras för att lagra heltalsvärden.

Begäran:

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

För både skapa- eller uppdateringsåtgärder får du samma svar. Observera hur OData-EntityId svars­huvudet använder nyckelvärdena istället för postens GUID-baserade primärnyckel.

Svar:

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)

Eftersom svaret är detsamma kan du inte veta om åtgärden representerar en Create eller Update åtgärd.

Om du behöver veta kan du använda begärandehuvudet Prefer: return=representation . Med den här rubriken får du ett 201 Created svar när en post skapas och ett 200 OK svar när posten uppdateras. Det här alternativet lägger till en Retrieve åtgärd som påverkar prestanda. Om du använder Prefer: return=representation begärandehuvudet kontrollerar du att din $select innehåller den minimala mängden data, helst bara primärnyckelkolumnen. Mer information: Uppdatera med data som returneras och Skapa med data som returneras.

När du använder alternativa nycklar bör du inte inkludera de alternativa nyckelvärdena i brödtexten i begäran.

  • När en upsert representerar en Updateignoreras dessa alternativa nyckelvärden. Du kan inte uppdatera alternativa nyckelvärden när du använder dem för att identifiera posten.
  • När en upsert representerar en Create anges nyckelvärdena i URL:en för posten om de inte finns i brödtexten. Därför behöver du inte inkludera dem i brödtexten i begäran.

Mer information: Använd Upsert för att skapa eller uppdatera en registerpost

Anmärkning

Normalt när du skapar en ny post låter du systemet tilldela ett GUID-värde för primärnyckeln. Detta är en bra metod eftersom systemet genererar nycklar som är optimerade för indexet och detta förbättrar prestandan. Men om du behöver skapa en post med ett specifikt primärnyckelvärde, till exempel när nyckel-GUID-värdet genereras av ett externt system, ger upsert-operationen dig ett sätt att göra detta.

Förhindra att skapa eller uppdatera med upsert

Ibland finns det situationer där du vill utföra en upsert, men du vill förhindra en av de potentiella åtgärderna: antingen skapa eller uppdatera. Du kan göra detta med hjälp av rubrikerna If-Match eller If-None-Match . Mer information finns i Begränsa upsert-operationer.

Grundläggande borttagning

En borttagningsåtgärd är enkel. Använd verbet DELETE med URI:n för den entitet som du vill ta bort. Det här exempelmeddelandet tar bort en kontoentitet med primärnyckelvärdet accountid lika med 00000000-0000-0000-0000-0000000001.

Begäran:

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

Svar:

Om entiteten finns får du ett normalt svar med status 204 som anger att borttagningen lyckades. Om entiteten inte hittas får du ett svar med status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Kontrollera dubbletter i register

Mer information om hur du söker efter dubblettposter under en uppdateringsåtgärd finns i Identifiera dubbletter under uppdateringsåtgärden med hjälp av webb-API:et.

Ta bort flera poster i en enda begäran

Det snabbaste sättet att ta bort flera poster av samma typ i en enda begäran är att använda åtgärden DeleteMultiple . När detta skrivs är åtgärden DeleteMultiple en förhandsversionsfunktion. Standardtabeller stöder inte den här åtgärden, men alla elastiska tabeller gör det.

Anmärkning

För standardtabeller rekommenderar vi att du använder åtgärden BulkDelete, som möjliggör asynkron borttagning av poster som matchar en fråga. Mer information: Ta bort data massvis

Mer information:

Uppdatera och ta bort dokument i lagringspartitioner

Om du uppdaterar eller tar bort elastiska tabelldata som lagras i partitioner måste du ange partitionsnyckeln vid åtkomst till dessa data.

Mer information: Välja ett PartitionId-värde

Se även

Exempel på grundläggande åtgärder för webb-API (C#)
Exempel på grundläggande åtgärder för webb-API (JavaScript på klientsidan)
Utföra åtgärder med hjälp av webb-API
Skapa Http-begäranden och hantera fel
Fråga efter data med hjälp av webb-API:et
Skapa en tabellrad med hjälp av webb-API:et
Hämta en tabellrad med hjälp av webb-API:et
Associera och avassociera tabellrader med hjälp av webb-API:et
Använda webb-API-funktioner
Använda Web API-åtgärder
Köra batchåtgärder med hjälp av webb-API:et
Personifiera en annan användare med hjälp av webb-API:et
Utföra villkorsstyrda åtgärder med hjälp av webb-API:et