共用方式為

使用 Web API 擷取實體

  • 發行項

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

使用 GET 要求，針對指定為具有唯一識別碼的實體擷取資料。 擷取實體時，您也可以要求特定屬性並展開導覽屬性，以傳回相關實體的屬性。

注意

如需擷取實體中繼資料的詳細資訊，請參閱使用 Web API 查詢中繼資料。

本主題內容

基本擷取範例

擷取特殊屬性

使用其他索引鍵擷取

擷取單一屬性值

擷取導覽屬性值

藉由展開導覽屬性擷取實體的相關實體

適用於展開實體的選項

偵測實體自擷取後是否變更

擷取格式化的值

基本擷取範例

此範例會傳回客戶實體執行個體的資料，其中主索引鍵值等於 00000000-0000-0000-0000-000000000001。

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

若要一次擷取多個實體，請參閱使用 Web API 查詢資料主題中的基本查詢範例。

警告

上述範例會傳回客戶記錄的所有屬性，是依照擷取資料的效能最佳作法。 此範例僅說明如何在 Dynamics 365 中執行實體執行個體的基本擷取。 因為所有屬性都會傳回，所以我們未在此範例中包含要求的回覆資訊。

基於效能最佳作法，您必須一律使用 $select 系統查詢選項，限制擷取資料時傳回的屬性。 如需與此相關的資訊，請參閱下一節擷取特殊屬性。

擷取特殊屬性

使用 $select 系統查詢選項限制傳回的屬性，藉由包括逗點分隔的屬性名稱清單。 這是一項重要的效能最佳作法。 如果未使用 $select 指定屬性，則會傳回所有屬性。

下列範例會擷取客戶實體的 name 和 revenue 屬性，其中主索引鍵值等於 00000000-0000-0000-0000-000000000001

  • 要求

    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

  • 回覆

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

當您要求特定類型的屬性時，可預期會自動傳回額外的唯讀屬性。

如果您要求金額值，_transactioncurrencyid_value 查詢屬性將會傳回。 此屬性只包含交易貨幣的 GUID 值，因此您可以使用此值利用 transactioncurrency EntityType 擷取有關貨幣的資訊。 或者，要求註解也可以在相同要求中取得額外的資料。其他資訊：擷取有關查詢屬性的資料

如果您要求的屬性屬於地址的複合屬性，則也會收到該複合屬性。 例如，如果您的查詢要求連絡人的 address1_line1 屬性，則也會傳回 address1_composite 屬性。其他資訊：5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes。

使用其他索引鍵擷取

若實體定義了其他索引鍵，您也可以使用其他索引鍵擷取實體，而不使用實體的唯一識別碼。 例如，如果 Contact 實體有其他索引鍵定義，當中同時包含 emailaddress1 和 firstname 屬性，您可以使用查詢擷取連絡人，並為這些索引鍵提供資料，如此處所示。

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

只要您需要唯一識別要擷取、更新或刪除的實體，就可以使用為實體設定的其他索引鍵。 根據預設，沒有為實體設定的其他索引鍵。 其他索引鍵只有在組織新增它們時才能使用。

擷取單一屬性值

當您只需要擷取實體的單一屬性的值時，可以附加屬性名稱至實體的 URI，只傳回該屬性的值。 這是效能最佳作法，因為回覆中需要傳回的資料較少。

此範例只會傳回客戶實體的名稱屬性值。

  • 要求

    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

  • 回覆

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

擷取導覽屬性值

透過您擷取個別屬性值的方式，您也可以存取導覽屬性的值 (查詢欄位)，藉由附加導覽屬性的名稱至參考個別實體的 URI。

下列範例會使用 primarycontactid 單一值導覽屬性傳回客戶的主要連絡人的全名。

  • 要求

    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

  • 回覆

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

若是集合值導覽屬性，您可以選擇要求只傳回相關實體的參考，或僅相關實體的計數。

下列範例只會傳回與特定客戶相關的工作參考，藉由新增 /$ref 至要求。

  • 要求

    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

  • 回覆

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

下列範例會與特定客戶相關的工作數，使用 Account_Tasks 集合值導覽屬性並附加 /$count。

  • 要求

    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

  • 回覆

    2

注意

傳回的值包括 UTF-8 位元順序標記 (BOM) 字元 ()，代表這是 UTF-8 文件。

藉由展開導覽屬性擷取實體的相關實體

使用 $expand 系統查詢選項來控制l要從相關實體傳回哪些資料。 導覽屬性有兩種類型：

  • 單一值導覽屬性對應查詢屬性，支援多對一關聯並允許設定另一個實體的參考。

  • 集合值導覽屬性對應至一對多或多對多關聯。

如果您僅包含導覽屬性的名稱，則會收到相關記錄的所有屬性。 您可以限制針對相關記錄傳回的屬性，於導覽屬性名稱後面在括號中使用 $select 系統查詢選項。 針對單一值和集合值導覽屬性使用此方式。

注意

若要擷取實體集的相關實體，請參閱藉由展開導覽屬性擷取相關實體。

  • 藉由展開單一值導覽屬性擷取實體執行個體的相關實體：下列範例示範如何擷取客戶實體的連絡人。 對於相關連絡人記錄，我們只會擷取 contactid 及 fullname。

    • 要求

      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

    • 回覆

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

    如果不要傳回實體執行個體的相關實體，您也可以傳回相關實體的參考 (連結)，藉由 $ref 選項展開單一值導覽屬性。 下列範例會傳回客戶實體的連絡人記錄的連結。

    • 要求

      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

    • 回覆

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

    • 藉由展開集合值導覽屬性擷取實體執行個體的相關實體：下列範例示範如何擷取所有指派至客戶記錄的工作。

      • 要求

        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

      • 回覆

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

      注意

      若要展開集合值導覽參數以擷取實體集的相關實體，@odata.nextLink 屬性將會傳回，而不是相關實體。 您應使用 @odata.nextLink 屬性的值與新的 GET 要求傳回需要的資料。其他資訊：藉由展開導覽屬性擷取相關實體

  • 藉由展開單一值和集合值導覽屬性擷取實體執行個體的相關實體：下列範例示範如何使用單一值和集合值導覽屬性展開實體執行個體的相關實體。

    • 要求

      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

    • 回覆

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

注意

您無法使用 /$ref 或 /$count 路徑區隔來僅傳回相關實體的 URI，或相關實體數目的計數

適用於展開實體的選項

您可以套用特定系統查詢選項在針對集合值導覽屬性傳回的實體上。 於集合值導覽屬性名稱後面，在括號內使用分號分隔的系統查詢選項清單。 您可以使用 $select、$filter、$orderby 和 $top。

下列範例會篩選與客戶相關的工作實體結果，僅顯示 subject 的結尾為 "1" 的結果。

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

下列範例指定，相關工作應根據 createdon 屬性依遞增順序傳回。

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

下列範例只會傳回第一個相關的工作。

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

注意

這是OData 4.0 版第 1 部分：通訊協定與 Errata 02的＜11.2.4.2.1 展開選項＞一節中說明的系統查詢選項的子集。 Web API 不支援 $skip、$count、$search、$expand 和 $levels 選項。

偵測實體自擷取後是否變更

基於效能最佳作法，您應只要求您需要的資料。 如果您先前已擷取實體記錄，可以使用與先前擷取的記錄相關的 ETag 執行該記錄的條件式擷取。 如需詳細資訊，請參閱條件擷取。

擷取格式化的值

要求個別記錄擷取的格式化值，方法與查詢實體集相同。其他資訊：包含格式化的值。

另請參閱

Web API 基本作業範例 (C#)
Web API 基本作業範例 (用戶端 JavaScript)
使用 Web API 執行作業
撰寫 HTTP 要求並處理錯誤
使用 Web API 查詢資料
使用 Web API，建立實體
使用 Web API 更新和刪除實體
使用 Web API 建立和取消實體的關聯
使用 Web API 功能
使用 Web API 動作
使用 Web API，執行批次作業
使用 Web API 模擬其他使用者
使用 Web API 執行條件運算

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權