概念：数据导出 REST API

Administrator Guide

下载 PDF

概念：数据导出 REST API

概览

Prism REST 服务中的 Data Export API 提供了从以表格支持的 Prism 数据源大规模导出数据的功能。

主要功能

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

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

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

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

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

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

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

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

已取消：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 Data Export: Execution
”域。

对数据源的导出表格存在以下任一安全性要求：

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

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

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

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

“表格的所有者”
权限。

使用此方法可为指定的 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 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/{fielName}

该端点有助于下载数据导出作业的输出文件。

指定：

数据导出作业的编号。

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

该

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

不满足安全性限制。

执行错误

系统错误

Gaudails：如果提取的行数超过 1B，则失败。

下载 API

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

429

或

503

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

性能注意事项

数据提取性能：

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

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

下载性能：

随着下载结果的进程数量的增加，所有大小的文件的总下载时间呈线性减少。

下载性能还可能受网络带宽和租户服务器位置的影响。

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

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

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