Een entiteit ophalen met de web-API

Artikel
10/31/2017

Gepubliceerd: januari 2017

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

Gebruik een GET-aanvraag om gegevens voor een entiteit op te halen, die is opgegeven als de resource met een unieke id. Bij het ophalen van een entiteit kunt u ook specifieke eigenschappen opvragen en navigatie-eigenschappen uitvouwen om eigenschappen van gerelateerde entiteiten te retourneren.

Notitie

Zie Query's uitvoeren op metagegevens via de web-API voor informatie over het ophalen van entiteitmetagegevens.

In dit onderwerp

Eenvoudig voorbeeld voor ophalen

Specifieke eigenschappen ophalen

Ophalen met behulp van een alternatieve sleutel

De waarde van een enkele eigenschap ophalen

Waarden van navigatie-eigenschappen ophalen

Gerelateerde entiteiten ophalen voor een entiteit door navigatie-eigenschappen uit te vouwen

Opties om toe te passen op uitgevouwen entiteiten

Detecteren of een entiteit is gewijzigd nadat deze is opgehaald

Opgemaakte waarden ophalen

Eenvoudig voorbeeld voor ophalen

In dit voorbeeld worden gegevens voor een accountentiteitsexemplaar geretourneerd, waarvoor de waarde van de primaire sleutel gelijk is aan 00000000-0000-0000-0000-000000000001.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

Als u meerdere entiteiten tegelijk wilt ophalen, raadpleegt u Eenvoudig queryvoorbeeld in het onderwerp Querygegevens met behulp van de web-API.

Waarschuwing

In het bovenstaande voorbeeld worden alle eigenschappen voor de accountrecord geretourneerd, wat ingaat tegen de best practices voor prestaties bij het ophalen van gegevens. In dit voorbeeld werd alleen getoond hoe u een basisophaalbewerking uitvoert van een entiteitsexemplaar in Dynamics 365. Omdat alle eigenschappen werden geretourneerd, werd niet de responsinformatie voor de aanvraag in dit voorbeeld vermeld.

Vanuit het oogpunt van de best practice voor prestaties moet u altijd de systeemqueryoptie $select gebruiken om het aantal geretourneerde eigenschappen te beperken wanneer gegevens worden opgehaald. Zie de volgende sectie Specifieke eigenschappen ophalen voor informatie hierover.

Specifieke eigenschappen ophalen

Gebruik de systeemqueryoptie $select om het aantal geretourneerde eigenschappen te beperken door een lijst met door komma's gescheiden eigenschapsnamen op te nemen. Dit is een belangrijke best practice voor prestaties. Als eigenschappen niet met $select zijn opgegeven, worden alle eigenschappen geretourneerd.

In het volgende voorbeeld worden de eigenschappen name en revenue opgehaald voor de accountentiteit waarvan de primaire sleutelwaarde gelijk is aan 00000000-0000-0000-0000-000000000001.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue)/$entity",
"@odata.etag": "W/\"502186\"",
"name": "A. Datum Corporation (sample)",
"revenue": 10000,
"accountid": "00000000-0000-0000-0000-000000000001",
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"
}

Als u bepaalde typen eigenschappen aanvraagt, kunt u verwachten dat er automatisch extra alleen-lezeneigenschappen worden geretourneerd.

Als u een geldwaarde aanvraagt, wordt de _transactioncurrencyid_value-opzoekeigenschap geretourneerd. Deze eigenschap bevat alleen de GUID-waarde van de transactievaluta zodat u deze waarde kunt gebruiken om informatie over de valuta op te halen via transactioncurrency EntityType Door aantekeningen aan te vragen, kunt u ook aanvullende gegevens ontvangen via dezelfde aanvraag.Meer informatie:Gegevens over opzoekeigenschappen ophalen

Als u een eigenschap aanvraagt die deel uitmaakt van een samengesteld kenmerk voor een adres, ontvangt u ook de samengestelde eigenschap. Wanneer u met uw query de eigenschap address1_line1 voor een contactpersoon aanvraagt, wordt bijvoorbeeld ook de eigenschap address1_composite geretourneerd.Meer informatie:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

Ophalen met behulp van een alternatieve sleutel

Als voor een entiteit een alternatieve sleutel is gedefinieerd, kunt u de entiteit ook ophalen met behulp van de alternatieve sleutel in plaats van de unieke id. Als bijvoorbeeld de entiteit Contact een alternatieve-sleuteldefinitie heeft die de eigenschappen firstname en emailaddress1 bevat, kunt u de contactpersoon ophalen met een query met gegevens die zijn opgegeven voor deze sleutels, zoals hierna weergegeven.

GET cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

Telkens wanneer u een entiteit uniek moet identificeren ten behoeve van ophalen, bijwerken of verwijderen, kunt u gebruik maken van de alternatieve sleutels die voor de entiteit zijn geconfigureerd. Standaard zijn geen alternatieve sleutels voor entiteiten geconfigureerd. Alternatieve sleutels zijn alleen beschikbaar als de organisatie deze toevoegt.

De waarde van een enkele eigenschap ophalen

Als u voor een entiteit alleen maar de waarde van een enkele eigenschap wilt ophalen, kunt u de naam van de eigenschap toevoegen aan de URI voor de entiteit, zodat alleen de waarde van die eigenschap wordt geretourneerd. Dit is een best practice voor prestaties, omdat minder gegevens in de respons moeten worden geretourneerd.

In dit voorbeeld wordt alleen de waarde van de eigenschap Naam geretourneerd voor een entiteit van het type Account.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Waarden van navigatie-eigenschappen ophalen

Net zoals u afzonderlijke eigenschapswaarden kunt ophalen, kunt u de waarden van navigatie-eigenschappen (opzoekvelden) ophalen door de naam van de navigatie-eigenschap correct toe te voegen aan de URI die verwijst naar een individuele entiteit.

In het volgende voorbeeld wordt de volledige naam van de primaire contactpersoon van een account geretourneerd door middel van de single-valued navigatie-eigenschap primarycontactid.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context": "cc_WebAPI_ServiceURI/$metadata#contacts(fullname)/$entity",
"@odata.etag": "W/\"500128\"",
"fullname": "Rene Valdes (sample)",
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
}

Voor collection-valued navigatie-eigenschappen hebt u de optie om te verzoeken dat alleen verwijzingen naar de gerelateerde entiteiten of slechts het aantal van de gerelateerde entiteiten worden geretourneerd.

In het volgende voorbeeld worden alleen verwijzigingen geretourneerd naar taken die gerelateerd zijn aan een bepaalde account, door /$ref aan de aanvraag toe te voegen.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context": "cc_WebAPI_ServiceURI/$metadata#Collection($ref)",
"value": [
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
},
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)"
}
]
}

In het volgende voorbeeld wordt het aantal taken geretourneerd dat is gerelateerd aan een bepaald account, door middel van de collection-valued navigatie-eigenschap Account_Tasks waaraan /$count is toegevoegd.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons
```
ï»¿2
```

Notitie

De geretourneerde waarde bevat de UTF-8 bytevolgordemarkering (BOM) (ï»¿) die aangeeft dat dit een UTF-8-document is.

Gerelateerde entiteiten ophalen voor een entiteit door navigatie-eigenschappen uit te vouwen

Gebruik de systeemqueryoptie $expand om te bepalen welke gegevens van gerelateerde entiteiten worden geretourneerd. Er zijn twee typen navigatie-eigenschappen:

Single-valued navigatie-eigenschappen corresponderen met opzoekkenmerken die veel-op-een-relaties ondersteunen en waarmee verwijzingen naar andere entiteiten kunnen worden ingesteld.
Collection-valued navigatie-eigenschappen corresponderen met een-op-veel-relaties of veel-op-veel-relaties.

Als u alleen de naam van de navigatie-eigenschap opneemt, ontvangt u alle eigenschappen van gerelateerde records. U kunt het aantal geretourneerde eigenschappen voor de gerelateerde records beperken door tussen haakjes de systeemqueryoptie $select toe te voegen achter de naam van de navigatie-eigenschap. Dit kunt u doen bij zowel single-valued als ook collection-valued navigatie-eigenschappen.

Notitie

Als u gerelateerde entiteiten wilt ophalen voor entiteitsets, raadpleegt u Gerelateerde entiteiten ophalen door navigatie-eigenschappen uit te breiden.

Gerelateerde entiteiten ophalen voor een entiteitsexemplaar door single-valued navigatie-eigenschappen uit te vouwen: In het volgende voorbeeld ziet u hoe u de contactpersoon voor een accountentiteit kunt ophalen. Voor de gerelateerde contactpersoonrecord worden alleen de contactid en de fullname opgehaald.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid($select=contactid,fullname) HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"primarycontactid":{
"@odata.etag":"W/\"550626\"",
"contactid":"c59648c3-68f7-e511-80d3-00155db53318",
"fullname":"Nancy Anderson (sample)"
}
}

In plaats van dat de gerelateerde entiteiten voor entiteitsexemplaren worden geretourneerd, kunt u ook verwijzingen (koppelingen) naar de gerelateerde entiteit laten retourneren door de single-valued navigatie-eigenschap uit te vouwen met de optie $ref. In het volgende voorbeeld worden koppelingen naar contactpersoonrecord voor de accountentiteit geretourneerd.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid)/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",
"primarycontactid":{
"@odata.id":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
}
}

Gerelateerde entiteiten ophalen voor een entiteitsexemplaar door collection-valued navigatie-eigenschappen uit te vouwen: In het volgende voorbeeld ziet u hoe u alle taken kunt ophalen die zijn toegewezen aan een accountrecord.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
"@odata.etag":"W/\"514069\"","name":"Sample Child Account 1","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

Notitie

Als u op collection-valued navigatieparameters uitvouwt om gerelateerde entiteiten op te halen voor entiteitsets, wordt in plaats daarvan een eigenschap @odata.nextLink voor de gerelateerde entiteiten geretourneerd. U moet waarde van de eigenschap @odata.nextLink gebruiken in een nieuwe GET-aanvraag om de gewenste gegevens te laten retourneren.Meer informatie:Gerelateerde entiteiten ophalen door navigatie-eigenschappen uit te breiden

Gerelateerde entiteiten voor een entiteitsexemplaar ophalen door zowel single-valued als collection-valued navigatie-eigenschappen uit te vouwen: In het volgende voorbeeld ziet u hoe u gerelateerde entiteiten voor een entiteitsexemplaar kunt uitvouwen door gebruik te maken van zowel single- als collection-valued navigatie-eigenschappen.

Aanvraag

GET cc_WebAPI_ServiceURI/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

Respons

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity","@odata.etag":"W/\"514069\"","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid":{
"@odata.etag":"W/\"514074\"","createdon":"2016-04-06T00:29:04Z",
"name":"Adventure Works (sample)",
"accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
},"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

Notitie

U kunt niet gebruik maken van de padsegmenten /$ref of /$count om uitsluitend de URI voor de gerelateerde entiteit of een telling van het aantal gerelateerde entiteiten te laten retourneren.

Opties om toe te passen op uitgevouwen entiteiten

U kunt bepaalde systeemqueryopties toepassen op de entiteiten die worden geretourneerd voor een collection-valued navigatie-eigenschap. Gebruik een met puntkomma's gescheiden lijst van systeemqueryopties tussen haakjes achter de naam van de collection-valued navigatie-eigenschap. U kunt $select, $filter, $orderby en $top gebruiken.

In het volgende voorbeeld worden de resultaten van taakentiteiten die gerelateerd zijn aan een account gefilterd op de resultaten met een subject die eindigt op "1".

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

In het volgende voorbeeld wordt opgegeven dat de gerelateerde taken moeten worden geretourneerd in oplopende volgorde, op basis van de eigenschap createdon.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

In het volgende voorbeeld wordt alleen de eerste gerelateerde taak geretourneerd.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

Notitie

Dit is een subset van de systeemqueryopties die zijn beschreven in de sectie "11.2.4.2.1 Expand Options" in het document OData Version 4.0 Part 1: Protocol Plus Errata 02 De opties $skip, $count, $search, $expand en $levels worden niet ondersteund voor de web-API.

Detecteren of een entiteit is gewijzigd nadat deze is opgehaald

Het is een best practice voor prestaties om alleen de gegevens op te vragen die u nodig hebt. Als u eerder een entiteitsrecord hebt opgehaald, kunt u de ETAG gekoppeld aan een eerder opgehaalde record gebruiken om voorwaardelijke ophaalbewerkingen uit te voeren op die record. Zie Voorwaardelijk ophalen voor meer informatie.

Opgemaakte waarden ophalen

Het opvragen van opgemaakte waarden voor het ophalen van individuele records voert u uit op dezelfde manier als wanneer u entiteitsets opvraagt.Meer informatie:Opgemaakte waarden ophalen.

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
Entiteiten bijwerken en verwijderen 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

Delen via

Een entiteit ophalen met de web-API

In dit onderwerp

Eenvoudig voorbeeld voor ophalen

Specifieke eigenschappen ophalen

Ophalen met behulp van een alternatieve sleutel

De waarde van een enkele eigenschap ophalen

Waarden van navigatie-eigenschappen ophalen

Gerelateerde entiteiten ophalen voor een entiteit door navigatie-eigenschappen uit te vouwen

Opties om toe te passen op uitgevouwen entiteiten

Detecteren of een entiteit is gewijzigd nadat deze is opgehaald

Opgemaakte waarden ophalen

Zie ook

Aanvullende resources