Centrum wsparcia Workiva

Wprowadzenie

W tym przewodniku dowiesz się, jak używać API Workiva do importowania pliku do Wdata.

Jeśli chcesz zautomatyzować import pliku zestawu danych do tabeli Wdata, ale nie chcesz używać łańcuchów z łącznikiem Workiva, możesz zamiast tego użyć interfejsu API Workiva bezpośrednio z łańcuchów z łącznikiem HTTP lub z dowolnego zewnętrznego oprogramowania, które może współpracować z interfejsem API REST zabezpieczonym protokołem OAuth 2.0.

Konfiguracja początkowa

Najpierw musisz utworzyć zezwolenie API, które wygeneruje identyfikator klienta i tajny klucz. Można to zrobić z poziomu dowolnego konta użytkownika Workiva posiadającego co najmniej uprawnienia „Właściciela obszaru roboczego” lub „Administratora zabezpieczeń organizacji”, postępując zgodnie z instrukcjami podanymi tutaj.

Uwierzytelnianie

Po poprawnym skonfigurowaniu uprawnień API pierwszym krokiem w komunikacji z API będzie uzyskanie uwierzytelnienia. W tym przypadku używana jest standardowa branżowa wymiana tokenów okaziciela OAuth 2.0 i wymagane jest wywołanie POST, zgodnie ze szczegółowymi instrukcjami podanymi tutaj .

Importuj

Aby załadować dane do tabeli Wdata przy użyciu interfejsu API Workiva, należy wykonać dwa wymagane kroki:

1. Prześlij plik do wybranej tabeli Wdata (https://developers.workiva.com/wdata-v1/wdata-uploadfile/). Spowoduje to dodanie pliku jako zbioru danych do tabeli ze statusem „staged”. W związku z tym nowe dane nie pojawią się na tym etapie w żadnych zapytaniach ani widokach tabeli.
2. Importuj plik (https://developers.workiva.com/wdata-v1/wdata-importfile/). „Identyfikator” otrzymany w odpowiedzi na przesłanie pliku można następnie wykorzystać we właściwości „fileId” w celu zaimportowania pliku, a w przypadku powodzenia — dodania danych do tabeli i udostępnienia ich w zapytaniach i widoku.

Z przykładami

Klucz

W poniższych przykładach podano adresy URL dla platformy UE; w przypadku platformy USA lub regionu Azji i Pacyfiku „eu” należy zmienić odpowiednio na „app” lub „apac”.

1. Prześlij

   Prześlij plik do wybranej tabeli Wdata: https://developers.workiva.com/wdata-v1/wdata-uploadfile/

   Przykład:

   POST: {baseURL}/api/v1/file Nagłówki: Content-Type: multipart/form-data; boundary="boundary" Treść: --boundary Content-Disposition: form-data; name="delimiter" średnik --boundary Content-Disposition: form-data; name="tableId" {tableId} --boundary Content-Disposition: form-data; name="file"; filename="filename.csv" Content-Type: text/plain fruit;quantity Apple;133 Morela;175 Awokado;182 Banan;187 Borówka;160 Jeżyna;178 Czarna porzeczka;102 Jagoda;156 Porzeczka;194 Wiśnia;182 Cherimoya;169 Klementynka;165 Daktyl;112 Damson;164 Durian;157 Bakłażan;189 --boundary-- 

2. Importuj

   Następnie użyj otrzymanego w odpowiedzi identyfikatora „Id” jako identyfikatora „fileId”, aby zaimportować plik w następujący sposób: https://developers.workiva.com/wdata-v1/wdata-importfile/

   Przykład:

   POST: {baseURL}/api/v1/table/{tableId}/import Nagłówki: Typ zawartości: application/json Treść: { "delimiter":";", "fileId":"{fileId}" } 

   Uwaga: To żądanie tylko inicjuje import pliku, a odpowiedź jest wysyłana bez oczekiwania na jego powodzenie lub niepowodzenie.

Sprawdź status

Nie jest to wymagane, ale w większości przypadków dobrym rozwiązaniem będzie potwierdzenie, zarejestrowanie i zgłoszenie, czy import pliku zakończył się powodzeniem, czy nie. Można to zrobić za pomocą dwóch następujących żądań GET.

1. Aby potwierdzić, że punkt końcowy pliku importu pomyślnie zaimportował plik, należy użyć (sondaż) punktu końcowego Pobierz pojedynczy plik dla tego samego {fileId} z importu, a następnie sprawdzić odpowiedź dla swojego pliku.

   Przykład:

   GET: {baseURL}/api/v1/file/{fileId} Nagłówki: Typ zawartości: application/json 

2. Jeśli status to „IMPORTOWANIE”, importowanie nadal trwa, dlatego należy wstrzymać proces na pewien czas przed ponownym wysłaniem poprzedniego żądania (sondażu).
3. Status „IMPORTOWANO” oznacza, że ​​plik został pomyślnie zaimportowany.
4. Jeśli status pliku to nadal „STAGED”, a „numErrors” jest większe od zera, oznacza to, że import pliku nie powiódł się i można użyć punktu końcowego Pobierz błędy, aby pobrać komunikaty o błędach, które wystąpiły.

Rozwiązywanie problemów

Jeśli nie możesz wysłać żadnych żądań do API (błąd 401 – Nieautoryzowany)

• Sprawdź, czy użyłeś prawidłowego prefiksu adresu URL dla lokalizacji swojego obszaru roboczego Workiva.
• Sprawdź, czy używasz prawidłowego identyfikatora klienta i klucza tajnego w swoim żądaniu, bez spacji przed i po.

Uwierzytelnianie działa, ale kolejne żądania nie (błędy 404 lub 500)

• Sprawdź, czy użytkownik wskazany w utworzonym przez Ciebie grancie API ma dostęp do określonego identyfikatora tabeli Wdata.
• Sprawdź, czy tabela Wdata znajduje się w tym samym obszarze roboczym, co przyznane API.
• Sprawdź, czy używasz prawidłowych identyfikatorów plików i nie używaj spacji przed nimi ani po nich.
• Sprawdź, czy nagłówki, szczególnie „Content-Type”, zgadzają się z dokumentacją.

Mój plik został pomyślnie przesłany, ale wystąpiły błędy podczas importowania

• Sprawdź, czy podałeś prawidłowy separator.
• Upewnij się, że dane w pliku mają format pliku płaskiego, z nagłówkami w wierszu 1 z kolumny A i danymi w wierszu 2 z kolumny A.
• Upewnij się, że liczba kolumn nagłówka odpowiada liczbie kolumn danych.
• Sprawdź, czy typy danych odpowiadają tym określonym w konfiguracji tabeli Wdata.
• Pobierz błędy związane z importem pliku w celu dalszego rozwiązywania problemów