Delen via

Tabelrijen bijwerken en verwijderen met behulp van de web-API

Bewerkingen voor het wijzigen van gegevens vormen een belangrijk onderdeel van de web-API. Naast eenvoudige bijwerk- en verwijderbewerkingen kunt u bewerkingen uitvoeren op kolommen met één tabel (entiteitskenmerken) en upsert-aanvragen opstellen waarmee gegevens worden bijgewerkt of ingevoegd, afhankelijk van of deze bestaan.

Basisupdate

Bijwerkbewerkingen maken gebruik van het HTTP-werkwoord PATCH . Geef een JSON-object door met de eigenschappen die u wilt bijwerken naar de URI die de record vertegenwoordigt. Er wordt een antwoord met de status 204 No Content geretourneerd als de update is geslaagd.

De If-Match: * header zorgt ervoor dat u geen nieuwe record maakt door per ongeluk een upsert-bewerking uit te voeren. Meer informatie: Voorkom het maken bij upsert.

Belangrijk

Wanneer u een entiteit bijwerkt, neemt u alleen de eigenschappen op die u in de aanvraagtekst wijzigt. Als u alleen de eigenschappen bijwerkt van een entiteit die u eerder hebt opgehaald en die JSON in uw aanvraag opneemt, wordt elke eigenschap bijgewerkt, ook al is de waarde hetzelfde. Dit kan systeem gebeurtenissen veroorzaken die bedrijfslogica kunnen activeren die verwacht dat de waarden zijn gewijzigd. Dit kan ertoe leiden dat eigenschappen in controlegegevens zijn bijgewerkt wanneer ze in feite niet daadwerkelijk zijn gewijzigd.

Wanneer u de statecode eigenschap bijwerkt, is het belangrijk om altijd de gewenste statuscodeeigenschap in te stellen. statecode en statuscode afhankelijke waarden hebben. Er kunnen meerdere geldige statuscode waarden zijn voor een bepaalde statecode waarde, maar elke statecode kolom heeft één DefaultStatus-waarde geconfigureerd. Wanneer u bijwerkt statecode zonder een statuscodeop te geven, wordt de standaardstatuswaarde door het systeem ingesteld. Wanneer controle is ingeschakeld voor de tabel en de statuscode kolom, wordt de gewijzigde waarde voor de statuscode kolom ook niet vastgelegd in de controlegegevens, tenzij deze is opgegeven in de updatebewerking.

Opmerking

De definitie voor kenmerken bevat een RequiredLevel eigenschap. Als dit is ingesteld op SystemRequired, kunt u deze kenmerken niet instellen op een null-waarde. Meer informatie: Niveau van kenmerkvereiste

In dit voorbeeld wordt een bestaande accountrecord bijgewerkt met de accountid waarde 00000000-0000-0000-0000-000000000001.

Verzoek:

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  
}

Antwoord:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Opmerking

Zie Navigatie-eigenschappen met één waarde gebruiken voor informatie over het koppelen en ontkoppelen van entiteiten bij het bijwerken.

Bijwerken met geretourneerde gegevens

Als u gegevens wilt ophalen uit een entiteit die u bijwerkt, kunt u uw PATCH aanvraag opstellen zodat gegevens uit de gemaakte record worden geretourneerd met de status 200 (OK). Als u dit resultaat wilt ophalen, moet u de Prefer: return=representation aanvraagheader gebruiken.

Als u wilt bepalen welke eigenschappen worden geretourneerd, voegt u de $select queryoptie toe aan de URL van de entiteitsset. De $expand queryoptie wordt genegeerd als deze wordt gebruikt.

In dit voorbeeld wordt een accountentiteit bijgewerkt en worden de aangevraagde gegevens in het antwoord geretourneerd.

Verzoek:

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

Antwoord:

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

Meerdere records in één aanvraag bijwerken

De snelste manier om meerdere records van hetzelfde type in één aanvraag bij te werken, is door de actie UpdateMultiple te gebruiken. Op het moment van schrijven wordt de actie UpdateMultiple uitgevoerd. Niet alle standaardtabellen ondersteunen deze actie, maar alle elastische tabellen wel.

Meer informatie:

Eén eigenschapswaarde bijwerken

Als u slechts één eigenschapswaarde wilt bijwerken, gebruikt u een PUT aanvraag met de eigenschapsnaam die is toegevoegd aan de URI van de entiteit.

In het volgende voorbeeld wordt de name eigenschap van een bestaande account rij bijgewerkt met de accountid waarde 00000000-0000-0000-0000-0000000000001.

Verzoek:

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

Antwoord:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Eén eigenschapswaarde verwijderen

Als u de waarde van één eigenschap wilt verwijderen, gebruikt u een DELETE aanvraag met de eigenschapsnaam die is toegevoegd aan de URI van de entiteit.

In het volgende voorbeeld wordt de waarde van de description eigenschap van een accountentiteit met de accountid waarde 00000000-0000-0000-0000-000000000001 verwijderd.

Verzoek:

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

Antwoord:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Opmerking

Dit kan niet worden gebruikt met een navigatie-eigenschap met één waarde om twee entiteiten te ontkoppelen. Zie Ontkoppelen met een navigatie-eigenschap met één waarde voor een alternatieve benadering.

Een tabelrij upsert

Een upsert-bewerking is vergelijkbaar met een update. Er wordt een PATCH aanvraag gebruikt en een URI gebruikt om naar een specifieke record te verwijzen. Het verschil is dat als de record niet bestaat, deze wordt gemaakt. Als deze al bestaat, wordt deze bijgewerkt.

Upsert is waardevol bij het synchroniseren van gegevens tussen externe systemen. Het externe systeem bevat mogelijk geen verwijzing naar de primaire sleutel van de Dataverse-tabel, zodat u alternatieve sleutels voor de Dataverse-tabel kunt configureren met behulp van waarden van het externe systeem waarmee de record op beide systemen uniek wordt geïdentificeerd. Meer informatie: Alternatieve sleutels definiëren om naar rijen te verwijzen

U kunt alternatieve sleutels zien die zijn gedefinieerd voor een tabel in de aantekeningen voor het entiteitstype in het $metadata servicedocument. Meer informatie: Alternatieve sleutels.

In het volgende voorbeeld is er een tabel met de naam sample_thing met een alternatieve sleutel die verwijst naar twee kolommen: sample_key1 en sample_key2, die beide zijn gedefinieerd om gehele getallen op te slaan.

Verzoek:

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

Voor zowel maak- als bijwerkbewerkingen krijgt u dezelfde reactie. U ziet hoe de OData-EntityId antwoordheader de sleutelwaarden gebruikt in plaats van de primaire GUID-sleutel-id voor de record.

Antwoord:

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)

Omdat het antwoord hetzelfde is, kunt u niet weten of de bewerking een Create of Update bewerking vertegenwoordigt.

Als u dit wilt weten, kunt u de Prefer: return=representation aanvraagheader gebruiken. Met deze header krijgt u een 201 Created antwoord wanneer een record wordt gemaakt en een 200 OK antwoord wanneer de record wordt bijgewerkt. Met deze optie wordt een Retrieve bewerking toegevoegd die invloed heeft op de prestaties. Als u de Prefer: return=representation aanvraagheader gebruikt, moet u ervoor zorgen dat u $select de minimale hoeveelheid gegevens opneemt, bij voorkeur alleen de primaire-sleutelkolom. Meer informatie: Bijwerken met geretourneerde gegevens en Maken met geretourneerde gegevens.

Wanneer u alternatieve sleutels gebruikt, moet u de alternatieve sleutelwaarden niet opnemen in de hoofdtekst van de aanvraag.

  • Wanneer een upsert een Updatewaarde vertegenwoordigt, worden deze alternatieve sleutelwaarden genegeerd. U kunt alternatieve sleutelwaarden niet bijwerken terwijl u deze gebruikt om de record te identificeren.
  • Wanneer een upsert een Createvertegenwoordigt, worden de sleutelwaarden in de URL ingesteld voor de record als ze niet aanwezig zijn in de hoofdtekst. U hoeft ze dus niet op te nemen in de hoofdtekst van de aanvraag.

Meer informatie: Upsert gebruiken om een record te maken of bij te werken

Opmerking

Normaal gesproken laat u bij het aanmaken van een nieuw record het systeem een GUID-waarde voor de primaire sleutel toewijzen. Dit is een best practice omdat het systeem sleutels genereert die zijn geoptimaliseerd voor de index en dit verbetert de prestaties. Maar als u een record wilt maken met een specifieke primaire-sleutelwaarde, zoals wanneer de sleutel-GUID-waarde wordt gegenereerd door een extern systeem, biedt de upsert bewerking een manier om dit te doen.

Voorkomen van het aanmaken of bijwerken met een upsert-operatie

Soms zijn er situaties waarin u een upsert wilt uitvoeren, maar u wilt een van de mogelijke bewerkingen verbieden: ofwel maken of bijwerken. U kunt dit doen met behulp van de If-Match of If-None-Match headers. Zie limiet op upsert-bewerkingen voor meer informatie.

Standaard verwijderen

Een verwijderbewerking is eenvoudig. Gebruik het DELETE werkwoord met de URI van de entiteit die u wilt verwijderen. In dit voorbeeldbericht wordt een accountentiteit verwijderd met de primaire-sleutelwaarde accountid gelijk aan 00000000-0000-0000-00000000000001.

Verzoek:

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

Antwoord:

Als de entiteit bestaat, krijgt u een normaal antwoord met status 204 om aan te geven dat het verwijderen is geslaagd. Als de entiteit niet wordt gevonden, krijgt u een antwoord met de status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Controleren op dubbele records

Zie Duplicaten detecteren tijdens de updatebewerking met behulp van de web-API voor meer informatie over het controleren op dubbele records tijdens een updatebewerking.

Meerdere records in één aanvraag verwijderen

De snelste manier om meerdere records van hetzelfde type in één aanvraag te verwijderen, is door de DeleteMultiple actie te gebruiken. Op het moment van schrijven is de DeleteMultiple actie een preview-functie. Standaardtabellen bieden geen ondersteuning voor deze actie, maar alle elastische tabellen wel.

Opmerking

Voor standaardtabellen wordt u aangeraden de actie BulkDelete te gebruiken, waardoor asynchrone verwijdering van records die overeenkomen met een query mogelijk is. Meer informatie: Gegevens bulksgewijs verwijderen

Meer informatie:

Documenten in opslagpartities bijwerken en verwijderen

Als u elastische tabelgegevens bijwerkt of verwijdert die zijn opgeslagen in partities, moet u de partitiesleutel opgeven bij het openen van die gegevens.

Meer informatie: Een PartitionId-waarde kiezen

Zie ook

Web-API Basic Operations Sample (C#)
Web-API Basic Operations Sample (JavaScript aan clientzijde)
Bewerkingen uitvoeren met de web-API
Http-aanvragen opstellen en fouten afhandelen
Query's uitvoeren op gegevens met behulp van de web-API
Een tabelrij maken met behulp van de web-API
Een tabelrij ophalen met behulp van de web-API
Tabelrijen koppelen en ontkoppelen met behulp van de web-API
Web-API-functies gebruiken
Web-API-acties gebruiken
Batchbewerkingen uitvoeren met behulp van de web-API
Een andere gebruiker imiteren met behulp van de web-API
Voorwaardelijke bewerkingen uitvoeren met behulp van de web-API

  • Last updated on