Hente et objekt ved hjælp af web-API'et

Artikel
10/31/2017

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Brug en GET-anmodning til at hente data for et objekt, der er angivet som ressource med et entydigt id. Når du henter et objekt, du kan også anmode om specifikke egenskaber og udvide navigationsegenskaber for at returnere egenskaber fra relaterede objekter.

Bemærk

Du kan få oplysninger om hentning af metadata under Forespørg på metadata ved hjælp af Web-API'en.

Dette emne indeholder

Grundlæggende hetningseksempel

Hente bestemte egenskaber

Hente ved hjælp af en alternativ nøgle

Hente en enkelt egenskabsværdi

Hente egenskabsværdier for navigation

Hente relaterede objekter for et objekt ved at udvide navigationsegenskaber

Indstillingerne, der skal bruges til at udvidede objekter

Find ud af, om et objekt er blevet ændret, siden det blev hentet

Hente formaterede værdier

Grundlæggende hetningseksempel

I dette eksempel returneres data for en firmaobjektforekomst med primære nøgleværdi lig med 00000000-0000-0000-0000-000000000001.

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

Hvis du vil hente mere end ét objekt ad gangen, kan du se Grundlæggende forespørgselseksempel i emnet Forespørg på data ved hjælp af Web-API'en.

Forsigtigt

Ovenstående eksempel returnerer alle egenskaberne for firmapost, som er mod de bedste fremgangsmåder for ydeevne ved hentning af data. Dette eksempel var blot for at vise, hvordan du kan foretage en grundlæggende hentning af et objektforekomst i Dynamics 365. Da alle egenskaberne blev returneret, har vi ikke medtaget svaroplysningerne for anmodningen i dette eksempel.

Som en bedste fremgangsmåde for ydeevne kan du altid bruge $select-systemforespørgselsindstillingen for at begrænse de egenskaber, der returneres, når der hentes data. Se følgende afsnit Hente bestemte egenskaber for at få oplysninger om dette.

Hente bestemte egenskaber

Brug $select-systemforespørgselsindstillingen for at begrænse de egenskaber, der returneres, ved at medtage en kommasepareret liste over egenskabsnavne. Dette er en vigtig bedste fremgangsmåde for ydeevne. Hvis egenskaberne ikke angives ved hjælp af $select, returneres alle egenskaber.

Følgende eksempel henter name- og revenue-egenskaberne for firmaobjektet med den primære nøgleværdi lig med 00000000-0000-0000-0000-000000000001

Anmodning

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

Svar

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

Du kan forvente, at der automatisk returneres flere skrivebeskyttede egenskaber, når du anmoder om visse typer af egenskaber.

Hvis du anmoder om en pengeværdi, returneres _transactioncurrencyid_value-opslagsegenskaben. Denne egenskab indeholder kun GUID-værdien for transaktionsvalutaen,, så du kan bruge denne værdi til at hente oplysninger om valutaen ved hjælp af transactioncurrency EntityType. Ved at anmode om anmærkninger kan du også få ekstra data i den samme anmodning.Flere oplysninger:Hente data om egenskaber for opslag

Hvis du anmoder om en egenskab, der er en del af en sammensat attribut for en adresse, får du også den sammensatte egenskab. Hvis din forespørgsel f.eks. anmoder om egenskaben address1_line1 for en kontakt, returneres address1_composite-egenskaben også.Flere oplysninger:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

Hente ved hjælp af en alternativ nøgle

Hvis et objekt har en alternativ nøgle, der er defineret, kan du også bruge den alternative nøgle til at hente objektet i stedet for det entydige id for objektet. Hvis Contact-objektet f.eks. har en definition af en alternativ nøgle, der omfatter både firstname- og emailaddress1-egenskaberne, kan du hente kontakten ved hjælp af en forespørgsel med data, der er angivet for disse nøgler, sådan som det er vist her.

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

Hver gang du har brug for entydigt at identificere et objekt, der skal hentes, opdateres eller slettes, kan du bruge alternative nøgler, der er konfigureret for objektet. Som standard er der konfigureret alternative nøgler for objekter. Alternative nøgler vil kun være tilgængelige, hvis organisationen tilføjer dem.

Hente en enkelt egenskabsværdi

Når du kun har brug for at hente værdien af en enkelt egenskab for et objekt, kan du føje navnet på egenskaben til URI for et objekt, så det kun er værdien for den egenskab, der returneres. Dette er en bedste fremgangsmåde for ydeevne, fordi færre data skal returneres i svaret.

I dette eksempel returneres kun værdien af navneegenskaben for et firmaobjekt.

Anmodning

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

Svar

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

På samme måde som du kan hente individuelle egenskabsværdier, har du også adgang til værdierne for navigationsegenskaberne (opslagsfelter) ved at føje navnet på navigationsegenskaben til URI, der refererer til et individuelt objekt.

Følgende eksempel returnerer det fulde navn på den primære kontakt for en konto ved hjælp af primarycontactid-navigationsegenskaben med enkeltværdi.

Anmodning

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

Svar

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

Når det gælder navigationsegenskaber for gruppeværdi, har du mulighed for at anmode om, at der returneres referencer til de relaterede objekter eller blot et antal af de relaterede objekter.

Følgende eksempel returnerer kun referencer til opgaver, der er relateret til en bestemt konto, ved at tilføje /$ref til anmodningen.

Anmodning

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

Svar

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

Følgende eksempel returnerer antallet af opgaver, der er relateret til en bestemt konto, ved hjælp af Account_Tasks-navigationsegenskaben med gruppeværdi, hvor /$count tilføjes.

Anmodning

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

Svar
```
ï»¿2
```

Bemærk

Den returnerede værdi omfatter UTF-8 BOM-tegn (byte order mark) (ï»¿), der tilkendegiver, at dette er et UTF-8-dokument.

Hente relaterede objekter for et objekt ved at udvide navigationsegenskaber

Brug $expand-systemforespørgselsindstillingen til at styre, hvilke data der returneres fra de relaterede objekter. Der findes to typer navigationsegenskaber:

Navigationsegenskaber med enkeltværdisvarer til opslagsattributter, der understøtter mange-til-en-relationer og gør det muligt at indstille en reference til et andet objekt.
Navigationsegenskaberne gruppeværdi svarer til en-til-mange- eller mange-til-mange-relationer.

Hvis du blot inkluderer navnet på navigationsegenskaben, modtager du alle egenskaberne for relaterede poster. Du kan begrænse de egenskaber, der er returneret til relaterede poster, ved hjælp af $select-systemforespørgselsindstillingen i parentes efter navigationsegenskabsnavnet. Brug denne til både navigationsegenskaber med enkeltværdi og gruppeværdi.

Bemærk

Hvis du vil hente relaterede objekter for objektsæt, kan du se Hente relaterede objekter ved at udvide navigationsegenskaber.

Hente relaterede objekter for en objektforekomst ved at udvide navigationsegenskaber med enkeltværdi: Følgende eksempel demonstrerer, hvordan du henter kontakten for et firmaobjekt. Vi henter kun contactid og fullname for den relaterede kontaktpost.

Anmodning

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

Svar

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

I stedet for at returnere de relaterede objekter for objektforekomster kan du også returnere referencer (links) til de tilknyttede objekter ved at udvide navigatoinsegenskaben med enkeltværdi med indstillingen $ref. Følgende eksempel returnerer hyperlinks til kontaktposten for firmaobjektet.

Anmodning

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

Svar

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

Hente relaterede objekter for en objektforekomst ved at udvide navigationsegenskaber med gruppeværdi: Følgende eksempel demonstrerer, hvordan du kan hente alle opgaver, der er tildelt til en firmapost.

Anmodning

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

Svar

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

Bemærk

Hvis du udvider navigationsparametre med gruppeværdi til at hente relaterede objekter for objektsæt, returneres i stedet en @odata.nextLink-egenskab for de relaterede objekter. Du skal bruge værdien af @odata.nextLink-egenskaben med en ny GET-anmodning for at returnere de påkrævede data.Flere oplysninger:Hente relaterede objekter ved at udvide navigationsegenskaber

Hente relaterede objekter for en objektforekomst ved at udvide navigationsegenskaber med både enkeltværdi og gruppeværdi: Følgende eksempel viser, hvordan du kan udvide relaterede objekter for en objektforekomst ved hjælp af navigationsegenskaber for både enkeltværdi og gruppeværdi.

Anmodning

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

Svar

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

Bemærk

Du kan ikke bruge /$ref- eller /$count-stisegmenter for kun at returnere URI'en for det relaterede objekt eller et antal relaterede objekter

Indstillingerne, der skal bruges til at udvidede objekter

Du kan anvende visse systemforespørgselsindstillinger på de objekter, der er returneret for navigationsegenskab med gruppeværdi. Brug en semikolonsepareret liste over systemforespørgselsindstillinger i parentes efter navnet på navigationsegenskaben med gruppeværdi. Du kan bruge $select, $filter, $orderby og $top.

Det følgende eksempel filtrerer resultaterne af opgaveobjekter, der er relateret til et firma, til dem, der har et subject , der slutter med "1".

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

I følgende eksempel angiver, at relaterede opgaver skal returneres i stigende rækkefølge baseret på egenskaben createdon.

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

Følgende eksempel returnerer kun den første relaterede opgave.

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

Bemærk

Dette er et undersæt af de systemforespørgselsindstillinger, der er beskrevet i afsnittet "11.2.4.2.1 Expand Options" i OData Version 4.0 Part 1: Protocol Plus Errata 02. Indstillingerne for $skip, $count, $search, $expand og $levels understøttes ikke af web API'et.

Find ud af, om et objekt er blevet ændret, siden det blev hentet

Bedste fremgangsmåde for ydeevne er kun at anmode om de data, du har brug for. Hvis du tidligere har hentet en objektpost, kan du bruge det ETag, der er knyttet til en tidligere hentet post, til at udføre betingede hentninger for denne post. Du kan finde flere oplysninger under Betingede hentninger.

Hente formaterede værdier

Anmodning om formaterede værdier for hentning af individuelle poster gøres på samme måde, som når der forespørges om objektsæt.Flere oplysninger:Medtage formaterede værdier.

Se også

Eksempel på Web API Basic-operationer (C#)
Eksempel på Web API Basic operationer (JavaScript på klientsiden)
Udføre operationer ved hjælp af web-API
Skrive HTTP-anmodninger og håndtere fejl
Forespørg på data ved hjælp af Web-API'en
Oprette et objekt ved hjælp af Web-API
Opdatere og slette objekter ved hjælp af web-API'et
Tilknytte og fjerne tilknytningen af objekter ved hjælp af web-API'et
Bruge Web-API-funktioner
Brug Web API-handlinger
Udføre batchhandlinger ved hjælp af Web-API
Efterligne en anden bruger ved hjælp af Web-API'en
Udfør betingede operationer ved hjælp af web-API

Microsoft Dynamics 365

Del via

Hente et objekt ved hjælp af web-API'et

Dette emne indeholder

Grundlæggende hetningseksempel

Hente bestemte egenskaber

Hente ved hjælp af en alternativ nøgle

Hente en enkelt egenskabsværdi

Hente egenskabsværdier for navigation

Hente relaterede objekter for et objekt ved at udvide navigationsegenskaber

Indstillingerne, der skal bruges til at udvidede objekter

Find ud af, om et objekt er blevet ændret, siden det blev hentet

Hente formaterede værdier

Se også

Yderligere ressourcer