Delen via

Entiteiten bijwerken en verwijderen met de Web-API

  • Artikel

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Bewerkingen om gegevens te wijzigen vormen een wezenlijk onderdeel van de Web-API. Naast eenvoudige bijwerk- en verwijderbewerkingen kunt u bewerkingen uitvoeren op enkele kenmerken en upsert-aanvragen opstellen waarmee een entiteit wordt bijgewerkt of ingevoegd, afhankelijk van de vraag of de entiteit bestaat.

Notitie

De metagegevens die entiteiten definiëren, worden bijgewerkt op een andere manier.Meer informatie:Entiteitsdefinities maken en bijwerken met behulp van de web-API

In dit onderwerp

Basisbijwerkbewerking

Bijwerken met gegevens retourneren

Eén eigenschapswaarde bijwerken

Eén eigenschapswaarde verwijderen

Upsert toepassen op een entiteit

Basisverwijderbewerking

Basisbijwerkbewerking

In bijwerkbewerkingen wordt HTTP PATCH gebruikt. Geef een JSON-object door met de eigenschappen die u wilt bijwerken in URI waarmee de entiteit wordt vertegenwoordigd. Een respons met een status van 204 wordt geretourneerd als de bijwerking is gelukt.

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

Belangrijk

Neem bij het bijwerken van een entiteit alleen de eigenschappen op die u in de aanvraagtekst wijzigt. Als u eenvoudigweg de eigenschappen van een entiteit bijwerkt die u eerder hebt opgehaald en die JSON in uw aanvraag opneemt, wordt elke eigenschap bijgewerkt, zelfs als de waarde hetzelfde is. Hierdoor kan het lijken dat eigenschappen zijn bijgewerkt in controlegegevens, terwijl ze in werkelijkheid niet zijn gewijzigd.

  • Aanvraag

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • Respons

    HTTP/1.1 204 No Content
OData-Version: 4.0

Notitie

Zie Entiteiten koppelen bij bijwerken voor informatie over het koppelen van entiteiten bij het bijwerken.

Bijwerken met gegevens retourneren

Notitie

Deze mogelijkheid is toegevoegd in de Update voor Dynamics 365 (online en on-premises) - december 2016.

Om gegevens op te halen van een entiteit die u bijwerkt, kunt u uw PATCH-aanvraag zodanig samenstellen dat de gegevens van de gemaakte record worden geretourneerd met de status 200 (OK). Om dit resultaat te verkrijgen, moet u de voorkeur return=representation gebruiken in de aanvraagheaders.

Om te controleren welke eigenschappen worden geretourneerd, voegt u de queryoptie $select toe aan de URL naar de entiteitset. Als de queryoptie $expand wordt gebruikt, wordt deze genegeerd.

In dit voorbeeld wordt een accountentiteit bijgewerkt en worden de gewenste gegevens in de respons geretourneerd.

  • Aanvraag

    PATCH cc_WebAPI_ServiceURI/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

{"name":"Updated Sample Account"}

  • Respons

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$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"
}

Eén eigenschapswaarde bijwerken

Als u slechts één eigenschapswaarde wilt bijwerken, gebruikt u een PUT-aanvraag met de naam van de eigenschap die is toegevoegd aan de Uri van de entiteit.

In het volgende voorbeeld wordt de eigenschap name van een bestaande accountentiteit bijgewerkt met de accountid-waarde van 00000000-0000-0000-0000-000000000001.

  • Aanvraag

    PUT cc_WebAPI_ServiceURI/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"}

  • Respons

    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 naam van de eigenschap die is toegevoegd aan de Uri van de entiteit.

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

  • Aanvraag

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Respons

    HTTP/1.1 204 No Content
OData-Version: 4.0

Notitie

Dit kan niet worden gebruikt met een navigatie-eigenschap met één waarde om twee entiteiten te ontkoppelen. Raadpleeg voor een andere aanpak Een verwijzing naar een entiteit verwijderen.

Upsert toepassen op een entiteit

Een upsert-bewerking is precies hetzelfde als een bijwerkbewerking. Er wordt een PATCH-aanvraag gebruikt en een URI om te verwijzen naar een specifieke entiteit. Het verschil is dat als de entiteit niet bestaat, deze wordt gemaakt. Als de entiteit al bestaat, wordt deze bijgewerkt. Normaal gesproken wanneer u een nieuwe entiteit maakt, laat u het systeem een unieke ID toewijzen. Dit is de beste manier. Maar als u een record met een specifieke id-waarde moet maken, bevat een upsert-bewerking een manier om dit te doen. Dit kan handig zijn in de situatie waarin u gegevens in verschillende systemen synchroniseert.

In sommige situaties wilt u echter een upsert uitvoeren, maar wel een van de mogelijke standaardacties voorkomen: maken of bijwerken. U kunt dit bereiken door de headers If-Match of If-None-Match toe te voegen. Zie Upsert-bewerkingen beperken voor meer informatie.

Basisverwijderbewerking

Een verwijderbewerking is heel eenvoudig. Gebruik het werkwoord DELETE met de URI van de entiteit die u wilt verwijderen. Met dit voorbeeldbericht wordt een accountentiteit verwijderd met de waarde van de primaire sleutel accountid die gelijk is aan 00000000-0000-0000-0000-000000000001.

  • Aanvraag

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Respons
    Als de entiteit bestaat, krijgt u een normale respons met status 204 om aan te geven dat de verwijderbewerking is gelukt. Als de entiteit niet wordt gevonden, krijgt u een respons met de status 404.

    HTTP/1.1 204 No Content
OData-Version: 4.0

Zie ook

Voorbeeld van eenvoudige Web API-bewerkingen (C#)
Voorbeeld basisbewerkingen web-API (JavaScript op client)
Bewerkingen uitvoeren met de web-API
HTTP-aanvragen opstellen en fouten afhandelen
Querygegevens met behulp van de web-API
Een entiteit maken met de web-API
Een entiteit ophalen met de web-API
Entiteiten koppelen en ontkoppelen met de web-API
Web-API-functies gebruiken
Web-API-acties gebruiken
Batchbewerkingen uitvoeren met de Web API
Zich als een andere gebruiker voordoen die de Web API gebruikt
Voorwaardelijke bewerkingen uitvoer met de web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht