Konzept: REST-API für Datenexport

Administrator Guide

Übersicht

Die Datenexport- API (Application Programming Interface) im Prism-REST- Service bietet die Fertigkeit , Daten aus tabellengestützten Prism-Datenquellen in großem Umfang zu exportieren.

Hauptfunktionen

Erstellen Sie einen Job , um Daten aus einer tabellengestützten Prism- Datenquelle zu exportieren.

Brechen Sie einen bestimmten Datenexportjob () ab. Der Status des Job muss Geplant oder Wird ausgeführt lauten.

Benutzer in uneingeschränkten Sicherheitsgruppen können alle Datenexportjobs anzeigen und abbrechen.

Benutzer in einer Selfservice- Sicherheitsgruppe können nur die von ihnen erstellten Datenexportjobs anzeigen und abbrechen.

Prüfen Sie den Status des Job.

Geplant: Workday hat die Ausführung des Job "" geplant.

Wird verarbeitet: Workday führt derzeit den Job"" aus.

Erfolgreich: Workday hat den Job abgeschlossen und mindestens eine Ausgabedatei mit den exportierten Daten erstellt.

Abgebrochen: Workday hat die Ausführung des Job auf Anforderung; Antrag eines Benutzers beendet.

Fehlgeschlagen: Beim Versuch, den Job auszuführen, ist ein Fehler aufgetreten.

Laden Sie die Ausgabedateien mit den exportierten Daten herunter.

Sie können nur die Ausgabedateien Download , die das Sicherheitsprofil des aktuellen Benutzers zulässt.

Sie können Dateien entweder sequenziell oder parallel Download . Sie können die für das Download aller Ausgabedateien erforderlich Zeit verkürzen, indem Sie sie parallel herunterladen.

Die Download-Performance hängt von folgenden Faktoren ab:

Anzahl der Dateien.

Die Anzahl der parallelen Downloads.

Die Netzwerkbandbreite zwischen dem API (Application Programming Interface) Client und dem Workday Server. Beispiel: Wenn sich der Client in einer anderen geografischen Region befindet als der Server, dauert das Download der Dateien länger.

Anwendungsfälle

Anwendungsfall	Beschreibung
Angaben und gesetzliches Reporting.	In einem Zeitplan, der von täglich bis jährlich Bereich kann, müssen Sie eine große Anzahl detaillierter Finanzdaten für bestimmte Perioden aus Workday extrahieren. Nach dem Export können Sie die Daten an einen Unternehmens-Data Lake oder ein regulatorisches Reporting-Tool übermitteln. Das Tool erleichtert Ihnen das Formatieren und Übermitteln finanzieller Angaben, um strenge Vorschriften einzuhalten.
Erweiterte Analysen, Data Science und sonstiges Reporting	Sie müssen große Mengen detaillierter operativer und finanzieller Daten für bestimmte Perioden aus Workday extrahieren. Nach dem Export können Sie die Daten an einen Enterprise Lake oder eine Data Science Workbench übermitteln, wo Sie unter anderem für folgende Themen prädiktive Modelle erstellen können: Kunden und Benutzer. Mitarbeiter. Marketingforschung. Performance. Produkte oder Services
Regulatorische Sperren und Archivierung	Sie müssen regulatorische und Compliance-Standards erfüllen, indem Sie Finanzdaten aus 5 bis 7 Jahren archivieren. Sie müssen diese Daten gemäß den geltenden Vorschriften und der Branche sofort nach Anforderung; Antrag für die Aufsichtsbehörden und Auditoren zur Verfügung stellen.
Auditanforderungen.	Um ein gründliches Audit durchzuführen, müssen Sie alle Transaktionen, Aktivitäten und Metadaten für bestimmte Salden über einen bestimmten Zeitperiode Anforderung; Antrag . Diese Daten sind monatlich, vierteljährlich und jährlich sowie für vorherige Jahre erforderlich . Sie müssen eine große Anzahl von Daten in Ihre Datenbank exportieren.

URL-Basispfad

Basispfad für Mandanten

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

Beispiel zum Erstellen eines Job:

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

Basispfad für Workday Extend API (Application Programming Interface) Gateway

Verwenden Sie für Workday Extend-Apps die regionale Basis-URL des API (Application Programming Interface) Gateway für Ihr Unternehmen. Siehe Referenz: Workday Extend API (Application Programming Interface) Gateways und Authorization Base URLs auf der Entwicklersite.

Die Basis-URL für das API (Application Programming Interface) Gateway enthält nicht den Mandantenname "".

Überlegungen zur Sicherheit

Folgende Domänen im funktionaler Bereich„Prism“:

Prism-Datenexport: Ausführen
: Steuert, wer Datenexportjobs erstellen kann.

Prism-Datenexport: Verwalten
: Steuert, wer Datenexportjobs anzeigen und abbrechen kann.

Datenexportjob wird erstellt

Die

POST /dataExport

Endpunkt ermöglicht das Erstellen eines Job.

Überlegungen zur Sicherheit:

Domäne Prism Data Export: Execute
im funktionaler Bereich „Prism Analytics“ .

Eine der folgenden Sicherheitsanforderungen für Tabelle , aus denen Sie exportieren:

Domäne Prism: Tables Manage
im funktionaler Bereich „Prism Analytics“ .

Domäne Prism: Tables Owner Manage
im funktionaler Bereich „Prism Analytics“ .

Berechtigung Tabellenansicht
für die Tabelle.

Berechtigung Tabelleneditor
für die Tabelle "".

Berechtigung Tabelleneigentümer
für die Tabelle.

Verwenden Sie diese Methode, um einen Job für eine angegebene Prism- Datenquelle zu erstellen.

Wenn Sie einen Job erstellen, generiert Workday eine oder mehrere Dateien mit Daten aus der Prism Datenquelle , die Sie auf Ihren lokalen Computer Download können.

Geben Sie im Anforderung; Antrag einen Wert für folgende Parameter an:

Textparameter	Art	Beschreibung
Eingabe	Objekt	Schließen Sie eine WQL-Abfrage ein, die alle Felder angibt, die aus einer Prism Datenquelle exportiert werden sollen. Verwenden Sie folgendes Format: "input": { "query": " WQL_Query ", "type": "SQL" } Beim Schreiben der WQL-Abfrage: Verwenden Sie den WQL-Alias der Prism- Datenquelle und jedes Feld. Listen Sie alle Felder auf, die Sie einschließen möchten. Optional können Sie ein Feld mit dem Operator AS umbenennen. (Optional) Sie können die Datensätze mit einer WHERE-Klausel Filter . Sie können ein Datumsfeld Filter , indem Sie es mit einem anderen Datumsfeld vergleichen. Sie können ein Datumsfeld nicht Filter , indem Sie es mit einem Literal-Datumswert vergleichen. Sie können jede Feldart außer Multiinstanzfeldern exportieren. Ausführliche Informationen zur Angabe einer gültigen Abfrage im Eingabeparameter finden Sie unter Referenz: Verwendung von WQL-Abfragen und Richtlinien für den Datenexport .
ausgegeben	Objekt	Verwenden Sie folgendes Format: "output": { "type": "CSV_GZIP", “headers”: true }

Beispielanforderung:

POST /dataExport

Beispielanforderungstext:

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

Beispielantwort

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

Rufen Sie den Status des Datenexportjobs ab

Die

GET /dataExport

Der Endpunkt ermöglicht den Abruf aller Datenexportjobs.

Die

GET /dataExport/{id}

ermöglicht das Abrufen von 1 Job().

Überlegungen zur Sicherheit:

Domäne Prism Data Export: Manage
im funktionaler Bereich „Prism Analytics“ .

Dieser Endpunkt gibt die Datenexportjobs zurück, für die der aktuelle Benutzer eine Berechtigung hat. Verwenden Sie beim Abrufen einer Sammlung die folgenden optionalen Abfrageparameter:

Abfrageparameter	Beschreibung	Standard	Maximum
type	Der Wert für "type" bestimmt, welche Antwort enthalten sein sollen. Full: Gibt alle Informationen zum Datenexport zurück. Zusammenfassung: Gibt eine zusammengefasste Antwort zurück, indem die Liste der Ausgabeergebnisse ausgeschlossen wird.	Zusammenfassung
limit	Der Grenzwert von Objektdateneingaben in einer einzelnen Antwort.	20	1.000
offset	Der Gegenbuchung zum ersten Objekt in einer Sammlung, das in die Antwort "" aufgenommen werden soll.	0

Beispielanforderung:

GET /dataExport

Beispielantwort:

Die Antwort ist eine Sammlung von Datenexportjobs im JSON Format.

Diese Antwort zeigt nur einen Job"" an.

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

Anforderung; Antrag zum Abrufen von Informationen zum Job mit der ID = b1bd0e1ac5d410001193bf9340050000:

GET /dataExport/b1bd0e1ac5d410001193bf9340050000

Beispielantwort:

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

Ausgabedateien werden heruntergeladen

Die

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

Der Endpunkt "" ermöglicht das Herunterladen von Ausgabedateien aus einem Job ().

Geben Sie Folgendes an:

Die ID des Job"".

Der Name der Ausgabedatei aus dem Job "".

Die

GET /dataExport/{id}

Endpunkt liefert die Namen der Ausgabedateien.

Sie können nur die Ausgabedateien Download , die das Sicherheitsprofil des aktuellen Benutzers zulässt. Sie können Dateien entweder sequenziell oder parallel Download .

Überlegungen zur Sicherheit:

Domäne Prism Data Export: Manage
im funktionaler Bereich „Prism Analytics“ .

Anforderung; Antrag zum Download der Datei "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

Wenn ein Datenexportjob abgebrochen wird

Die

POST /dataExport/{id}/cancel

Der Endpunkt ermöglicht das Abbrechen eines bestimmten Job , der geplant ist oder ausgeführt wird.

Sie können nur Datenexportjobs abbrechen, die das Sicherheitsprofil des aktuellen Benutzers zulässt.

Überlegungen zur Sicherheit:

Eine der folgenden Domänen im funktionaler Bereich „Prism Analytics“ :

Prism-Datenexport: Ausführen

Prism-Datenexport: Verwalten

Eine der folgenden Sicherheitsanforderungen für Tabelle , aus denen Sie exportieren:

Domäne Prism: Tables Manage
im funktionaler Bereich „Prism Analytics“ .

Domäne Prism: Tables Owner Manage
im funktionaler Bereich „Prism Analytics“ .

Berechtigung Tabellenansicht für die Tabelle.

Berechtigung Tabelleneditor für die Tabelle "".

Berechtigung Tabelleneigentümer für die Tabelle.

Beispielanforderung:

Sie müssen eine leer JSON Zeichenfolge "{}" in den Anforderung; Antrag für diese Methode aufnehmen.

Anforderung; Antrag zum Abbrechen eines Job mit der ID b1bd0e1ac5d4100018d18abc4ea00000:

POST /dataExport/b1bd0e1ac5d4100018d18abc4ea00000/cancel

Beispielantwort:

Die Antwort enthält den Job einschließlich des aktuellen Status "Abgebrochen" im JSON Format.

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

Einschränkungen

Exporttätigkeiten sind Tätigkeiten mit niedriger Priorität und haben eine niedrigere Rangfolge als andere Tätigkeiten wie Veröffentlichung.

Sie können die generierten Dateien nach 7 Tagen nicht mehr Download , da die Dateien gelöscht werden.

Die folgenden Maximalwerte werden als Richtlinien festgelegt, um die Performance und Zuverlässigkeit des Systems zu optimieren:

1 Milliarden Zeilen pro Job.

1.000 Spalten pro Abfrage.

Parallele Download Anforderungen:

Wenn das Systemlimit erreicht wird, eingehen Sie die Antwort 503 - HIT_SERVER_LIMIT .

Wenn ein Mandant seinen spezifischen Grenzwert überschreitet, eingehen Sie die Antwort 429 - HIT_TENANT_LIMIT .

Parallele Exportjobs:

Pro Benutzer oder Mandant kann jeweils nur ein Job ausgeführt werden.

Alle weiteren Exportjobs werden automatisch in die Warteschlange gestellt, bis der aktuelle Job abgeschlossen ist.

Häufige Fehler

Validierungsfehler:

Nicht wohlgeformte JSON-Eingaben.

Nicht wohlgeformtes SQL, ungültig Felder/Tabellenname, nicht unterstützte Funktionen.

Leitplanken: Anzahl Felder > 10.000.

Sicherheitsbeschränkungen nicht erfüllt.

Ausführungsfehler

Systemfehler.

Gaudrails: Schlägt fehl, wenn die Extraktion mehr als 1 Mrd. Zeilen enthält.

APIs herunterladen

Beim Herunterladen wird es für den HTTP- Client immer empfohlen, aufgrund unvorhergesehener Netzwerk- oder Systemprobleme erneut zu versuchen. Es gibt eine Ratenbeschränkung für die Anzahl der gleichzeitigen Verbindungen, die zu einem Mandant und einem Server erstellt werden. Möglicherweise werden gelegentlich HTTP-Statuscodes angezeigt

429

oder

503

aufgrund dieser erzwungenen Grenzwerte. Es wird dem Client empfohlen, einige Zeit zu warten und es erneut zu versuchen.

Überlegungen zur Performance

Performance der Datenextraktion:

Die Ausführungszeit für die Datenextraktion hängt vom Datentyp sowie der Anzahl der Zeilen und Spalten in den Daten ab.

Die Ausführungszeit steigt mit dem Band .

Download-Performance:

Die gesamte Download Zeit verringert sich für alle Dateigrößen linear mit der Anzahl der Prozesse, die die Ergebnisse Download .

Die Download-Performance kann auch von der Netzwerkbreite und dem Standort des Mandant -Servers beeinflusst werden.

Schritte: Mandanten für die REST-API für den Prism-Datenexport einrichten

Schritte: Daten aus einer Prism-Datenquelle exportieren

Referenz: Verwendung von WQL-Abfragen und Richtlinien für den Datenexport