Passa al contenuto principale
Documentazione
Documentazione
Administrator Guide
Ultimo aggiornamento: 2025-11-14
Concetto: API REST per l'esportazione dei dati

Concetto: API REST per l'esportazione dei dati

Panoramica

L' API di esportazione dei dati nel servizio REST di Prism offre la possibilità di esportare dati da origini dati Prism supportate da tabella su larga scala.

Funzionalità principali

  • Creare un job di esportazione dati per esportare i dati da origine dati Prism supportata da tabella .
  • Annullare un job di esportazione dati specifico . Lo stato job di esportazione dei dati deve essere Pianificato o In esecuzione.
    • Gli utenti dei gruppi di sicurezza senza vincoli possono visualizzare e annullare tutti i job di esportazione dei dati.
    • Gli utenti di un gruppo di sicurezza self service possono visualizzare e annullare solo i job di esportazione dati creati.
  • Controllare lo stato del job di esportazione dei dati .
    • Pianificato: il Workday ha pianificato l'esecuzione del job di esportazione dei dati .
    • Elaborazione in corso: Workday sta eseguendo il job di esportazione dei dati .
    • Workday riuscita: il job di esportazione dei dati è stato completato e creato uno o più file di output contenenti i dati esportati.
    • Annullato: Workday' esecuzione del job di esportazione dei dati è stata interrotta su richiesta di un utente.
    • Non riuscito: Workday è verificato un errore durante il tentativo di eseguire il job di esportazione dei dati .
  • Scaricare i file di output contenenti i dati esportati.
    • È possibile download solo i file di output consentiti dal profilo di sicurezza dell'utente corrente.
    • È possibile download i file in sequenza o in parallelo. È possibile ridurre il tempo obbligatorio per download tutti i file di output scaricandoli in parallelo.
    • Le performance del download dipendono da:
      • Il numero di file.
      • Il numero di download paralleli.
      • La larghezza di banda di rete tra il client API e il server Workday . Esempio: se il client si trova in un'area geografica diversa da quella del server, il tempo necessario per download i file aumenterà.

Casi d'uso

Caso d'uso
Descrizione
Informativa e reportistica legale
In una pianificazione che può intervallo da giornaliera a annuale, è necessario estrarre grandi volumi di dati finanziari dettagliati per periodi specifici da Workday. Dopo l'esportazione, è possibile inoltrare i dati a un data lake aziendale o a uno strumento di reportistica normativo. Lo strumento semplifica la formattazione e l'inoltro delle informative finanziarie per conformarsi a normative rigorose.
Analisi avanzate, data science e reportistica varie.
È necessario estrarre dal Workday volumi elevati di dati operativi e finanziari dettagliati per periodi specifici . Dopo l'esportazione, è possibile inoltrare i dati a un lago aziendale o a un workbench di data science, dove è possibile creare modelli predittivi per i seguenti argomenti, tra gli altri:
  • Clienti e utenti
  • Dipendenti
  • Ricerche di mercato
  • Performance
  • Prodotti o servizi
Blocchi normativi e archivi
È necessario soddisfare gli standard normativi e di conformità archiviando da 5 a 7 anni di dati finanziari. È necessario rendere immediatamente disponibili i dati alle autorità di regolamentazione e ai revisori su richiesta, in conformità con le normative e il settore applicabili.
Controllare le richieste.
Per condurre un controllo approfondito, è necessario richiedere tutte le transazioni, le attività e i metadati per determinati saldi in un periodo di tempo specificato . Questi dati sono obbligatorio su base mensile, trimestrale e annuale, nonché per gli anni precedenti. È necessario esportare un numero elevato di dati nel database di controllo .

Percorso base URL

Percorso base del tenant 
https://{hostname}/api/prismAnalytics/{version}/{tenantname}/dataExport
Esempio di creazione di un job di esportazione dati : 
https://yourTenantHostName.com/api/prismAnalytics/v3/<TENANT_NAME>/dataExport
Percorso di base del gateway API Workday Extend
Per le app Workday Extend, utilizzare l'URL di base API Gateway regionale azienda. Consultare Riferimenti: Gateway API Workday Extend e URL di base di autorizzazione nel sito per gli sviluppatori.
L'URL di base API Gateway non include il nome del tenant.

Considerazioni sulla sicurezza

I seguenti domini nell'area area funzionale Prism :
  • Prism Data Export: Execute
     : controlla chi può creare job di esportazione dati.
  • Prism Data Export: Manage
     : controlla chi può visualizzare e annullare i job di esportazione dei dati.

Creazione job di esportazione dati

Il
POST /dataExport
 L'endpoint facilita la creazione di un job di esportazione dei dati .
Considerazioni sulla sicurezza:
  • dominio
    Prism Data Export: Execute
     nell'area area funzionale Prism Analytics .
  • Uno dei seguenti requisiti di sicurezza per la tabella da cui si esegue l'esportazione:
    • dominio
      Prism: Tables Manage
       nell'area area funzionale Prism Analytics .
    • dominio
      Prism: Tables Owner Manage
       nell'area area funzionale Prism Analytics .
    • autorizzazione
      Visualizzatore tabelle
       per la tabella.
    • autorizzazione
      Editor tabelle
       per la tabella.
    • autorizzazione
      Proprietario tabella
       per la tabella.
Utilizzare questo metodo per creare un job di esportazione dati per origine dati Prism specificata.
Quando si crea un job di esportazione dati , il Workday genera uno o più file contenenti dati origine dati Prism che è possibile download nel computer locale.
Nel corpo della richiesta, fornire un valore per i seguenti parametri:
Parametro del corpo
Tipo
Descrizione
input
Oggetto
Includere una query WQL che specifichi tutti i campi da esportare da origine dati Prism .
Utilizzare questo formato: 
"input": {
"query": " WQL_Query ",
"type": "SQL"
}
Quando si scrive la query WQL:
  • Utilizzare l'alias WQL origine dati Prism e ogni campo.
  • Elencare tutti i campi che si desidera includere. Facoltativamente, è possibile rinominare un campo utilizzando l'operatore AS.
  • (Facoltativo) È possibile filtro i record utilizzando una clausola WHERE. È possibile filtro un campo Data confrontandolo con un campo Data diverso. Non è possibile filtro un campo Data confrontandolo con un valore di data letterale.
  • È possibile esportare qualsiasi tipo di campo ad eccezione dei campi a istanza multipla.
Per informazioni dettagliate su come specificare una query valida nel parametro di input, consultare Riferimenti: Utilizzo delle query WQL e linee guida per l'esportazione dei dati .
output
Oggetto
Utilizzare questo formato: 
"output": {
"type": "CSV_GZIP",
“headers”: true
}
Richiesta di esempio:
POST /dataExport
Corpo della richiesta di esempio:
{
 "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
 }
}
Risposta di esempio
{
 "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"
}

Stato job esportazione recupero dati

Il
GET /dataExport
 endpoint facilita il recupero di tutti i job di esportazione dei dati.
Il
GET /dataExport/{id}
 facilita il recupero di un job di esportazione .
Considerazioni sulla sicurezza:
dominio
Prism Data Export: Manage
 nell'area area funzionale Prism Analytics .
Questo endpoint restituisce i job di esportazione dati per i quali l'utente corrente dispone autorizzazione . Quando si recupera una raccolta, utilizzare i seguenti parametri di query facoltativi:
Parametro query
Descrizione
Predefinito
Massimo
type
Il valore per il tipo determina quali campi risposta includere.
  • full: restituisce tutte le informazioni di esportazione dei dati.
  • Riepilogo: restituisce una risposta riepilogativa escludendo l'elenco dei risultati di output.
riepilogo
limit
Il limite di voci di dati oggetto incluse in una singola risposta.
20
1.000
offset
spostamento rispetto al primo oggetto di una raccolta da includere nella risposta.
0
Richiesta di esempio:
GET /dataExport
Risposta di esempio:
La risposta è una raccolta di job di esportazione dati, in formato JSON .
Questa risposta di esempio mostra un solo job di esportazione dati .
{
 "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"
  },
  ...
 ]
}
Richiesta di esempio per recuperare informazioni sul job di esportazione dati con ID = b1bd0e1ac5d410001193bf9340050000:
GET /dataExport/b1bd0e1ac5d410001193bf9340050000
Risposta di esempio: 
{
 "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"
}

Download dei file di output in corso

Il
GET /dataExport/{id}/results/{fileName}
 endpoint facilita il download dei file di output da un job di esportazione dei dati.
Specificare:
  • ID del job di esportazione dati .
  • Nome del file di output del job di esportazione dati .
Il
GET /dataExport/{id}
 endpoint fornisce i nomi dei file di output.
È possibile download solo i file di output consentiti dal profilo di sicurezza dell'utente corrente. È possibile download i file in sequenza o in parallelo.
Considerazioni sulla sicurezza:
dominio
Prism Data Export: Manage
 nell'area area funzionale Prism Analytics .
Richiesta di esempio per download il file denominato 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

Annullamento di un job di esportazione dati

Il
POST /dataExport/{id}/cancel
 L'endpoint facilita l'annullamento di un job di esportazione di dati specifico pianificato o in esecuzione.
È possibile annullare solo i job di esportazione dati consentiti dal profilo di sicurezza dell'utente corrente.
Considerazioni sulla sicurezza:
Uno dei seguenti domini nell'area area funzionale Prism Analytics :
  • Prism Data Export: Execute
  • Prism Data Export: Manage
Uno dei seguenti requisiti di sicurezza per la tabella da cui si esegue l'esportazione:
  • dominio
    Prism: Tables Manage
     nell'area area funzionale Prism Analytics .
  • dominio
    Prism: Tables Owner Manage
     nell'area area funzionale Prism Analytics .
  • autorizzazione Visualizzatore tabelle per la tabella.
  • autorizzazione Editor tabelle per la tabella.
  • autorizzazione Proprietario tabella per la tabella.
Richiesta di esempio:
È necessario includere una stringa JSON vuota {} nel corpo della richiesta per questo metodo.
Richiesta di esempio per annullare un job di esportazione dati con ID b1bd0e1ac5d4100018d18abc4ea00000:
POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel
Risposta di esempio:
La risposta contiene il job di esportazione dei dati con lo stato corrente Annullato in 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"
}

Limitazioni

  • Gli impieghi di esportazione sono impieghi a bassa priorità e avranno una priorità inferiore rispetto ad altri impieghi come la pubblicazione.
  • Non è possibile download i file generati dopo 7 giorni perché i file verranno eliminati.
  • Questi valori massimi sono impostati come guardrail per ottimizzare le prestazioni e l'affidabilità del sistema:
    • 1 miliardo di righe per job di esportazione .
    • 1000 colonne per query.
  • Richieste download simultanee:
    • Se il limite di sistema viene raggiunto, ricevere una risposta 503 - HIT_SERVER_LIMIT .
    • Se un tenant supera il limite specifico, ricevere una risposta 429 - HIT_TENANT_LIMIT .
  • Job di esportazione simultanei:
    • È possibile eseguire un solo job di esportazione alla volta per utente o tenant.
    • Eventuali job di esportazione aggiuntivi verranno automaticamente accodati fino al completamento del job corrente.

Errori comuni

Errori di convalida:
  • JSON di input con formato errato.
  • SQL con formato errato, campi/nome tabella non valido , funzioni non supportate.
  • Guardrail: numero di campi > 10000.
  • Vincoli di sicurezza non soddisfatti.
Errori di esecuzione
  • Errori di sistema
  • Gaudrails: non riesce se l'estrazione include più di 1 miliardo di righe.
Scaricare le API
  • Durante il download, è sempre consigliabile che il client HTTP esegua nuovi tentativi a causa di problemi di rete o di sistema imprevisti. È prevista una limitazione della tariffa al numero di connessioni simultanee create a un tenant e a un server. Occasionalmente potrebbero essere visualizzati codici di stato HTTP
    429
     o
    503
     a causa di questi limiti imposti. Si client di attendere qualche istante e riprovare la richiesta.

Considerazioni sulle performance

Performance di estrazione dei dati:
  • Il tempo di esecuzione dell'estrazione dei dati varia in base al tipo di dati e al numero di righe e colonne nei dati.
  • Il tempo di esecuzione aumenta con il volume dei dati.
Scarica performance:
  • Il tempo totale download per file di tutte le dimensioni diminuisce in modo lineare con il numero di processi che download i risultati.
  • Le performance del download possono anche essere influenzate dalla larghezza di banda della rete e sede del server tenant .