Recupera un'entità utilizzando l'API Web

Articolo
10/31/2017

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Utilizzare una richiesta GET per recuperare i dati per un'entità specificata come la risorsa con un identificatore univoco. Quando recuperi un'entità puoi inoltre richiedere proprietà specifiche ed espandere le proprietà di navigazione per ritornare alle proprietà delle entità correlate.

Nota

Per ulteriori informazioni sul recupero dei metadati di entità, vedi Query sui metadati tramite la Web API.

In questo argomento

Esempio Recupero di base

Recupera proprietà specifiche

Recuperare utilizzando una chiave alternativa

Recupera un unico valore proprietà

Richiama i valori della proprietà di navigazione

Recupero entità correlate per un'entità espandendo le proprietà di navigazione

Opzioni da applicare alle entità espanse

Rileva se un'entità è cambiata da quando è stata recuperata

Recupera valori formattati

Esempio Recupero di base

In questo esempio vengono recuperati i dati per un'istanza di entità account con il valore della chiave primaria uguale a 00000000-0000-0000-0000-000000000001.

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

Per recuperare più entità alla volta, vedi Esempio query di base nell'argomento Query di dati tramite l'API Web.

Attenzione

Nell'esempio precedente verranno restituite le proprietà per il record di account, rispetto alle procedure consigliate delle prestazioni per il recupero dei dati. In questo esempio viene semplicemente illustrato come eseguire un recupero di base di un'istanza di entità in Dynamics 365. Poiché tutte le proprietà sono state restituite, non abbiamo incluso le informazioni di risposta alla richiesta in questo esempio.

Come procedura consigliata per le prestazioni, devi utilizzare sempre l'opzione della query di sistema $select per limitare le proprietà restituite durante il recupero di dati. Per ulteriori informazioni, vedi la sezione seguente, Recupera le proprietà specifiche.

Recupera proprietà specifiche

Utilizza l'opzione query di sistema $select per limitare le proprietà restituite includendo un elenco delimitato da virgole dei nomi di proprietà. Questa è un'importante procedura consigliata per le prestazioni. Se le proprietà non sono specificate utilizzando $select, vengono restituite tutte le proprietà.

Nel seguente esempio vengono recuperate le proprietà name e revenue per l'entità account con il valore della chiave primaria uguale a 00000000-0000-0000-0000-000000000001

Richiesta

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

Risposta

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

Quando sono necessari alcuni tipi di proprietà puoi prevedere che vengano restituite automaticamente le proprietà di sola lettura aggiuntive.

Se è necessario un valore in denaro, la proprietà di ricerca _transactioncurrencyid_value sarà restituita. La proprietà contiene solo il valore GUID della valuta di transazione pertanto puoi utilizzare questo valore per recuperare le informazioni sulla valuta tramite transactioncurrency EntityType. In alternativa, richiedendo le annotazioni puoi anche ottenere dati aggiuntivi nella stessa richiesta.Ulteriori informazioni:Recuperare i dati sulle proprietà di ricerca

Se richiedi una proprietà che fa parte di un attributo composto per un indirizzo, analogamente otterrai la proprietà composita. Ad esempio, se la query richiede la proprietà address1_line1 per un contatto, viene restituita anche la proprietà address1_composite.Ulteriori informazioni:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

Recuperare utilizzando una chiave alternativa

Se un'entità ha una chiave alternativa definita, puoi inoltre utilizzare la chiave alternativa per recuperare l'entità anziché l'identificatore univoco per l'entità. Ad esempio, se l'entità Contact ha una definizione di chiave alternativa che include sia le proprietà firstname che emailaddress1, puoi recuperare il contatto con una query con i dati forniti per tali chiavi come illustrato di seguito.

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

Ogni volta che devi identificare in modo univoco un'entità da richiamare, aggiornare o eliminare, puoi utilizzare le chiavi alternative configurate per l'entità. Per impostazione predefinita, non ci sono chiavi alternative configurate per le entità. Le chiavi alternative saranno disponibili solo se l'organizzazione le aggiunge.

Recupera un unico valore proprietà

Quando è necessario recuperare il valore di una proprietà singola per un'entità, puoi aggiungere il nome della proprietà all'URI affinché un'entità restituisca solo il valore per tale proprietà. Questa è una procedura consigliata delle prestazioni perché in risposta deve essere restituito un minor numero di dati.

Questo esempio restituisce solo il valore della proprietà del nome per un'entità account.

Richiesta

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

Risposta

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

Richiama i valori della proprietà di navigazione

Allo stesso modo puoi recuperare i valori di proprietà singoli, puoi inoltre accedere ai valori delle proprietà di navigazione (campi di tipo lookup) associando il nome della proprietà di navigazione all'URI facendo riferimento a un'entità singola.

Nell'esempio seguente viene restituito il nome completo del contatto primario di un account utilizzando la proprietà di navigazione a valore singolo primarycontactid.

Richiesta

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

Risposta

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

Per le proprietà di navigazione con i valori della raccolta hai la possibilità di richiedere di restituire solo i riferimenti alle entità correlate o solo un numero di entità correlate.

Nel seguente esempio verranno restituiti i riferimenti alle attività correlate a un account specifico aggiungendo /$ref alla richiesta.

Richiesta

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

Risposta

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

Nell'esempio seguente viene restituito il numero di attività correlate a un account specifico utilizzando la proprietà di navigazione con valori della raccolta Account_Tasks con /$count associato.

Richiesta

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

Risposta
```
ï»¿2
```

Nota

Il valore restituito include caratteri BOM UTF-8 (ï»¿) che rappresentano che si tratta di un documento UTF-8.

Recupero entità correlate per un'entità espandendo le proprietà di navigazione

Utilizza l'opzione query di sistema $expand per controllare quali dati vengono restituiti dalle entità correlate. Sono disponibili due tipi di proprietà di navigazione:

Le proprietà di navigazione a valore singolo corrispondono agli attributi di tipo lookup che supportano relazioni molti-a.-uno e consentono l'impostazione di un riferimento a un'altra entità.
Le proprietà di navigazione con valori della raccolta corrispondono a relazioni uno-a-molti o molti-a-molti.

Se includi semplicemente il nome della proprietà di navigazione, riceverai tutte le proprietà dei record correlati. Puoi limitare le proprietà restituite per i record correlati utilizzando l'opzione della query di sistema $select tra parentesi dopo il nome della proprietà di navigazione. Utilizza questa opzione per le proprietà di navigazione a valore singolo e con i valori della raccolta.

Nota

Per recuperare le entità correlate per i set di entità, vedi Recupero entità correlate espandendo le proprietà di navigazione.

Recupera entità correlate per un'istanza di entità espandendo le proprietà di navigazione a valore singolo: nell'esempio seguente viene illustrato come recuperare il contatto per un'entità account. Per il record del contatto correlato, stai solo recuperando contactid e il nome completo.

Richiesta

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

Risposta

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

Invece di restituire le entità correlate per le istanze di entità, puoi inoltre restituire riferimenti (collegamenti) per le entità correlate espandendo la proprietà di navigazione a valore singolo con l'opzione $ref. Nel seguente esempio vengono restituiti collegamenti al record di contatto per l'entità account.

Richiesta

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

Risposta

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

Recupera le entità correlate per un'istanza di entità espandendo le proprietà di navigazione con valori di raccolta: nell'esempio seguente viene illustrato come poter recuperare tutte le attività assegnate a un record di account.

Richiesta

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

Risposta

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

Nota

Se espandi i parametri di navigazione con i valori della raccolta per recuperare le entità correlate per set di entità, verrà restituita la proprietà @odata.nextLink invece delle entità correlate. Utilizza il valore della proprietà @odata.nextLink con una nuova richiesta GET per tornare ai dati richiesti.Ulteriori informazioni:Recupero entità correlate espandendo le proprietà di navigazione

Recupera le entità correlate per un'istanza di entità espandendo le proprietà di navigazione a valore singolo e con i valori della raccolta: l'esempio seguente illustra come espandere le entità correlate per un'istanza di entità sia con le proprietà di navigazione a valore singolo che con i valori della raccolta.

Richiesta

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

Risposta

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

Nota

Non puoi utilizzare i segmenti del percorso /$ref o /$count per restituire solo l'URI per l'entità correlata o un conteggio del numero di entità correlate

Opzioni da applicare alle entità espanse

Puoi applicare alcune opzioni query di sistema alle entità restituite per una proprietà di navigazione con i valori della raccolta. Usa un elenco separato da punti e virgola delle opzioni query di sistema chiuse tra parentesi dopo il nome della proprietà di navigazione con i valori della raccolta. Puoi utilizzare $select, $filter, $orderby e $top.

Nel seguente esempio vengono filtrati i risultati delle entità di attività correlate a un account a quelle con un subject che termina con "1".

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

Nel seguente esempio vengono viene specificato che le attività correlate vengano restituite in ordine discendente in base alla proprietà createdon.

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

Nel seguente esempio viene restituita solo la prima attività correlata.

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

Nota

Si tratta delle opzioni di query di sistema come descritte nella sezione "11.2.4.2.1 Espandi opzioni" di OData Version 4.0 Part 1: Protocol Plus Errata 02. Le opzioni $skip, $count, $search, $expand e $levels non sono supportate per l'API Web.

Rileva se un'entità è cambiata da quando è stata recuperata

La procedura consigliata delle prestazioni dovrebbe richiedere solo i dati necessari. Se in precedenza hai recuperato un record di entità, puoi utilizzare l'ETag associato al record recuperato in precedenza per eseguire recuperi condizionali sul record. Per ulteriori informazioni, vedere Recuperi condizionali.

Recupera valori formattati

La richiesta dei valori formattati per i recuperi dei record singoli viene eseguita come quando si esegue la query dei set di entità.Ulteriori informazioni:Includere valori formattati.

Vedere anche

Esempio di operazioni di base dell'API Web (C#)
Esempio di operazioni di base API Web (JavaScript lato client)
Eseguire operazioni tramite l'API Web
Comporre richieste HTTP e gestire gli errori
Query di dati tramite l'API Web
Creare un'entità utilizzando l'API Web
Aggiorna ed elimina le entità con l'API Web
Associa e annulla associazione entità con l'API Web
Utilizzare le funzioni API Web
Utilizzare le azioni API Web
Eseguire operazioni in batch usando l'API Web
Rappresentare un altro utente usando l'API Web
Eseguire operazioni condizionali tramite l'API Web

Microsoft Dynamics 365

Share via

Recupera un'entità utilizzando l'API Web

In questo argomento

Esempio Recupero di base

Recupera proprietà specifiche

Recuperare utilizzando una chiave alternativa

Recupera un unico valore proprietà

Richiama i valori della proprietà di navigazione

Recupero entità correlate per un'entità espandendo le proprietà di navigazione

Opzioni da applicare alle entità espanse

Rileva se un'entità è cambiata da quando è stata recuperata

Recupera valori formattati

Vedere anche

Risorse aggiuntive