Concept : API REST d’exportation de données

Administrator Guide

Aperçu

L'API d'exportation de données du service Prism REST permet d'exporter à grande échelle des données à partir de sources de données Prism fondées sur des tables.

Fonctions clés

Créez une tâche d’exportation de données pour exporter des données à partir d’une source de données Prism fondée sur un tableau.

Annulez une tâche d'exportation de données précise. Le statut de la tâche d'exportation de données doit être Planifié ou En cours d'exécution.

Les utilisateurs des groupes de sécurité non contraints 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’exportation des données.

Planifié : Workday a planifié l’exécution de la tâche d’exportation des données.

En cours d’exécution : Workday exécute actuellement la tâche d’exportation des données.

Succès : Workday a terminé la tâche d’exportation des données et 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’exportation des 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’exportation de données.

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

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

Vous pouvez télécharger des fichiers de manière séquentielle ou en parallèle. Vous pouvez réduire le temps nécessaire 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 :

Le nombre de fichiers.

Le nombre de téléchargements en parallèle.

La bande passante 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 augmentera.

Cas d’utilisation

Cas d’utilisation	Description
Les divulgations et les rapports prévus par la loi.	Dans un calendrier qui peut être quotidien ou annuel, vous devez extraire de Workday de gros volumes de données financières détaillées pour des périodes spécifiques. Après l’exportation, vous pouvez soumettre les données à un bassin de données d’entreprise ou à un outil de production de rapports réglementaires. L’outil vous permet de mettre en forme et de soumettre plus facilement l’information financière afin de vous conformer à une réglementation stricte.
Analyses avancées, comptabilité des données et production de rapports divers.	Vous devez extraire de gros volumes de données opérationnelles et financières détaillées pour des périodes précises de Workday. Après l’exportation, vous pouvez soumettre les données à un plan d’entreprise ou à une console de connaissances sur les données, où vous pouvez créer des modèles prédictifs pour les sujets suivants, entre autres : Clients et utilisateurs. Les employés. Études de marketing. Le rendement. Des produits ou des services.
Les blocages réglementaires et les archivages.	Vous devez satisfaire aux normes réglementaires et de conformité en archivant des données financières de cinq à sept ans. Vous devez mettre ces données à la disposition des autorités réglementaires et des audits immédiatement sur demande, conformément aux réglementations et au secteur d’activité applicables.
Les demandes d’audit.	Pour effectuer un audit approfondi, vous devez demander l’ensemble des transactions, de l’activité et des métadonnées pour certains soldes au cours d’une période donnée. Ces données sont obligatoires 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 vers votre base de données d’audit.

Chemin de base de l'URL

Chemin de base du locataire

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

Exemple pour créer une tâche d’exportation de données :

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

Chemin de base de la passerelle Workday Extend API

Pour les applications Workday Extend, utilisez l’adresse URL de base de la passerelle API régionales pour votre société. Voir Référence : Workday Extend API Passerelles et Authorization Base URLs sur le site Développeur.

L'adresse URL de base de la passerelle API n'inclut pas le nom de locataire.

Éléments à prendre en compte pour la sécurité

Les 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 : Gestion
: Contrôle les personnes autorisées à afficher et à annuler des tâches d'exportation de données.

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

POST /dataExport

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

Éléments à prendre en compte pour la sécurité :

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

L’une des exigences de sécurité suivantes s’applique au tableau à partir duquel vous exportez :

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

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

L'autorisation de lecteur du tableau
sur le tableau.

L’autorisation de l’éditeur de tableau
sur le tableau.

L’autorisation du propriétaire du tableau
sur le tableau.

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

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

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

Paramètre du corps	Type	Description
données entrantes	Objet	Incluez une interrogation WQL qui indique chaque champ à exporter à partir d'une source de données Prism. Utilisez le format suivant : "input": { "query": " WQL_Query ", "type": "SQL" } Lors de l’écriture de l’interrogation WQL : Utilisez l'alias WQL de la source de données Prism et de 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 filtrer les enregistrements à l’aide d’une clause WHERE. Vous pouvez filtrer un champ de date en le comparant à un champ de date différent. Vous ne pouvez pas filtrer un champ Date en le comparant à une valeur de date littérale. Vous pouvez exporter tout type de champ, à l'exception des champs à instances multiples. Pour obtenir des détails sur la façon de préciser une interrogation valide dans le paramètre d’entrée, voir Référence : utilisation des interrogations WQL et directives pour l’exportation de données.
sortie	Objet	Utilisez le format suivant : "output": { "type": "CSV_GZIP", “headers”: true }

Demande d'exemple :

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

Exemple de réponse

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

Obtenir le statut de la tâche d'exportation des données

GET /dataExport

Le point de terminaison 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 à prendre en compte pour la sécurité :

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

Ce point de terminaison retourne les tâches d'exportation de données pour lesquelles l'utilisateur actuel a une autorisation. Lorsque vous récupérez un recouvrement, utilisez les paramètres d’interrogation facultatifs suivants :

Paramètre d'interrogation	Description	Valeur par défaut	Max.
type	La valeur du type détermine les champs de réponse à inclure. full : renvoie toutes les informations sur l’exportation des données. Récapitulatif : renvoie une réponse récapitulative en excluant la liste des résultats de sortie.	récapitulatif
limit	La limite d’entrées de données d’objets incluses dans une seule réponse.	20	1 000
offset	La compensation par rapport au premier objet d'une collection à inclure dans la réponse.	0

Demande d'exemple :

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 de récupération d'information 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 en cours

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

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

Précisez :

L'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}

Le point de terminaison fournit les noms des fichiers de sortie.

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

Éléments à prendre en compte pour la 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

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

POST /dataExport/{id}/cancel

Le point de terminaison facilite l'annulation d'une tâche d'exportation de données précise qui est planifiée ou en cours d'exécution.

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

Éléments à prendre en compte pour la sécurité :

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

Exportation de données Prism : Exécution

Exportation de données Prism : Gérer

L’une des exigences de sécurité suivantes s’applique au tableau à partir duquel vous exportez :

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

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

L'autorisation de lecteur du tableau sur le tableau.

L’autorisation de l’éditeur de tableau sur le tableau.

L’autorisation du propriétaire du tableau sur le tableau.

Demande d'exemple :

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

Exemple de demande d'annulation d'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 à faible priorité et auront une priorité moins élevée que d'autres tâches comme la publication.

Vous ne pouvez pas télécharger les fichiers générés après 7 jours, car les fichiers seront supprimés.

Ces maximums sont définis à titre de clôtures pour optimiser la performance et la fiabilité du système :

Un milliards de rangées par tâche d’exportation.

1 000 colonnes par interrogation.

Demandes de téléchargement simultanés :

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

Si un locataire dépasse sa limite spécifique, vous recevrez la réponse 429 - HAT_TENANT_LIMIT.

Tâches d'exportation simultanées :

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

Toute tâche d'exportation supplémentaire sera automatiquement mise en file d'attente jusqu'à ce que la tâche actuelle soit terminée.

Erreurs communes

Erreurs de validation :

L'entrée Json n'est pas valide.

SQL non valide, champs/nom de tableau non valides, fonctions non prises en charge.

Garderies : nombre de champs > 10 000.

Contraintes de sécurité non respectées.

Erreurs d'exécution

Erreurs du système.

Gaudrails : échec si l’extraction a plus de 1B rangées.

Télécharger les API

Lors du téléchargement, il est toujours recommandé au client HTTP d’avoir de nouveaux essais en raison de problèmes de réseau ou de système non prévus. Une limite de taux est appliquée au nombre de connexions simultanées créées à un locataire et à un serveur. Vous pourriez parfois voir des codes de statut HTTP

429

503

en raison de ces limites mises en application. Il est recommandé au client d’attendre un certain temps et de réessayer la demande.

Éléments à prendre en compte pour la performance

Performance de l’extraction des données :

Le temps d’exécution de l’extraction des données varie en fonction du type de données et du nombre de rangées et de colonnes dans les données.

Le temps d’exécution augmente avec le volume de données.

Télécharger la performance :

Le temps total de téléchargement de tous les fichiers diminue de manière linéaire avec le nombre de processus qui téléchargent les résultats.

La performance du téléchargement peut également être déterminée par la bande passante du réseau et l'emplacement du serveur du locataire.

Étapes : définir le locataire pour l’API REST d’exportation de données Prism

Étapes : exporter des données à partir d’une source de données Prism

Référence : utilisation des interrogations WQL et directives pour l’exportation de données