Query di dati tramite l'API Web

  • Articolo

 

Data di pubblicazione: gennaio 2017

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

Per recuperare i dati per un set di entità, utilizza una richiesta GET. Nel recupero dei dati, puoi applicare le opzioni di query per impostare i criteri per i dati desiderati e le proprietà delle entità che devono essere restituite.

In questo argomento

Esempio query di base

Limita il numero di entità restituite

Specifica il numero di entità da restituire in una pagina

Applicare le opzioni query di sistema

Proprietà specifiche della richiesta

Filtrare i risultati

Ordinare i risultati

Usare gli alias di parametro con le opzioni di query di sistema

Limitare i risultati

Recuperare un conteggio di entità

Includere valori formattati

Recuperare i dati sulle proprietà di ricerca

Filtro dei record in base alle proprietà di navigazione a valore singolo

Recupero entità correlate espandendo le proprietà di navigazione

Esempio query di base

In questo esempio si esegue la query del set di entità accounts e si utilizzano le opzioni di query di sistema $top e $select per restituire la proprietà name dei primi tre account:

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Response

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

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

Limita il numero di entità restituite

Se non specifichi dimensioni di pagina inferiori, verrà restituito un massimo di 5000 entità per ogni richiesta. Se esistono più entità corrispondenti ai criteri del filtro di query, verrà restituita la proprietà @odata.nextLink con i risultati. Utilizza il valore della proprietà @odata.nextLink con una nuova richiesta GET per tornare alla pagina successiva di dati.

Nota

Le query delle entità di modello non sono limitate o sottoposte al paging.Ulteriori informazioni:Query sui metadati tramite la Web API

Specifica il numero di entità da restituire in una pagina

Utilizza il valore di preferenza odata.maxpagesize per richiedere il numero di entità restituite nella risposta.

Nota

Non puoi usare un valore di preferenza odata.maxpagesize maggiore di 5000.

L'esempio seguente eseguire la query del set di entità accounts e restituisce la proprietà name per i primi tre account.

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Risposta

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

Utilizza il valore della proprietà @odata.nextLink per richiedere il set di record successivo. Non modificare né aggiungere opzioni aggiuntive di query di sistema al valore. Per ogni richiesta successiva di pagine aggiuntive, devi utilizzare lo stesso valore di preferenza di odata.maxpagesize utilizzato nella richiesta originale. Inoltre, memorizza nella cache i risultati restituiti o il valore della proprietà @odata.nextLink in modo da poter restituire le pagine in precedenza recuperate.

Nota

Il valore della proprietà @odata.nextLink è URI codificato. Se l'URI codifica il valore prima di inviarlo, le informazioni dei cookie XML nell'URL causeranno un errore.

Applicare le opzioni query di sistema

Tutte le opzioni query di sistema accodate all'URL per il set di entità vengono aggiunte tramite la sintassi delle stringhe di query. La prima viene aggiunta automaticamente dopo [?] e le opzioni di query successive sono separate tramite [&]. Tutte le opzioni di query rispettano la distinzione tra maiuscole e minuscole come illustrato nell'esempio seguente.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

Proprietà specifiche della richiesta

Utilizza l'opzione di query di sistema $select per limitare le proprietà restituite come illustrato nell'esempio seguente.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

Importante

Questa è una procedura consigliata per le prestazioni. Se le proprietà non sono specificate utilizzando $select, vengono restituite tutte le proprietà.

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.

Filtrare i risultati

Usa l'opzione di query di sistema $filter per impostare i criteri per le entità da restituire.

Operatori standard del filtro

L'API Web supporta gli operatori di filtro OData standard elencati nella tabella seguente.

Operatore

Descrizione

Esempio

Operatori di confronto

eq

Uguale a

$filter=revenue eq 100000

ne

Diverso

$filter=revenue ne 100000

gt

Maggiore di

$filter=revenue gt 100000

ge

Maggiore di o uguale a

$filter=revenue ge 100000

lt

Minore di

$filter=revenue lt 100000

le

Minore di o uguale a

$filter=revenue le 100000

Operatori logici

and

Logica e

$filter=revenue lt 100000 and revenue gt 2000

or

Logica o

$filter=contains(name,'(sample)') or contains(name,'test')

not

Negazione logica

$filter=not contains(name,'sample')

Operatori di raggruppamento

( )

Raggruppamento precedente

(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Nota

Questo è un sottoinsieme di Opzioni di filtro incorporate 11.2.5.1.1. Gli operatori aritmetici e l'operatore ha del confronto non sono supportati nell'API Web.

Funzionalità di query standard

L'API Web supporta le funzionalità di query di stringa OData standard.

Funzione

Esempio

contains

$filter=contains(name,'(sample)')

endswith

$filter=endswith(name,'Inc.')

startswith

$filter=startswith(name,'a')

Nota

Questo è un sottoinsieme di Funzionalità di query incorporate 11.2.5.1.2.Date, Math, Type, Geo e altre funzioni di stringa non sono supportate nell'API Web.

Funzioni di query dell'API Web di Microsoft Dynamics 365

Microsoft Dynamics 365 fornisce una serie di funzioni speciali che accettano parametri, restituiscono valori booleani e possono essere utilizzati come criteri di filtro in una query. Per un elenco di queste funzioni, vedi Web API Query Function Reference. Viene di seguito è riportato un esempio della ricerca Between Function per gli account con un numero di utenti compreso tra 5 e 2000.

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Ulteriori informazioni:Comporre una query con le funzioni.

Ordinare i risultati

Specifica l'ordine in cui gli elementi vengono restituiti tramite l'opzione di query di sistema $orderby. Utilizza il suffisso asc o desc per specificare l'ordine crescente o decrescente rispettivamente. L'impostazione predefinita è crescente, se il suffisso non è applicato. Nell'esempio seguente viene illustrato il recuperano delle proprietà di nome e ricavi degli account in ordine crescente per ricavi e decrescente per nome.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Usare gli alias di parametro con le opzioni di query di sistema

Puoi usare gli alias di parametro per le opzioni di query di sistema $filter e $orderby. Gli alias di parametro consente di usare lo stesso valore più volte in una richiesta. Se l'alias non è assegnato a un valore, si presuppone essere null.

Senza alias di parametro

 
GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Con alias di parametro

 
GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=@p1 asc,@p2 desc&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Puoi anche possibile usare gli alias di parametro con le funzioni.Ulteriori informazioni:Utilizzare le funzioni API Web

Limitare i risultati

Puoi limitare il numero di risultati restituiti utilizzando l'opzione di query di sistema $top. Il seguente esempio restituisce solo le prime tre entità account.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

Nota

La limitazione dei risultati tramite utilizzando $top impedisce l'applicazione della preferenza odata.maxpagesize. Puoi utilizzare la preferenza odata.maxpagesize o $top, ma non entrambe contemporaneamente. Per ulteriori informazioni su odata.maxpagesize, vedere Specifica il numero di entità da restituire in una pagina.

Non devi utilizzare $top con $count.

Recuperare un conteggio di entità

Usa l'opzione di query di sistema $count con il valore true per includere un conteggio delle entità corrispondente ai criteri di filtro fino a 5000.

Nota

Il valore del conteggio non rappresenta il numero totale delle entità del sistema. È limitato dal numero massimo di entità che puoi restituire.Ulteriori informazioni:Limita il numero di entità restituite

La proprietà @odata.count** della risposta conterrà il numero di entità corrispondenti ai criteri di filtro indipendentemente dalla limitazione di preferenza **odata.maxpagesize.

Nota

Non devi utilizzare $top con $count.

Nell'esempio seguente viene illustrato che sono disponibili dieci account corrispondenti ai criteri del nome contenente "esempio", ma solo i primi tre account vengono restituiti.

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Risposta

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

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Se non desideri che vengano restituiti dati ad eccezione del conteggio, puoi applicare $count in qualsiasi raccolta per ottenere solo il valore.

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Risposta

    HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

10

Includere valori formattati

Quando vuoi ricevere valori formattati per le proprietà con i risultati, utilizza la preferenza odata.include-annotations con il valore OData.Community.Display.V1.FormattedValue. La risposta prevede questi valori con le proprietà corrispondenti alla seguente convenzione di denominazione:

<propertyname>@OData.Community.Display.V1.FormattedValue

L'esempio seguente eseguire una query del set di entità account e restituisce il primo record, incluse le proprietà che supportano i valori formattati.

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

  • Risposta

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

Recuperare i dati sulle proprietà di ricerca

Se la query include le proprietà di ricerca puoi richiedere le annotazioni che forniscono informazioni aggiuntive sui dati delle proprietà. Per la maggior parte dei casi, gli stessi dati possono essere derivati con la conoscenza delle proprietà di navigazione a un solo valore e dei dati inclusi nelle entità correlate. Tuttavia, nei casi in cui la proprietà rappresenta un attributo di ricerca che può fare riferimento a più di un tipo di entità, tali informazioni possono indicarti il tipo di entità a cui la proprietà di ricerca fa riferimento.Ulteriori informazioni:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

Esistono due tipi aggiuntivi di annotazioni disponibili per queste proprietà,

Annotazione

Descrizione

Microsoft.Dynamics.CRM.associatednavigationproperty

Il nome della proprietà di navigazione a valore singolo che include il riferimento all'entità.

Microsoft.Dynamics.CRM.lookuplogicalname

Il nome logico dell'entità a cui la ricerca fa riferimento.

Queste proprietà possono anche includere i valori formattati come descritto in Includere valori formattati. Analogamente ai valori formattati, puoi restituire le altre annotazioni utilizzando la preferenza odata.include-annotations impostata sul tipo specifico di annotazione desiderata oppure impostare il valore su "*" e restituire tutti e tre i tipi. Il seguente esempio mostra la richiesta e la risposta per recuperare le informazioni sulla proprietà di ricerca _customerid_value dell'entità incident con le annotazioni incluse.

  • Richiesta

    GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

  • Risposta

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

Filtro dei record in base alle proprietà di navigazione a valore singolo

Le proprietà di navigazione consentono di accedere ai dati relativi all'entità corrente. 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à.Ulteriori informazioni:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

Puoi filtrare i record del set di entità in base ai valori della proprietà di navigazione a valore singolo. Ad esempio, puoi recuperare gli account figlio per l'account specificato. Puoi utilizzare solo il valore dell'attributo principale dell'entità a cui fa riferimento la proprietà di navigazione a valore singolo per filtrare i record. Ad esempio:

  • Recupera tutti gli account corrispondenti per un ID contatto specificato

    • Richiesta

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 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)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

  • Recupera gli account child per l'ID account specificato.

    • Richiesta

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

Recupero entità correlate espandendo le proprietà di navigazione

Utilizza l'opzione query di sistema $expand nelle proprietà di navigazione 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 solo 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 un'istanza di entità, vedi Recupero entità correlate per un'entità 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 tutti i record di account. Per i record del contatto correlati, recuperiamo solo il contactid e il nome completo.

    • Richiesta

      GET cc_WebAPI_ServiceURI/accounts?$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))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

    Invece di restituire le entità correlate per i set 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 ai record di contatto per tutti gli account.

    • Richiesta

      GET cc_WebAPI_ServiceURI/accounts?$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)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

    • Recupera le entità correlate espandendo le proprietà di navigazione con valore di raccolta: se espandi i parametri di navigazione con valore di raccolta per recuperare le entità correlate per i set di entità, la proprietà @odata.nextLink sarà restituita per le entità correlate. Utilizza il valore della proprietà @odata.nextLink con una nuova richiesta GET per tornare ai dati richiesti.

      Nel seguente esempio vengono recuperate le attività assegnate ai 5 record di account principali.

      • Richiesta

        GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=Account_Tasks($select%20=%20subject,%20scheduledstart) 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,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

  • Recupera le entità correlate per un'istanza di entità espandendo le proprietà di navigazione a valore singolo e con valore di raccolta: l'esempio seguente illustra come espandere le entità correlate per i set di entità sia con le proprietà di navigazione a valore singolo che con valore di raccolta. Come spiegato in precedenza, se si espandono le proprietà di navigazione con valore di raccolta per recuperare le entità correlate per i 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.

    In questo esempio, recupereremo il contatto e le attività ai 3 account principali.

    • Richiesta

      GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  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,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

Vedere anche

Esempio di dati di query API Web (C#)
Esempio di dati di query API Web (JavaScript lato client)
Eseguire operazioni tramite l'API Web
Comporre richieste HTTP e gestire gli errori
Creare un'entità utilizzando l'API Web
Recupera 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

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright