Concept : API REST d’exportation de données

Administrator Guide

Aperçu

L’ API d’exportation de données dans le service Prism REST offre la aptitude 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.

Les utilisateurs des groupes de sécurité sans contrainte 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 de données .

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

En cours de traitement : Workday exécute actuellement la tâche d'exportation 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 arrêté d’exécuter la tâche d’exportation de données à la demande d’un utilisateur.

Échec : Workday a décelé 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 pouvez uniquement téléchargement 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 raccourcir le temps de 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.

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
Divulgations et rapports prévus par la loi.	Selon un calendrier pouvant varier de jour en année, vous devez extraire de grands volumes de données financières détaillées pour des périodes précises de Workday. Après l’exportation, vous pouvez soumettre les données dans un lac de données d’entreprise ou un outil de production de rapports réglementaires. Grâce à cet outil, vous pouvez facilement mettre en forme et soumettre des informations financières afin de vous conformer à des réglementations strictes.
Analyses avancées, science des données et rapports divers.	Vous devez extraire de grands 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 dans un lac d’entreprise ou une console pour la science des données, où vous pouvez créer des modèles prédictifs pour les sujets suivants, entre autres : Clients et utilisateurs. Les employés. Effectuer des recherches sur le marketing. Le rendement. Produits ou services.
Blocages et archivages réglementaires.	Vous devez respecter les normes réglementaires et de conformité en archiver de cinq à sept années de données financières. Vous devez mettre ces données à la disposition des autorités réglementaires et des auditeurs immédiatement après la demande, conformément aux réglementations et au secteur d'activité applicables.
Demandes d’audit.	Pour effectuer un audit approfondi, vous devez demande l'ensemble des transactions, de l'activité et des métadonnées pour certains soldes sur une période temporelle donnée. Ces données sont nécessaires 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 de base de l'adresse 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 de API de Workday Extend

Pour les applications Workday Extend, utilisez l'adresse URL de base de la API locale de votre société: . Voir Référence : passerelles API Workday Extend API et URL de base d’autorisations sur le site des développeurs.

L'adresse URL de base de la passerelle de API ne comprend pas le nom de locataire.

Éléments à prendre en compte en matière de 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 de
: Contrôle qui peut afficher et annuler les 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 en matière de sécurité :

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

L'une de ces exigences de sécurité pour le tableau que vous exportez à partir de :

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

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

autorisation pour l'affichage des tableaux
sur le tableau.

autorisation d'éditeur de tableau
pour le tableau.

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 indiqué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 de la source de données Prism que vous pouvez téléchargement sur votre ordinateur local.

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

Paramètre du corps du texte	Type	Description
entrée	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. Présente chaque champ que vous souhaitez inclure. Vous pouvez éventuellement 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 de date en le comparant à un champ de date différent. Vous ne pouvez pas filtre un champ de date en le comparant à une valeur de date littérale. Vous pouvez exporter n'importe quel type de champ, à l'exception des champs à instances multiples. Pour plus d'informations sur la façon de préciser une interrogation valide dans le paramètre d'entrée, voir Référence : utilisation de l'interrogation WQL et directives pour l'exportation de données (rubrique en anglais) .
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
 }
}

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

Statut de la tâche d'obtention de l'exportation de données

GET /dataExport

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'un tâche d'exportation .

Éléments à prendre en compte en matière de sécurité :

domaine Prism Data Exportation: 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 dispose d' une autorisation . Lorsque vous récupérez une collection, utilisez les paramètres d’interrogation facultatifs suivants :

Paramètre de requête	Description	Valeur par défaut	Max.
type	La valeur pour le type détermine les champs de réponse à inclure. complet : 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ésumé
limit	Limite d'entrées de données d'objets incluses dans une seule réponse.	20	1 000
offset	La contrepartie du premier objet d'une collection à inclure dans la réponse.	0

Exemple de demande :

GET /dataExport

Exemple de réponse :

La réponse est une collection 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 pour 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 en cours

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

le point de terminaison facilite le téléchargement de 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 .

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

GET /dataExport/{id}

point de terminaison fournit les noms des fichiers de sortie.

Vous pouvez uniquement téléchargement 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 à prendre en compte en matière de sécurité :

domaine Prism Data Exportation: 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 donnée qui est planifiée ou en cours d’exécution.

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

Éléments à prendre en compte en matière de sécurité :

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 de ces exigences de sécurité pour le tableau que vous exportez à partir de :

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

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

autorisation pour l'affichage des tableaux sur le tableau.

autorisation d'éditeur de tableau pour le tableau.

autorisation du propriétaire du tableau sur le tableau.

Exemple de demande :

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 :

Dans la réponse , vous trouverez la tâche d'exportation des données, dont le statut actuel est Annulé dans le 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échargement les fichiers générés après 7 jours, car les fichiers seront supprimés.

Ces maximums sont définis comme garde-fous pour optimiser la performance et la fiabilité du système :

1 milliard de rangées par tâche d'exportation .

1 000 colonnes par requête.

Demandes de téléchargement simultanées :

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

Si un locataire dépasse sa limite, vous réceptionner une réponse 429 - HIT_ si 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 locataire.

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

Erreurs courantes

Erreurs de validation :

Le code JSON d'entrée n'est pas valide.

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

Gardes : Nombre de champs > 10 000.

Les contraintes de sécurité ne sont pas respectées.

Erreurs d'exécution

Erreurs du système.

Gaudra : Échec de l’extraction si l’extraction comportait plus de 1 milliard de rangées.

Télécharger les API

Lors du téléchargement, il est toujours recommandé au client HTTP de faire une nouvelle tentative en raison de problèmes imprévus du réseau ou du système. Une limite de taux s’applique 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. Nous recommandons au client d'attendre un certain temps avant de relancer la demande .

Éléments à prendre en compte pour le rendement

Performance d’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.

Performance de téléchargement :

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

La performance de téléchargement peut également être influencée par la bande passante du réseau et 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