使用入口網站 API 查詢資料

發行項
03/16/2023

您可以在 Power Pages 中使用可用的 WEB API 作業。 Web API 作業是由 HTTP 要求和回應所組成。本文提供可在 HTTP 要求中使用的範例讀取作業、方法、URI 及範例 JSON。

先決條件

您的網站版本必須為 9.4.1.x 或更新版本。
為 Web API 作業啟用資料表和欄位。其他資訊：WEB API 的網站設定
入口網站 Web API 會存取資料表記錄，並遵循透過關聯的 Web 角色授與使用者的資料表權限。請確定您已設定正確的資料表權限。其他資訊：建立 Web 角色

注意

使用入口網站 API 來參考 Dataverse 資料表時，需要使用 EntitySetName，例如若要存取 account 資料表，程式碼語法將使用 accounts 的 EntitySetName。

查詢記錄

下列範例會查詢客戶紀錄：

作業	Method	URI
擷取資料表記錄	GET	`[Portal URI]/_api/accounts` 範例： `https://contoso.powerappsportals.com/_api/accounts`

範例回覆

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

使用 $select 和 $top 系統查詢選項來傳回前三個客戶的名稱屬性：

作業	Method	URI
擷取前三個實體記錄	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

使用客戶識別碼擷取客戶：

作業	Method	URI
擷取記錄的特定屬性	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` 範例： `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

範例回覆

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

套用系統查詢選項

您附加至實體集 URL 的每個系統查詢選項都是使用查詢字串的語法新增的。第一個查詢會附加在 [?] 後面，而隨後的查詢選項會使用 [&] 來分隔。所有查詢選項都要區分大小寫，如以下範例所示：

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

要求特定屬性

使用 $select 系統查詢選項來限制傳回的屬性，如以下範例所示：

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

重要

這是效能最佳作法。如果未指定屬性，且已將 Webapi/<table name>/fields 網站設定值設定為 *，則會使用 $select 來傳回所有屬性。如果未指定任何屬性，則會傳回錯誤。

篩選結果

使用 $filter 系統查詢選項，以設定要傳回資料列的準則。

標準篩選運算子

Web API 支援下表列出的標準 OData 篩選運算子：

Operator	描述	範例
比較運算子
eq	等於	$filter=revenue eq 100000
ne	不等於	$filter=revenue ne 100000
gt	大於	$filter=revenue gt 100000
ge	大於或等於	$filter=revenue ge 100000
lt	小於	$filter=revenue lt 100000
le	小於或等於	$filter=revenue le 100000
邏輯運算子
and	邏輯和	$filter=revenue lt 100000 and revenue gt 2000
or	邏輯或	$filter=contains(name,'(sample)') or contains(name,'test')
not	邏輯否定	$filter=not contains(name,'sample')
群組運算子
( )	優先群組	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

標準查詢函數

Web API 支援以下標準 OData 字串查詢函數：

函數	範例
contains	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Dataverse 查詢函數

Web API 支援 Dataverse 查詢函數以篩選結果。如需詳細資訊，請參閱 Web API 查詢函數參考。

排序結果

使用 $orderby 系統查詢選項指定傳回項目的順序。請使用 asc 或 desc 尾碼來分別指定遞增或遞減。如果未套用尾碼，則預設為遞增。以下範例顯示擷取的客戶名稱和收入屬性依收入遞增和名稱遞減排序。

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

彙總與群組結果

透過使用 $apply，您可以動態地彙總和群組資料，如下列範例所示：

案例	範例
查詢中的唯一狀態清單	accounts?$apply=groupby((statuscode))
估計值的彙總總和	opportunities?$apply=aggregate(estimatedvalue with sum as total)
根據估計值與狀態的平均交易大小	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
根據狀態的估計值總和	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
依客戶名稱劃分的商機總收入	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
「WA」中客戶的主要連絡人名稱	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
上次建立記錄的日期和時間	accounts?$apply=aggregate(createdon with max as lastCreate)
第一次建立記錄的日期和時間	accounts?$apply=aggregate(createdon with min as firstCreate)

擷取列數

請使用值為 True 的 $count 系統查詢選項，以包括符合篩選準則的實體計數，最多 5,000 個。

Method	URI
GET	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true`

範例回覆

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

如果您不想要傳回除計數以外的任何資料，您可以將 $count 套用至任何集合來只取得該值。

Method	URI
GET	`[Portal URI/_api/accounts/$count` 範例： `https://contoso.powerappsportals.com/_api/accounts/$count`

範例回覆

3

資料行比較

下列範例顯示如何使用 Web API 來比較資料行：

Method	URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` 範例： `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

使用瀏覽屬性中的 $expand 系統查詢選項，來控制要傳回相關實體中的哪些資料。

使用 $expand 查詢選項時，您需要使用 Microsoft.Dynamics.CRM.associatednavigationproperty 做為查詢屬性。

要確定屬性的 Microsoft.Dynamics.CRM.associatednavigationproperty，您可以使用以下命名約定對資料行發出以下 http GET 要求：_name_value。

在以下示例中，我們可以通過在請求中格式化名稱來指定列名稱 primarycontactid 來確定帳戶資料表的主要連絡人資料行的關聯瀏覽屬性：_primarycontactid_value。

Method	URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` 範例 `https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value`

範例回覆

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

我們從回覆中看到關聯的瀏覽屬性是 primarycontactid。關聯的瀏覽屬性可以是查詢資料行的邏輯名稱或結構描述名稱，依資料表的建立方式而定。

如需詳細資訊，請參閱擷取有關查詢屬性的資料。

以下範例顯示如何擷取所有客戶記錄的連絡人。對於相關的連絡人記錄，我們只會擷取 contactid 和 fullname。

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` 範例： `https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)`

範例回覆

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

如果您展開集合值瀏覽參數以擷取實體集的相關資料表，則有資料時只會傳回一個深度層級。否則，集合將傳回空白陣列。

Method	URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` 範例： `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

下面的範例說明如何使用單一值瀏覽屬性和集合值瀏覽屬性展開實體集的相關實體。您必須在程式碼的語法中指定資料表關聯名稱。

Method	URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` 範例： `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

後續步驟

入口網站使用 Web API 寫入、更新和刪除作業

共用方式為

使用入口網站 API 查詢資料

先決條件

查詢記錄

套用系統查詢選項

要求特定屬性

篩選結果

標準篩選運算子

標準查詢函數

Dataverse 查詢函數

排序結果

彙總與群組結果

擷取列數

資料行比較

查詢關聯的瀏覽屬性

後續步驟

另請參閱

意見反應

其他資源

共用方式為

使用入口網站 API 查詢資料

先決條件

查詢記錄

套用系統查詢選項

要求特定屬性

篩選結果

標準篩選運算子

標準查詢函數

Dataverse 查詢函數

排序結果

彙總與群組結果

擷取列數

資料行比較

使用查詢擷取相關資料表記錄

查詢關聯的瀏覽屬性

透過展開單一值瀏覽屬性來擷取相關資料表記錄

透過展開集合值瀏覽屬性來擷取相關資料表

透過展開單一值和集合值瀏覽屬性來擷取相關資料表

後續步驟

另請參閱

意見反應

其他資源