Introduzione
Questa guida mostra come utilizzare Workiva API per importare un file in Wdata.
Se si desidera automatizzare l'importazione di un file di dati in una tabella Wdata , ma non si desidera utilizzare le catene con il connettore Workiva , è invece possibile utilizzare l'API di Workiva direttamente dalle catene con il connettore HTTP o da qualsiasi software esterno in grado di interagire con un'API REST protetta con OAuth 2.0.
Configurazione iniziale
Per prima cosa è necessario creare una concessione API che genererà un ID cliente e un segreto. Questo può essere fatto da qualsiasi account utente di Workiva con almeno i permessi di "Workspace Owner" o "Org Security Administrator" e seguendo le istruzioni di fornite qui.
Autenticazione
Una volta configurato correttamente il grant API, il primo passo nella comunicazione con l'API è l'autenticazione. Questo utilizza uno scambio di token bearer oauth 2.0, standard del settore, e richiede una chiamata POST come dettagliato nelle istruzioni di qui.
Importare
Per caricare i dati in una tabella Wdata utilizzando l'API di Workiva, sono necessari due passaggi:
- Caricare il file nella tabella Wdata scelta (https://developers.workiva.com/wdata-v1/wdata-uploadfile/). Questo aggiungerà il file come set di dati nella tabella con lo stato "staged". Pertanto, a questo punto i nuovi dati non appariranno in nessuna query o vista della tabella.
- Importare il file (https://developers.workiva.com/wdata-v1/wdata-importfile/). L'"Id" ricevuto nella risposta del caricamento può essere usato nella proprietà "fileId" per importare il file e, in caso di successo, aggiungere i dati alla tabella e renderli disponibili nelle query e nelle viste.
Con esempi
Chiave
| Testo | Sostituire con |
{baseURL} |
Il vostro codice di località pertinente, come definito qui da |
{tabellaId} |
L'id della tabella Wdata come trovato nell'URL (vedi qui) |
{fileId} |
L'id del file importato nella fase di caricamento |
Negli esempi che seguono, gli URL sono mostrati per la piattaforma UE; per gli Stati Uniti o l'APAC, "eu" deve essere cambiato rispettivamente in "app" o "apac".
-
Caricare
Caricare il file nella tabella Wdata scelta: https://developers.workiva.com/wdata-v1/wdata-uploadfile/
Esempio:
POST: {baseURL}/api/v1/file Headers: Content-Type: multipart/form-data; boundary="boundary" Body: --boundary Content-Disposition: form-data; name="delimiter" punto e virgola --boundary Content-Disposition: form-data; name="tableId" {tableId} --boundary Content-Disposition: form-data; name="file"; filename="filename.csv" Content-Type: text/plain fruit;quantity Mela;133 Albicocca;175 Avocado;182 Banana;187 Mirtillo;160 Mora;178 Ribes nero;102 Mirtillo;156 Ribes;194 Ciliegia;182 Cherimoya;169 Clementina;165 Dattero;112 Damson;164 Durian;157 Melanzana;189 --boundary-- -
Importazione
Quindi utilizzare l'"Id" ricevuto nella risposta come "fileId" per importare il file in questo modo: https://developers.workiva.com/wdata-v1/wdata-importfile/
Esempio:
POST: {baseURL}/api/v1/table/{tableId}/import Headers: Content-Type: application/json Body: {"delimiter":";", "fileId":"{fileId}" }Nota: Questa richiesta avvia solo l'importazione dei file e la risposta viene inviata senza attendere che abbia successo o fallisca.
Controllare lo stato
Non è obbligatorio, ma è una buona pratica nella maggior parte dei casi d'uso per confermare e registrare/riportare se l'importazione del file è riuscita o meno. Questo può essere fatto con le due seguenti richieste GET.
-
Per confermare che l'endpoint di importazione del file è stato importato con successo, si dovrebbe usare (polling) l'endpoint Retrieve a single file per lo stesso
{fileId}file dell'importazione e poi controllare la risposta per il proprio file.Esempio:
GET: {baseURL}/api/v1/file/{fileId} Headers: Tipo di contenuto: application/json - Se lo stato è "IMPORTAZIONE", l'importazione è ancora in corso, quindi è necessario sospendere il processo per un certo periodo prima di ripetere la richiesta precedente (poll).
- Lo stato "IMPORTATO" indica che il file è stato importato con successo.
- Se lo stato del file è ancora "STAGED" e "numErrors" è maggiore di zero, l'importazione del file non è riuscita e si può usare l'endpoint Retrieve errors per recuperare i messaggi di errore che si sono verificati.
Risoluzione dei problemi
Se non è possibile effettuare alcuna richiesta all'API (errore 401 Unauthorized)
- Verificare di aver utilizzato il prefisso URL corretto per la posizione dell'area di lavoro Workiva.
- Verificate di utilizzare l'ID cliente e il Segreto corretti nella vostra richiesta, senza spazi prima o dopo.
L'autenticazione funziona, ma le richieste successive non funzionano (errori 404 o 500)
- Verificare che l'utente specificato nella concessione API creata abbia accesso all'ID della tabella Wdata specificata.
- Verificare che la tabella Wdata si trovi nello stesso spazio di lavoro del grant API.
- Verificate che stiate utilizzando gli ID file corretti, senza spazi prima o dopo.
- Verificare che le intestazioni, in particolare "Content-Type", corrispondano alla documentazione.
Il mio file viene caricato correttamente, ma si verifica un errore durante l'importazione
- Verificare di aver specificato il delimitatore corretto.
- Assicurarsi che i dati del file siano in formato flat file con le intestazioni nella riga 1 della colonna A e i dati nella riga 2 della colonna A.
- Assicurarsi che il numero di colonne di intestazione corrisponda al numero di colonne di dati.
- Verificare che i tipi di dati corrispondano a quelli specificati nell'impostazione della tabella Wdata.
- Recuperare gli errori relativi all'importazione dei file per un'ulteriore risoluzione dei problemi