概念︰資料匯出REST API

Administrator Guide

下載 PDF

概念︰資料匯出REST API

總覽

Prism REST服務中的資料匯出API能力從表格支援的 Prism 資料來源大規模匯出資料。

主要特色

請建立資料匯出作業，從 Prism 表格提供的資料來源 ()匯出資料。

取消特定的資料匯出作業 ()。資料匯出作業的狀態必須為「已排定」或「執行中」。

未受限制的安全群組中的使用者可以檢視和取消所有的資料匯出作業。

自助服務安全群組中的使用者只能檢視及取消自己建立的資料匯出作業。

請檢查資料匯出作業的狀態︰。

已排程Workday已排定執行資料匯出作業。

處理中Workday目前正在執行資料匯出作業 ()。

成功Workday已完成資料匯出作業，並建立了 1 或多個包含匯出資料的輸出檔案。

已取消︰WorkdayWorkday使用者要求, 申請已停止執行資料匯出作業。

失敗Workday嘗試執行資料匯出作業 ()時發生錯誤。

下載包含匯出資料的輸出檔案。

您只能下載目前使用者的安全基本資料允許的輸出檔案。

您可以依序或併行下載檔案。您可以並行下載這些檔案必要, 必填, 必修的時間。

下載效能取決於︰

檔案數量。

並行下載次數。

API用戶端與Workday伺服器之間的網路頻寬。範例︰如果用戶端與伺服器位於不同的地理區域，下載檔案的時間將會增加。

使用個案

使用個案	說明
披露與法定報告	您需要從Workday擷取特定期間的大量詳細財務資料，時間表從每日到每年範圍。匯出後，您可以將資料提交至企業資料湖或法規報告工具。此工具可讓您更輕鬆地設定財務披露資料的格式和提交資料，以遵守嚴格的法規。
進階分析、資料科學和雜項報告。	您需要從Workday擷取特定期間的大量詳細營運和財務資料。匯出後，您可以將資料提交至企業湖或資料科學工作台，為以下學科建立預測模型：客戶與使用者。正職員工行銷研究績效。產品或服務。
依照監管規定暫停使用與封存。	您必須將財務資料封存 5 至 7 年，才能符合法規與法規遵循標準。您必鬚根據適用法規和產業，在主管機關和稽核人員要求, 申請時，立即提供這些資料。
稽核要求	若要進行徹底稽核，您必須要求, 申請取得指定時期內特定餘額的所有交易、活動和中繼資料。每月、每季、每年以及往年都必要, 必填, 必修此資料。您必須將大量資料匯出至您的稽核資料庫「」。

URL 基本路徑

用戶基本路徑

https://{hostname}/api/prismAnalytics/{version}/{tenantname}/dataExport

建立資料匯出作業的範例︰

https://yourTenantHostName.com/api/prismAnalytics/v3/<TENANT_NAME>/dataExport

Workday Extend API Gateway 基本路徑

若為Workday Extend 應用程式，請使用貴公司區域性的API Gateway 基本 URL。請參閱開發人員網站上的《參考： Workday Extend API Gateways and Authorization Base URLs》(參考︰Workday Extend API Gateways and Authorization Base URLs) 。

API Gateway 基本 URL 未包含用戶名稱「」。

安全注意事項

Prism功能區中的以下網域︰

Prism 資料匯出︰執行
︰控制誰能建立資料匯出作業。

Prism 資料匯出︰管理
：控制哪些人可以檢視及取消資料匯出作業。

建立資料匯出作業

的

POST /dataExport

端點有助建立資料匯出作業。

安全注意事項︰

「Prism Analytics」功能區中的「Prism DataExport: Execute」
網域。

以下任何一項安全要求適用於您從中匯出的表︰

「Prism Analytics」功能區中的「Prism:Tables Manage」
網域。

「Prism Analytics」功能區中的「Prism: Tables O網頁版主管理」
網域。

具有表「」的表格檢視者
權限。

具有表「」的表格編輯者
權限。

具有表「」的表格擁有者
權限。

使用此方法可為指定的 Prism資料來源建立資料匯出作業。

當您建立資料匯出作業， Workday會產生 1 或多個檔案，其中包含來自 Prism資料來源的資料，您可以將這些檔案下載到本機。

在要求, 申請內文中，為以下參數提供一個值：

內文參數	類型	說明
輸入	物件	請包含 WQL 查詢，指定要從 Prism資料來源匯出的每個欄位。使用此格式︰ "input": { "query": " WQL_Query ", "type": "SQL" } 編寫 WQL 查詢時︰使用 Prism資料來源和各欄位的 WQL 別名。列出您要包含的每個欄位。您也可以選擇使用 AS 運算子重新命名欄位。 (選用) 您可以使用 WHERE 子句篩選條件記錄。您可以將「日期」欄位與不同的「日期」欄位進行比較，篩選條件。您無法透過將日期欄位與日期文字值進行比較來篩選條件日期欄位。您可以匯出任何欄位類型，但多實例欄位除外。有關如何在輸入參數中指定有效查詢的詳細資料，請參閱《參考︰WQL 查詢使用方法和資料匯出準則》。
輸出	物件	使用此格式︰ "output": { "type": "CSV_GZIP", “headers”: true }

範例要求︰

POST /dataExport

範例要求內文︰

{
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "output": {
  "type": "CSV_GZIP",
  "headers": true
 }
}

範例回覆

{
 "createdMoment": "2017-03-17T00:00:00.000Z",
 "status": "Scheduled",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "id": "b1bd0e1ac5d410001193bf9340050000"
}

正在取得資料匯出作業狀態

的

GET /dataExport

端點有助擷取所有資料匯出作業。

的

GET /dataExport/{id}

便於擷取 1 個匯出作業。

安全注意事項︰

Prism Analytics功能區中的Prism DataExport:Manage
網域。

此端點會傳回目前使用者權限存取的資料匯出作業。擷取集合時，請使用以下選填查詢參數：

查詢參數	說明	預設值	上限
類型	類型的值會決定要包含哪些回覆欄位。完整︰傳回所有資料匯出資訊。摘要︰透過排除輸出結果清單，傳回摘要回覆。	摘要
limit	單一回覆中包含的物件資料項目上限。	20	1000
offset	要包含在回覆「」中的集合中第一個物件的抵銷。	0

範例要求︰

GET /dataExport

範例回覆︰

回覆是JSON格式的資料匯出作業集合。

此範例回覆僅顯示 1 個資料匯出作業︰。

{
 "total": 7,
 "data": [
  {
   "createdMoment": "2023-08-03T22:47:10.929Z",
   "createdBy": {
    "id": "274555853a4446cf8809325243534f34",
    "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr
 30.3, 41200, PayIntPartner; PayPartner, PayAdmin)",
    "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr
 30.3, 41200, PayIntPartner; PayPartner, PayAdmin)"
   },
   "status": "Success",
   "input": {
    "query": "SELECT insuranceOfficeState, sourceFileTag,
 sort1, sort2, agentCity, agentCountry, agentNote,
 GET_DISPLAY_ID(billingCompany) AS billing_company,
 GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter FROM
 cds_insuranceClaimData",
    "type": "SQL"
   },
   "output": {
    "noOfFiles": 4,
    "totalSizeInBytes": 5610214,
    "totalRows": 110408
   },
   "id": "b1bd0e1ac5d4100013ad1f50c6910000"
  },
  ...
 ]
}

範例要求, 申請擷取 ID = b1bd0e1ac5d410001193bf9340050000 的資料匯出作業相關資訊︰

GET /dataExport/b1bd0e1ac5d410001193bf9340050000

範例回覆︰

{
 "createdMoment": "2023-08-03T22:08:42.928Z",
 "createdBy": {
  "id": "274555853a4446cf8809325243534f34",
  "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)",
  "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)"
 },
 "status": "Success",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData WHERE claimAmount > 1000",
  "type": "SQL"
 },
 "output": {
  "createdTime": "2023-08-03T22:08:53.725Z",
  "expirationTime": "2023-08-10T22:08:53.725Z",
  "noOfFiles": 2,
  "totalSizeInBytes": 359680,
  "totalRows": 41301,
  "results": [
   {
    "name":
 "part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz",
    "length": 298913
   },
   {
    "name":
 "part-00001-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz",
    "length": 60767
   }
  ]
 },
 "id": "b1bd0e1ac5d410001193bf9340050000"
}

下載輸出檔案

的

GET /dataExport/{id}/results/{fileName}

端點有助於從資料匯出作業下載輸出檔案。

請指定︰

資料匯出作業的 ID。

資料匯出作業「」的輸出檔案名稱。

的

GET /dataExport/{id}

端點提供輸出檔案的名稱。

您只能下載目前使用者的安全基本資料允許的輸出檔案。您可以依序或併行下載檔案。

安全注意事項︰

Prism Analytics功能區中的Prism DataExport:Manage
網域。

下載名為part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c000.csv.gz 的檔案的範例要求, 申請︰

GET /dataExport/b1bd0e1ac5d410001193bf9340050000/results/part-00000-70e49bea-487e-4a3e-b43e-be3935e951c1-c 000.csv.gz

取消資料匯出作業

的

POST /dataExport/{id}/cancel

端點有助取消排定中或執行中的特定資料匯出作業。

您只能取消目前使用者的安全基本資料允許的資料匯出作業。

安全注意事項︰

Prism Analytics功能區中的以下其中一個網域︰

Prism 資料匯出︰執行

Prism 資料匯出︰管理

以下任何一項安全要求適用於您從中匯出的表︰

「Prism Analytics」功能區中的「Prism:Tables Manage」
網域。

「Prism Analytics」功能區中的「Prism: Tables O網頁版主管理」
網域。

具有表「」的表格檢視者權限。

具有表「」的表格編輯者權限。

具有表「」的表格擁有者權限。

範例要求︰

您必須在此方法的要求, 申請內文中加入空白的JSON字串 {}。

取消 ID 為 b1bd0e1ac5d4100018d18abc4ea00000 的資料匯出作業的範例要求, 申請︰

POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel

範例回覆︰

回覆中包含資料匯出作業(目前狀態為「已取消」) ( JSON格式)。

{
 "createdMoment": "2023-08-04T00:21:24.914Z",
 "createdBy": {
  "id": "274555853a4446cf8809325243534f34",
  "descriptor": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)",
  "fullName": "BLiu / Betty Liu (manager 4300, CostCtrMgr 30.3,
 41200, PayIntPartner; PayPartner, PayAdmin)"
 },
 "status": "Canceled",
 "input": {
  "query": "SELECT agentCity, GET_DISPLAY_ID(billingCompany) AS
 billing_company, GET_DISPLAY_ID(billingCostCenter) AS billing_CostCenter
 FROM cds_insuranceClaimData",
  "type": "SQL"
 },
 "id": "b1bd0e1ac5d4100018d18abc4ea00000"
}

限制

匯出作業屬於低優先順序順序，其優先低於發布等其他作業。

您無法在 7 天后下載產生的檔案，因為檔案將被刪除。

為使系統效能與可靠性最佳化，以下上限設定為防護欄：

每個匯出作業 ()包含 10 億列。

每個查詢可包含 1000 欄。

並行下載要求數︰

如果達到系統限制，您會接收503 - HIT_SERVER_LIMIT回覆。

如果用戶超過其特定限制，您會接收429 - HIT_tenant_LIMIT回覆。

並行匯出作業︰

每個使用者或用戶一次只能執行 1 個匯出作業。

在目前的作業完成之前，任何其他匯出作業都將自動排入佇列。

常見錯誤

驗證錯誤︰

輸入 json 格式錯誤。

SQL 格式錯誤、無效的欄位/表格名稱、不支援的函數。

防護機制︰欄位數 > 10000。

不符合安全限制。

執行錯誤

系統錯誤。

Gaudrains: 如果擷取的列數超過 10 億列，將會失敗。

下載 API

下載時，由於不可預見的網路問題或系統問題，建議 HTTP用戶端重新嘗試下載。為用戶和伺服器建立的並行連線數設有速率限制。您可能偶爾會看到 HTTP 狀態代碼

429

或

503

由於這些強制執行的限制，建議用戶端稍候片刻，然後要求, 申請一次。

效能注意事項

資料擷取效能︰

資料擷取執行時間會因資料類型以及資料中的列數和欄數而異。

執行時間會隨著資料冊數的增加而增加。

下載效能︰

所有檔案大小的總下載時間，會隨著下載結果的流程數量線性減少。

下載效能也會受到網路頻寬與用戶伺服器地點的影響。

步驟︰設定 Prism 資料匯出 REST API 的用戶

步驟︰從 Prism 資料來源匯出資料

參照︰WQL 查詢用途與資料匯出準則