Introduction
Ce guide vous montrera comment utiliser l'API Workiva pour importer un fichier dans Wdata.
Si vous souhaitez automatiser l'importation d'un fichier de données dans une table Wdata , mais que vous ne souhaitez pas utiliser les chaînes avec le connecteur Workiva, vous pouvez utiliser l'API Workiva directement à partir des chaînes avec le connecteur HTTP ou à partir de tout logiciel externe capable d'interagir avec une API REST sécurisée avec OAuth 2.0.
Configuration initiale
Vous devez d'abord créer une subvention API qui générera un identifiant et un secret client. Cette opération peut être effectuée par n'importe quel compte d'utilisateur Workiva disposant au moins des autorisations "Workspace Owner" ou "Org Security Administrator" et en suivant les instructions fournies ici.
Authentification
Une fois la subvention API correctement configurée, la première étape de la communication avec l'API consiste à obtenir l'authentification. Cette opération utilise un échange de jetons de support oauth 2.0 standard de l'industrie et nécessite un appel POST comme indiqué dans les instructions ici.
Importer
Deux étapes sont nécessaires pour charger des données dans une table Wdata à l'aide de l'API Workiva :
- Téléchargez le fichier dans la table Wdata de votre choix (https://developers.workiva.com/wdata-v1/wdata-uploadfile/). Cela ajoutera votre fichier en tant qu'ensemble de données dans la table avec le statut "staged". Par conséquent, les nouvelles données n'apparaîtront pas dans les requêtes ou les vues sur la table à ce stade.
- Importez le fichier (https://developers.workiva.com/wdata-v1/wdata-importfile/). L'"Id" que vous recevez dans la réponse du téléchargement peut alors être utilisé dans la propriété "fileId" pour importer le fichier et, en cas de succès, ajouter les données dans la table et les rendre disponibles dans les requêtes et les vues.
Avec des exemples
Clé
| Texte | Remplacer par |
{baseURL} |
Votre code de localisation pertinent, tel que défini ici ( ) |
{tableId} |
L'identifiant de votre table Wdata comme trouvé dans l'URL (voir ici) |
{fileId} |
L'identifiant du fichier que vous importez lors de l'étape de téléchargement |
Dans les exemples ci-dessous, les URL sont indiquées pour la plateforme de l'UE ; pour les États-Unis ou l'APAC, "eu" doit être remplacé par "app" ou "apac" respectivement.
-
Charger
Téléchargez le fichier dans le tableau Wdata de votre choix : https://developers.workiva.com/wdata-v1/wdata-uploadfile/
Exemple :
POST : {baseURL}/api/v1/file Headers : Content-Type : multipart/form-data ; boundary="boundary" Body : --boundary Content-Disposition : form-data ; name="delimiter" semicolon --boundary Content-Disposition : form-data ; name="tableId" {tableId} --boundary Content-Disposition : form-data ; name="file" ; filename="filename.csv" Content-Type : text/plain fruit;quantité Pomme;133 Abricot;175 Avocat;182 Banane;187 Myrtille;160 Mûre;178 Cassis;102 Bleuet;156 Groseille;194 Cerise;182 Cherimoya;169 Clémentine;165 Datte;112 Damson;164 Durian;157 Aubergine;189 --boundary-- -
Importation
Utilisez ensuite l'"Id" que vous recevez dans la réponse comme "fileId" pour importer le fichier comme suit : https://developers.workiva.com/wdata-v1/wdata-importfile/
Exemple :
POST : {baseURL}/api/v1/table/{tableId}/import Headers : Content-Type : application/json Body : { "delimiter" :";", "fileId" : "{fileId}" }Note : Cette requête ne fait qu'initier l'importation du fichier et la réponse est envoyée sans attendre la réussite ou l'échec de l'opération.
Vérifier l'état
Ce n'est pas obligatoire mais c'est une bonne pratique dans la plupart des cas d'utilisation pour confirmer et enregistrer/rapporter si l'importation du fichier s'est déroulée avec succès ou non. Cela peut être fait avec les deux requêtes GET suivantes.
-
Pour confirmer que le point de terminaison d'importation de fichiers a bien importé le fichier, vous devez utiliser (interroger) le point de terminaison Retrieve a single file pour le même
{fileId}de l'importation, puis vérifier la réponse pour votre fichier.Exemple :
GET : {baseURL}/api/v1/file/{fileId} En-têtes : Content-Type : application/json - Si le statut est "IMPORTER", l'importation est toujours en cours et vous devez donc interrompre le processus pendant un certain temps avant de répéter la demande précédente (sondage).
- Le statut "IMPORTE" indique que le fichier a été importé avec succès.
- Si le statut de votre fichier est toujours "STAGED" et que le "numErrors" est supérieur à zéro, l'importation du fichier a échoué et vous pouvez utiliser le point de terminaison Retrieve errors pour récupérer les messages d'erreur qui se sont produits.
Dépannage
Si vous ne pouvez pas faire de demandes à l'API (erreur 401 non autorisée)
- Vérifiez que vous avez utilisé le préfixe URL correct pour l'emplacement de votre espace de travail Workiva.
- Vérifiez que vous utilisez l'identifiant et le secret du client dans votre demande, sans espace avant ou après.
L'authentification fonctionne, mais les demandes ultérieures ne sont pas acceptées (erreurs 404 ou 500)
- Vérifiez que l'utilisateur spécifié dans la subvention API que vous avez créée a accès à l'ID de table Wdata spécifié.
- Vérifiez que la table Wdata se trouve dans le même espace de travail que la subvention API.
- Vérifiez que vous utilisez les bons identifiants de fichier, sans espace avant ou après.
- Vérifiez que vos en-têtes, en particulier le "Content-Type", correspondent à la documentation.
Mon fichier est téléchargé avec succès mais des erreurs se produisent lors de l'importation
- Vérifiez que vous avez spécifié le délimiteur correct.
- Assurez-vous que les données de votre fichier sont dans un format de fichier plat avec les en-têtes dans la ligne 1 de la colonne A et les données dans la ligne 2 de la colonne A.
- Assurez-vous que le nombre de colonnes d'en-tête correspond au nombre de colonnes de données.
- Vérifiez que les types de données correspondent à ceux spécifiés dans la configuration de la table Wdata.
- Récupérer les erreurs liées à l'importation du fichier pour un dépannage ultérieur