Concept : API REST pour l'exportation de données

Administrator Guide

Aperçu

L' API Data Exportation du service REST Prism aptitude d'exporter des données à partir de sources de données Prism reposant sur des tables.

Fonctionnalités principales

Créez une tâche d'exportation de données pour exporter des données à partir d'une source de données Prism reposant sur une table .

Annuler une tâche d'exportation de données spécifique. Le statut de la tâche d'export de données doit être Planifié ou En cours.

Les utilisateurs qui font partie de ces groupes de sécurité non limités peuvent afficher et annuler toutes les tâches d'exportation de données.

Les utilisateurs d'un groupe de sécurité en libre-service peuvent afficher et annuler uniquement les tâches d'exportation de données qu'ils ont créées.

Vérifiez le statut de la tâche d'export des données.

Planifié : Workday a planifié l'exécution de la tâche d'export de données.

En cours : Workday est en train d'exécuter la tâche d'export de données.

Succès : Workday a terminé la tâche d'exportation de données et a créé un ou plusieurs fichiers de sortie contenant les données exportées.

Annulé : Workday a interrompu l'exécution de la tâche d'export de données à la demande d'un utilisateur.

Échec : Workday a rencontré une erreur lors de la tentative d'exécution de la tâche d'export de données.

Téléchargez les fichiers de sortie contenant les données exportées.

Vous ne pouvez téléchargement que les fichiers de sortie autorisés par le profil de sécurité de l'utilisateur actuel.

Vous pouvez téléchargement les fichiers de manière séquentielle ou en parallèle. Vous pouvez réduire le temps obligatoire au téléchargement de tous les fichiers de sortie en les téléchargeant en parallèle.

La performance du téléchargement dépend des éléments suivants :

Nombre de fichiers.

Nombre de téléchargements en parallèle.

Largeur du réseau entre le client API et le serveur Workday . Exemple : si le client se trouve dans une région géographique différente de celle du serveur, le temps de téléchargement des fichiers augmente.

Cas d'utilisation

Cas d'utilisation	Description
Divulgation et reporting légal.	Avec un calendrier pouvant plage de quotidien à annuel, vous devez extraire de Workday des volumes importants de données financières détaillées pour des périodes spécifiques. Après exportation, vous pouvez soumettre les données à un Data Lake ou à un outil de reporting réglementaire. L'outil facilite le formatage et la soumission des informations financières afin de respecter la réglementation stricte.
Analyses avancées, science des données et reporting divers.	Vous devez extraire de Workday des volumes importants de données opérationnelles et financières détaillées pour des périodes spécifiques. Après l'exportation, vous pouvez soumettre les données à un Data Lake ou à un workbench de science des données, où vous pouvez créer des modèles prédictifs pour les sujets suivants, entre autres : Clients et utilisateurs. Salariés. Recherches marketing. Performance. Produits ou services.
Blocages et archivages réglementaires.	Vous devez respecter les normes réglementaires et de conformité en archivé 5 à 7 ans. Vous devez mettre ces données à disposition des organismes de réglementation et des auditeurs immédiatement sur demande, conformément aux réglementations et au secteur d'activité applicables.
Demandes d'audit.	Pour effectuer un audit détaillé, vous devez demander l'ensemble des transactions, activités et métadonnées pour certains soldes sur une période donnée. Ces données sont obligatoire sur une base mensuelle, trimestrielle et annuelle, ainsi que pour les années précédentes. Vous devez exporter un grand nombre de données dans votre base de données d'audit .

Chemin d'accès à l'URL de base

Chemin de base de l'environnement client

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

Exemple pour créer une tâche d'export de données :

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

Chemin de base de la API Workday Extend

Pour les applications Workday Extend, utilisez l'URL de base de la passerelle API locale de votre unité légale. Voir Référence : passerelles API Workday Extend et URL de base d'autorisation sur le site Developer.

L'URL de base de la passerelle API n'inclut pas le nom de l'environnement client.

Éléments de sécurité à prendre en compte

Domaines suivants dans le domaine fonctionnel Prism :

Exportation de données Prism : exécution
: contrôle qui peut créer des tâches d'exportation de données.

Exportation de données Prism : Gérer
: contrôle qui peut afficher et annuler les tâches d'exportation de données.

Création de tâche d'exportation de données

POST /dataExport

endpoint facilite la création d'une tâche d'exportation de données.

Éléments de sécurité :

domaine Prism Data Export: Execute
dans le domaine fonctionnel Prism Analytics .

L'une des conditions de sécurité suivantes pour la table à partir de laquelle vous exportez :

domaine Prism: Tables Manage
dans le domaine fonctionnel Prism Analytics .

domaine Prism: Tables Owner Manage
dans le domaine fonctionnel Prism Analytics .

autorisation d'affichage de table
sur la table.

autorisation d'éditeur de table
sur la table.

autorisation du propriétaire de la table
sur la table.

Utilisez cette méthode pour créer une tâche d'exportation de données pour une source de données Prism spécifique.

Lorsque vous créez une tâche d'exportation de données, Workday génère un ou plusieurs fichiers contenant des données de la source de données Prism que vous pouvez téléchargement sur votre ordinateur en local.

Dans le corps de la demande, indiquez une valeur pour les paramètres suivants :

Paramètre de corps	Type	Description
input	Objet	Incluez une requête WQL qui indique chaque champ à exporter depuis une source de données Prism. Utilisez le format suivant : "input": { "query": " WQL_Query ", "type": "SQL" } Lorsque vous écrivez la requête WQL : Utiliser l'alias WQL de la source de données Prism et chaque champ. Répertoriez tous les champs que vous souhaitez inclure. Vous pouvez également renommer un champ à l'aide de l'opérateur AS. (Facultatif) Vous pouvez filtre les enregistrements à l'aide d'une clause WHERE. Vous pouvez filtre un champ Date en le comparant à un autre champ Date. Vous ne pouvez pas filtre un champ Date en le comparant à une valeur de date littérale. Vous pouvez exporter n'importe quel type de champ, à l'exception des champs Multi-instance. Pour en savoir plus sur la façon de spécifier une requête valide dans le paramètre d'entrée, voir Référence : utilisation des requêtes WQL et recommandations pour l'exportation de données .
output	Objet	Utilisez le format suivant : "output": { "type": "CSV_GZIP", “headers”: true }

Exemple de demande :

POST /dataExport

Corps de la demande d'exemple :

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

Sample Response

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

Statut de la tâche d'extraction de données

GET /dataExport

endpoint facilite la récupération de toutes les tâches d'exportation de données.

GET /dataExport/{id}

facilite la récupération d'une tâche d'exportation.

Éléments de sécurité :

domaine Prism Data Export: Manage
dans le domaine fonctionnel Prism Analytics .

Ce point de terminaison renvoie les tâches d'exportation de données pour lesquelles l'utilisateur actuel est autorisation . Lors de la récupération d'une collection, utilisez les paramètres de requête facultatifs suivants :

Paramètre de requête	Description	Valeur par défaut	Max.
type	La valeur du type détermine les champs de réponse à inclure. full : renvoie toutes les informations d'exportation de données. Summary : renvoie une réponse récapitulative en excluant la liste des résultats de sortie.	summary
limit	Limite de saisies de données objet incluses dans une seule réponse.	20	1 000
offset	contrepartie sur le premier objet d'une collection à inclure dans la réponse.	0

Exemple de demande :

GET /dataExport

Exemple de réponse :

La réponse est un ensemble de tâches d'exportation de données, au format JSON .

Cet exemple de réponse affiche une seule tâche d'exportation de données.

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

Exemple de demande permettant de récupérer des informations sur la tâche d'exportation de données avec l'identifiant = b1bd0e1ac5d410001193bf9340050000 :

GET /dataExport/b1bd0e1ac5d410001193bf9340050000

Exemple de réponse :

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

Téléchargement des fichiers de sortie

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

endpoint facilite le téléchargement des fichiers de sortie à partir d'une tâche d'exportation de données.

Renseignez le champ :

Identifiant de la tâche d'exportation de données.

Nom du fichier de sortie de la tâche d'exportation de données.

GET /dataExport/{id}

endpoint fournit les noms des fichiers de sortie.

Vous ne pouvez téléchargement que les fichiers de sortie autorisés par le profil de sécurité de l'utilisateur actuel. Vous pouvez téléchargement les fichiers de manière séquentielle ou en parallèle.

Éléments de sécurité :

domaine Prism Data Export: Manage
dans le domaine fonctionnel Prism Analytics .

Exemple de demande de téléchargement du fichier nommé 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

Annuler une tâche d'exportation de données

POST /dataExport/{id}/cancel

endpoint facilite l'annulation d'une tâche d'exportation de données spécifique en cours planifiée ou en cours.

Vous pouvez annuler uniquement les tâches d'exportation de données autorisées par le profil de sécurité de l'utilisateur actuel.

Éléments de sécurité :

L'un des domaines suivants, dans le domaine fonctionnel Prism Analytics :

Exportation de données Prism : exécuter

Exportation de données Prism : Gérer

L'une des conditions de sécurité suivantes pour la table à partir de laquelle vous exportez :

domaine Prism: Tables Manage
dans le domaine fonctionnel Prism Analytics .

domaine Prism: Tables Owner Manage
dans le domaine fonctionnel Prism Analytics .

autorisation d'affichage de table sur la table.

autorisation d'éditeur de table sur la table.

autorisation du propriétaire de la table sur la table.

Exemple de demande :

Vous devez inclure une chaîne JSON vide {} dans le corps de la demande pour cette méthode.

Exemple de demande pour annuler une tâche d'exportation de données avec l'identifiant b1bd0e1ac5d4100018d18abc4ea00000 :

POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel

Exemple de réponse :

La réponse contient la tâche d'exportation de données, y compris son statut actuel Annulé au format 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"
}

Limites

Les tâches d'exportation sont des tâches de faible priorité et auront une priorité moins élevée que les autres tâches de publication.

Vous ne pouvez pas téléchargement les fichiers générés au-delà de 7 jours, car les fichiers seront supprimés.

Les maximums suivants sont définis comme garde-fous afin d'optimiser les performances et la fiabilité du système :

1 milliard de lignes par tâche d'exportation.

1 000 colonnes par requête.

Requêtes de téléchargement simultanées :

Si la limite du système est atteinte, vous recevoir une réponse 503 - HIT_servER_LIMIT.

Si un environnement client dépasse sa limite spécifique, vous recevoir une réponse 429 - HIT_TENANT_LIMIT.

Tâches d'exportation simultanées :

Une seule tâche d'exportation peut être exécutée à la fois par utilisateur ou par environnement client.

Toutes les tâches d'exportation supplémentaires seront automatiquement mises en file d'attente jusqu'à ce que la tâche actuelle soit terminée.

Erreurs courantes

Erreurs de validation :

Json d'entrée mal formé.

SQL mal formé, champs/nom de table non valide , fonctions non prises en charge.

Sécurité : nombre de champs > 1 0 000.

Contraintes de sécurité non respectées.

Erreurs d'exécution

Erreurs système.

Gaudpils : échec si l'extraction contient plus d'1 milliard de lignes.

Télécharger les API

Lors du téléchargement, il est toujours recommandé au client HTTP de lancer une nouvelle tentative en raison de problèmes de réseau ou de système imprévus. Une limite de taux est appliquée au nombre de connexions simultanées créées pour un environnement client et un serveur. Vous pouvez voir apparaître de temps en temps des codes d'état HTTP

429

503

du fait des limites appliquées. Il est recommandé au client d'attendre un peu avant de réessayer.

Éléments à prendre en compte : Performance

Performance de l'extraction des données :

La durée d'exécution de l'extraction des données varie en fonction du type de données et du nombre de lignes et de colonnes dans les données.

La durée d'exécution augmente avec le volume de données.

Performance de téléchargement :

Le temps total de téléchargement pour toutes les tailles de fichier diminue de manière linéaire avec le nombre de processus qui téléchargement les résultats.

Les performances de téléchargement peuvent également être influencées par la débit du réseau et site du serveur de environnement client .

Étapes : définir l'environnement client pour l'API REST d'exportation de données Prism

Étapes : exporter des données depuis une source de données Prism

Référence : utilisation des requêtes WQL et recommandations pour l'export des données