Concepto: API de REST de exportación de datos

Administrator Guide

Información general

La API de exportación de datos del servicio REST Prism ofrece la posibilidad de exportar datos a gran escala desde orígenes de datos Prism respaldados por tablas.

Funciones clave

Cree un trabajo de exportación de datos para exportar datos de un origen de datos Prism respaldado por una tabla.

Cancele un trabajo de exportación de datos específico. El estado del trabajo de exportación de datos debe ser Programado o En ejecución.

Los usuarios de grupos de seguridad sin restricciones pueden consultar y cancelar todos los trabajos de exportación de datos.

Los usuarios de un grupo de seguridad de autoservicio solo pueden consultar y cancelar los trabajos de exportación de datos que han creado.

Compruebe el estado del trabajo de exportación de datos.

Programado: Workday ha programado la ejecución del trabajo de exportación de datos.

En proceso: Workday está ejecutando actualmente el trabajo de exportación de datos.

Correcto: Workday ha finalizado el trabajo de exportación de datos y ha creado uno o varios archivos de resultado que contienen los datos exportados.

Cancelado: Workday ha dejado de ejecutar el trabajo de exportación de datos a petición de un usuario.

Error: Workday ha encontrado un error al intentar ejecutar el trabajo de exportación de datos.

Descargue los archivos de resultado que contienen los datos exportados.

Solo puede descargar los archivos de resultado permitidos por el perfil de seguridad del usuario actual.

Puede descargar archivos de forma secuencial o en paralelo. Puede reducir el tiempo necesario para descargar todos los archivos de resultado descargándolos en paralelo.

El rendimiento de la descarga depende de:

El número de archivos.

El número de descargas paralelas.

El ancho de banda de red entre el cliente de API y el servidor de Workday. Ejemplo: si el cliente se encuentra en una región geográfica diferente a la del servidor, el tiempo para descargar los archivos aumentará.

Ejemplos de uso

Ejemplo de uso	Descripción
Divulgaciones e informes preceptivos por ley.	En un calendario que puede variar de diario a anual, debe extraer grandes volúmenes de datos financieros detallados para periodos específicos de Workday. Después de la exportación, puede enviar los datos a un lago de datos empresariales o a una herramienta de informes normativos. La herramienta facilita el formato y el envío de declaraciones financieras para cumplir con las estrictas normativas.
Análisis avanzado, ciencia de datos e informes diversos.	Necesita extraer grandes volúmenes de datos operativos y financieros detallados para periodos específicos de Workday. Después de la exportación, puede enviar los datos a un lago empresarial o a un área de trabajo de ciencia de datos, donde puede crear modelos predictivos para estos temas, entre otros: Clientes y usuarios Empleados Investigación de mercados El desempeño Productos o servicios
Retenciones y archivos reglamentarios	Debe cumplir con los estándares normativos y de cumplimiento archivando de 5 a 7 años de datos financieros. Debe poner estos datos a disposición de las autoridades reguladoras y los auditores inmediatamente después de que lo soliciten, de acuerdo con las normativas y el sector aplicables.
Solicitudes de auditoría	Para llevar a cabo una auditoría exhaustiva, debe solicitar todas las transacciones, la actividad y los metadatos de determinados saldos durante un periodo especificado. Estos datos son obligatorios con periodicidad mensual, trimestral y anual, así como para años anteriores. Debe exportar un gran número de datos a su base de datos de auditoría.

Ruta base de URL

Ruta base de entorno de cliente

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

Ejemplo para crear un trabajo de exportación de datos:

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

Ruta base de Workday Extend API Gateway

Para las apps de Workday Extend, utilice la URL base de API Gateway regional de su empresa. Consulte Referencia: Workday Extend API Gateways and Authorization Base URLs en el sitio de desarrollador.

La URL base de API Gateway no incluye el nombre del entorno de cliente.

Consideraciones de seguridad

Estos dominios en el área funcional Prism:

Prism Data Export: Execute
: controla quién puede crear trabajos de exportación de datos.

Prism Data Export: Manage
: controla quién puede consultar y cancelar trabajos de exportación de datos.

Creación de trabajo de exportación de datos

POST /dataExport

endpoint facilita la creación de un trabajo de exportación de datos.

Consideraciones de seguridad:

Dominio Prism Data Export: Execute
en el área funcional Prism Analytics.

Cualquiera de estos requisitos de seguridad para la tabla desde la que exporta:

Dominio Prism: Tables Manage
en el área funcional Prism Analytics.

Dominio Prism: Tables Owner Manage
en el área funcional Prism Analytics.

Permiso Visor de tabla
en la tabla.

Permiso Editor de tablas
en la tabla.

Permiso Propietario de tabla
en la tabla.

Utilice este método para crear un trabajo de exportación de datos para un origen de datos Prism especificado.

Cuando crea un trabajo de exportación de datos, Workday genera uno o varios archivos que contienen datos del origen de datos Prism que puede descargar en su equipo local.

En el cuerpo de la solicitud, proporcione un valor para los siguientes parámetros:

Parámetro de cuerpo	Tipo	Descripción
entrada	Objeto	Incluya una consulta WQL que especifique todos los campos para exportar desde un origen de datos Prism. Utilice este formato: "input": { "query": " WQL_Query ", "type": "SQL" } Al escribir la consulta WQL: Utilice el alias de WQL del origen de datos Prism y de cada campo. Enumere todos los campos que desee incluir. Opcionalmente, puede cambiar el nombre de un campo mediante el operador AS. Puede filtrar los registros mediante una cláusula WHERE (opcional). Puede filtrar un campo de fecha comparándolo con otro campo de fecha. No puede filtrar un campo de fecha comparándolo con un valor de fecha literal. Puede exportar cualquier tipo de campo, excepto los campos de varias instancias. Para obtener más información sobre cómo especificar una consulta válida en el parámetro de entrada, consulte Referencia: uso de consultas de WQL y pautas para la exportación de datos.
resultado	Objeto	Utilice este formato: "output": { "type": "CSV_GZIP", “headers”: true }

Solicitud de muestra:

POST /dataExport

Cuerpo de solicitud de muestra:

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

Respuesta de muestra

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

Obtención de estado de trabajo de exportación de datos

GET /dataExport

endpoint facilita la recuperación de todos los trabajos de exportación de datos.

GET /dataExport/{id}

facilita la recuperación de un trabajo de exportación.

Consideraciones de seguridad:

Dominio Prism Data Export: Manage
en el área funcional Prism Analytics.

Este punto de conexión devuelve los trabajos de exportación de datos para los que el usuario actual tiene permiso. Al recuperar una recopilación, utilice los siguientes parámetros de consulta opcionales:

Parámetro de consulta	Descripción	Por defecto	Máx.
tipo	El valor de tipo determina qué campos de respuesta se incluyen. full: devuelve toda la información de exportación de datos. Resumen: devuelve una respuesta resumida excluyendo la lista de resultados de salida.	resumen
limit	El límite de entradas de datos de objeto incluidas en una sola respuesta.	20	1000
offset	La compensación del primer objeto de una colección que se incluirá en la respuesta.	0

Solicitud de muestra:

GET /dataExport

Ejemplo de respuesta:

La respuesta es una recopilación de trabajos de exportación de datos en formato JSON.

Esta respuesta de muestra muestra solo un trabajo de exportación de datos.

{
 "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"
  },
  ...
 ]
}

Solicitud de ejemplo para recuperar información sobre el trabajo de exportación de datos con el ID = b1bd0e1ac5d410001193bf9340050000:

GET /dataExport/b1bd0e1ac5d410001193bf9340050000

Ejemplo de respuesta:

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

Descarga de archivos de resultado

GET /dataExport/{id}/results/{fielName}

endpoint facilita la descarga de archivos de resultado de un trabajo de exportación de datos.

Especifique:

El ID del trabajo de exportación de datos.

El nombre del archivo de resultado del trabajo de exportación de datos.

GET /dataExport/{id}

endpoint proporciona los nombres de los archivos de resultado.

Solo puede descargar los archivos de resultado permitidos por el perfil de seguridad del usuario actual. Puede descargar archivos de forma secuencial o en paralelo.

Consideraciones de seguridad:

Dominio Prism Data Export: Manage
en el área funcional Prism Analytics.

Ejemplo de solicitud para descargar el archivo 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

Cancelación de un trabajo de exportación de datos

POST /dataExport/{id}/cancel

endpoint facilita la cancelación de un trabajo de exportación de datos específico que está programado o en ejecución.

Solo puede cancelar los trabajos de exportación de datos permitidos por el perfil de seguridad del usuario actual.

Consideraciones de seguridad:

Uno de estos dominios en el área funcional Prism Analytics:

Exportación de datos Prism: Ejecutar

Exportación de datos Prism: gestión

Cualquiera de estos requisitos de seguridad para la tabla desde la que exporta:

Dominio Prism: Tables Manage
en el área funcional Prism Analytics.

Dominio Prism: Tables Owner Manage
en el área funcional Prism Analytics.

Permiso Visor de tabla en la tabla.

Permiso Editor de tablas en la tabla.

Permiso Propietario de tabla en la tabla.

Solicitud de muestra:

Debe incluir una cadena JSON vacía {} en el cuerpo de la solicitud para este método.

Ejemplo de solicitud para cancelar un trabajo de exportación de datos con el ID b1bd0e1ac5d4100018d18abc4ea00000:

POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel

Ejemplo de respuesta:

La respuesta contiene el trabajo de exportación de datos, incluido su estado actual de Cancelado, en formato 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"
}

Limitaciones

Los trabajos de exportación son trabajos de baja prioridad y tendrán menor prioridad que otros trabajos como el de publicación.

No puede descargar los archivos generados después de 7 días, ya que se eliminarán.

Estos valores máximos se establecen como medidas de seguridad para optimizar el rendimiento y la fiabilidad del sistema:

Mil millones de filas por trabajo de exportación

1000 columnas por consulta

Solicitudes de descarga simultáneas:

Si se alcanza el límite del sistema, recibirá una respuesta 503 - HIT_SERVER_LIMIT.

Si un entorno de cliente supera su límite específico, recibirá una respuesta 429 - HIT_TENANT_LIMIT.

Trabajos de exportación simultáneos:

Solo se puede ejecutar un trabajo de exportación a la vez por usuario o entorno de cliente.

Cualquier trabajo de exportación adicional se pondrá automáticamente en cola hasta que finalice el trabajo actual.

Errores comunes

Errores de validación:

Json de entrada con formato incorrecto.

SQL con formato incorrecto, campos/nombre de tabla no válidos, funciones no admitidas.

Medidas de seguridad: número de campos > 10 000.

No se cumplen las restricciones de seguridad.

Errores de ejecución

Errores de sistema

Gaudrails: falla si la extracción tenía más de 1 000 millones de filas.

Descargar API

Al descargar, siempre se recomienda que el cliente HTTP tenga reintentos debido a problemas de red imprevistos o problemas del sistema. Se aplica un límite de velocidad al número de conexiones simultáneas creadas en un entorno de cliente y un servidor. Ocasionalmente puede ver códigos de estado HTTP

429

503

debido a estos límites impuestos. Se recomienda que el cliente espere un momento y vuelva a intentar la solicitud.

Consideraciones de rendimiento

Rendimiento de extracción de datos:

El tiempo de ejecución de la extracción de datos varía en función del tipo de datos y del número de filas y columnas de los datos.

El tiempo de ejecución aumenta con el volumen de datos.

Rendimiento de descarga:

El tiempo total de descarga para todos los tamaños de archivo disminuye linealmente con el número de procesos que descargan los resultados.

El rendimiento de la descarga también puede verse afectado por el ancho de banda de la red y la ubicación del servidor del entorno de cliente.

Pasos: definición del entorno de cliente para la API de REST de exportación de datos de Prism

Pasos: exportación de datos desde un origen de datos Prism

Referencia: uso de consulta WQL y pautas para exportación de datos