概念：数据导出REST API

Administrator Guide

下载 PDF

概念：数据导出REST API

概览

使用 Prism REST服务中的 Data Export 应用程序编程接口 (API)，能力从以表支持的 Prism 数据源大规模导出数据。

主要功能

创建数据导出作业，从以表支持的 Prism数据源“”导出数据。

取消特定的数据导出作业。数据导出作业的状态必须为“已排定”或“正在运行”。

位于不受限制的安全组中的用户可以查看和取消所有数据导出作业。

自助服务安全组中的用户只能查看和取消他们创建的数据导出作业。

检查数据导出作业“”的状态。

已排定时间表： Workday已排定运行数据导出作业“”。

正在处理： Workday当前正在运行数据导出作业。

成功： Workday已完成数据导出作业，并创建了一个或多个包含导出数据的输出文件。

已取消： Workday应用户请求，申请已停止运行数据导出作业。

失败： 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)网关基本路径

对于Workday Extend 应用，请使用您公司的区域应用程序编程接口 (API)网关基 URL。请参见开发人员网站上的“Reference: Workday Extend 应用程序编程接口 (API) Gateways and Authorization Base URLs” 。

应用程序编程接口 (API)网关基 URL 不包含租户名称“”。

安全性注意事项

“Prism”功能区域中的以下域：

Prism 数据导出：执行
：控制谁可以创建数据导出作业。

Prism 数据导出：管理
：控制谁可以查看和取消数据导出作业。

创建数据导出作业

该

POST /dataExport

端点可协助“”创建数据导出作业。

安全性注意事项：

“Prism Analytics”功能区域中的“Prism 数据导出：执行
”域。

对于从中进行导出的表，存在以下任何安全性要求：

“Prism Analytics”功能区域中的“Prism: Tables Manage
”域。

Prism:
“Prism Analytics”功能区域中的“Tables Owner Manage ”域。

“”表的“表格查看者”
权限。

“”表的“表格编辑者”
权限。

“ ”表的“表格所有者”
权限。

使用此方法可为指定的 Prism数据源“”创建数据导出作业。

当您创建数据导出作业“”时， Workday会生成一个或多个文件，其中包含您可以从 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 Data Export: Manage
”域。

此端点将返回当前用户权限执行的数据导出作业。检索集合时，请使用以下可选查询参数：

查询参数	描述	默认值	最大值
type	类型“”的值决定了要包括的回复字段。 Full：返回所有数据的导出信息。汇总：通过排除输出结果列表来返回汇总回复。	汇总
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}

端点有助于从数据导出作业“”下载输出文件。

指定：

数据导出作业“”的编号。

数据导出作业“”的输出文件的名称。

该

GET /dataExport/{id}

端点会提供输出文件的名称。

您只能下载当前用户的安全概要所允许的输出文件。您可以顺序或并行下载文件。

安全性注意事项：

“Prism Analytics”功能区域中的“Prism Data Export: 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:
“Prism Analytics”功能区域中的“Tables Owner Manage ”域。

“”表的“表格查看者”权限。

“”表的“表格编辑者”权限。

“ ”表的“表格所有者”权限。

请求示例：

为此方法，您必须在请求，申请主体中包含一个空的JSON字符串“{}”。

取消编号为 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。

不符合安全限制条件。

执行错误

系统错误。

花花公子：如果提取的行超过 1B，则失败。

下载 API

下载时，由于不可预见的网络问题或系统问题，始终建议让 HTTP客户端进行重试。对租户和服务器创建的并行连接数存在速率限制。您可能偶尔会看到 HTTP 状态代码

429

或

503

由于这些强制限定的限额。建议客户端等待一段时间，然后再次尝试该请求，申请。

性能注意事项

数据提取性能：

数据提取执行时间因数据类型以及数据中的行数和列数而异。

执行时间会随着数据卷号的增加而增加。

下载绩效：

各种大小的文件的下载时间总计将随着下载结果的流程数量线性减少。

网络带宽和租户服务器地点也可能会影响下载性能。

步骤：为 Prism 数据导出 REST API 设置租户

步骤：从 Prism 数据源导出数据

参考信息：用于数据导出的 WQL 查询用途和指导原则