Workiva Support Center

Einführung

Diese Anleitung zeigt Ihnen, wie Sie die Workiva API verwenden, um eine Datei in Wdata zu importieren.

Wenn Sie den Import einer Datensatzdatei in eine Wdata-Tabelle automatisieren möchten, aber keine Ketten mit dem Workiva-Konnektor verwenden möchten, können Sie stattdessen die Workiva-API direkt von Ketten mit dem HTTP-Konnektor oder von jeder externen Software aus nutzen, die in der Lage ist, mit einer mit OAuth 2.0 gesicherten REST-API zu interagieren.

Ersteinrichtung

Zunächst müssen Sie eine API-Grant erstellen, die eine Client-ID und ein Geheimnis erzeugt. Dies kann von jedem Workiva-Benutzerkonto mit mindestens den Rechten "Workspace Owner" oder "Org Security Administrator" durchgeführt werden, indem man den Anweisungen auf folgt, die hier zur Verfügung gestellt werden.

Authentifizierung

Sobald Sie die API-Grant korrekt eingerichtet haben, besteht der erste Schritt in der Kommunikation mit der API darin, sich zu authentifizieren. Dabei wird der Industriestandard oauth 2.0 bearer token exchange verwendet und erfordert einen POST-Aufruf, wie in den Anweisungen von unter beschrieben.

Importieren

Es sind zwei Schritte erforderlich, um Daten in eine Wdata-Tabelle mit Hilfe der Workiva-API zu laden:

1. Laden Sie die Datei in die von Ihnen gewählte Wdata-Tabelle (https://developers.workiva.com/wdata-v1/wdata-uploadfile/) hoch. Dadurch wird Ihre Datei als Datensatz in der Tabelle mit dem Status "staged" hinzugefügt. Daher werden die neuen Daten zu diesem Zeitpunkt nicht in Abfragen oder Ansichten der Tabelle angezeigt.
2. Importieren Sie die Datei (https://developers.workiva.com/wdata-v1/wdata-importfile/). Die "Id", die Sie in der Antwort auf den Upload erhalten, kann dann in der Eigenschaft "fileId" verwendet werden, um die Datei zu importieren und, falls erfolgreich, die Daten in die Tabelle einzufügen und sie in Abfragen und Ansichten verfügbar zu machen.

Mit Beispielen

Schlüssel

In den folgenden Beispielen sind die URLs für die EU-Plattform angegeben; für die USA oder APAC sollte das "eu" in "app" bzw. "apac" geändert werden.

1. Hochladen

   Laden Sie die Datei in die von Ihnen gewählte Wdata-Tabelle hoch: https://developers.workiva.com/wdata-v1/wdata-uploadfile/

   Beispiel:

   POST: {baseURL}/api/v1/file Kopfzeilen: Content-Type: multipart/form-data; boundary="boundary" Body: --boundary Content-Disposition: form-data; name="delimiter" Semikolon --boundary Content-Disposition: form-data; name="tableId" {tableId} --boundary Content-Disposition: form-data; name="file"; filename="filename.csv" Content-Type: text/plain fruit;quantity Apfel;133 Aprikose;175 Avocado;182 Banane;187 Heidelbeere;160 Brombeere;178 Schwarze Johannisbeere;102 Heidelbeere;156 Johannisbeere;194 Kirsche;182 Cherimoya;169 Clementine;165 Dattel;112 Zwetschge;164 Durian;157 Aubergine;189 --boundary-- 

2. Importieren

   Verwenden Sie dann die "Id", die Sie in der Antwort erhalten, als "fileId", um die Datei folgendermaßen zu importieren: https://developers.workiva.com/wdata-v1/wdata-importfile/

   Beispiel:

   POST: {baseURL}/api/v1/table/{tableId}/import Headers: Content-Type: application/json Body: { "delimiter":";", "fileId":"{fileId}" } 

   Hinweis: Mit dieser Anfrage wird nur der Datei-Import eingeleitet, und die Antwort wird gesendet, ohne dass auf den Erfolg oder Misserfolg der Anfrage gewartet wird.

Status prüfen

Es ist nicht erforderlich, aber in den meisten Anwendungsfällen eine gute Praxis, zu bestätigen und zu protokollieren/zu melden, ob der Datei-Import erfolgreich war oder nicht. Dies kann mit den folgenden zwei GET-Anfragen geschehen.

1. Um zu bestätigen, dass der Dateiimport-Endpunkt die Datei erfolgreich importiert hat, sollten Sie den Endpunkt Retrieve a single file für denselben {fileId} aus dem Import verwenden (abfragen) und dann die Antwort für Ihre Datei überprüfen.

   Beispiel:

   GET: {baseURL}/api/v1/file/{fileId} Kopfzeilen: Inhalt-Typ: application/json 

2. Wenn der Status "IMPORTING" lautet, ist der Import noch im Gange, so dass Sie den Prozess für eine gewisse Zeit unterbrechen sollten, bevor Sie die vorherige Anfrage (Poll) wiederholen.
3. Der Status "IMPORTIERT" bedeutet, dass die Datei erfolgreich importiert wurde.
4. Wenn der Status Ihrer Datei immer noch "STAGED" lautet und die "numErrors" größer als Null ist, ist der Import der Datei fehlgeschlagen und Sie können den Endpunkt Retrieve errors verwenden, um die aufgetretenen Fehlermeldungen abzurufen.

Fehlersuche

Wenn Sie keine Anfragen an die API stellen können (Fehler 401 Unauthorized)

• Überprüfe, ob du den korrekten URL-Präfix für den Ort deines Workiva Workspace verwendet hast.
• Vergewissern Sie sich, dass Sie die richtige Client-ID und das richtige Geheimnis in Ihrer Anfrage verwenden, ohne Leerzeichen davor oder danach.

Die Authentifizierung funktioniert, die nachfolgenden Anfragen jedoch nicht (404- oder 500-Fehler)

• Überprüfen Sie, ob der in der von Ihnen erstellten API-Berechtigung angegebene Benutzer Zugriff auf die angegebene Wdata-Tabellen-ID hat.
• Überprüfen Sie, ob sich die Tabelle Wdata im selben Arbeitsbereich wie die API-Erlaubnis befindet.
• Stellen Sie sicher, dass Sie die richtigen Datei-IDs ohne Leerzeichen davor oder danach verwenden.
• Überprüfen Sie, ob Ihre Kopfzeilen, insbesondere der "Content-Type", mit der Dokumentation übereinstimmen.

Meine Datei wird erfolgreich hochgeladen, aber beim Importieren treten Fehler auf

• Prüfen Sie, ob Sie das richtige Trennzeichen angegeben haben.
• Vergewissern Sie sich, dass die Daten in Ihrer Datei in einem flachen Dateiformat vorliegen, mit den Kopfzeilen in Zeile 1 aus Spalte A und den Daten in Zeile 2 aus Spalte A.
• Achten Sie darauf, dass die Anzahl der Kopfspalten mit der Anzahl der Datenspalten übereinstimmt.
• Überprüfen Sie, ob die Datentypen mit denen übereinstimmen, die in der Einrichtung der Wdata-Tabelle angegeben wurden.
• Abrufen von Fehlern im Zusammenhang mit dem Datei-Import zur weiteren Fehlersuche