Introdução
Este guia mostrará como usar a Workiva API para importar um arquivo para o Wdata.
Se quiser automatizar a importação de um arquivo de conjunto de dados para uma tabela Wdata, mas não quiser usar as cadeias com o conector Workiva, você poderá usar a API Workiva diretamente das cadeias com o conector HTTP ou de qualquer software externo capaz de interagir com uma API REST protegida com OAuth 2.0.
Configuração inicial
Primeiro, você precisa criar uma concessão de API que gerará uma ID de cliente e um segredo. Isso pode ser feito por qualquer conta de usuário da Workiva com pelo menos as permissões "Workspace Owner" ou "Org Security Administrator" e seguindo as instruções do site fornecidas aqui.
Autenticação
Depois que você tiver configurado corretamente a concessão da API, a primeira etapa da comunicação com a API é obter a autenticação. Isso usa uma troca de token de portador oauth 2.0 padrão do setor e requer uma chamada POST, conforme detalhado nas instruções do site aqui.
Importar
Há duas etapas necessárias para carregar dados em uma tabela Wdata usando a API da Workiva:
- Faça upload do arquivo na tabela Wdata escolhida (https://developers.workiva.com/wdata-v1/wdata-uploadfile/). Isso adicionará seu arquivo como um conjunto de dados na tabela com o status "staged". Portanto, os novos dados não aparecerão em nenhuma consulta ou exibição da tabela nesse momento.
- Importe o arquivo (https://developers.workiva.com/wdata-v1/wdata-importfile/). O "Id" que você recebe na resposta do upload pode então ser usado na propriedade "fileId" para importar o arquivo e, se for bem-sucedido, adicionar os dados à tabela e disponibilizá-los em consultas e visualizações.
Com exemplos
Chave
| Texto | Substituir por |
{baseURL} |
Seu código de localização relevante, conforme definido aqui |
{tableId} |
Seu ID de tabela Wdata como encontrado na URL (veja aqui) |
{fileId} |
O ID do arquivo que você importou na etapa de upload |
Nos exemplos abaixo, os URLs são mostrados para a plataforma da UE; para os EUA ou a APAC, o "eu" deve ser alterado para "app" ou "apac", respectivamente.
-
Carregar
Faça upload do arquivo na tabela Wdata escolhida: https://developers.workiva.com/wdata-v1/wdata-uploadfile/
Exemplo:
POST: {baseURL}/api/v1/file Cabeçalhos: 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;quantity Apple;133 Apricot;175 Avocado;182 Banana;187 Bilberry;160 Blackberry;178 Blackcurrant;102 Blueberry;156 Currant;194 Cherry;182 Cherimoya;169 Clementine;165 Date;112 Damson;164 Durian;157 Eggplant;189 --boundary-- -
Importar
Em seguida, use o "Id" que você recebeu na resposta como o "fileId" para importar o arquivo da seguinte forma: https://developers.workiva.com/wdata-v1/wdata-importfile/
Exemplo:
POST: {baseURL}/api/v1/table/{tableId}/import Headers: Content-Type: application/json Body: { "delimiter":";", "fileId":"{fileId}" }Observação: Essa solicitação apenas inicia a importação do arquivo e a resposta é enviada sem esperar que ela seja bem-sucedida ou não.
Verificar status
Isso não é obrigatório, mas será uma boa prática na maioria dos casos de uso para confirmar e registrar/relatar se a importação do arquivo foi bem-sucedida ou não. Isso pode ser feito com as duas solicitações GET a seguir.
-
Para confirmar que o ponto de extremidade do arquivo de importação importou o arquivo com êxito, você deve usar (sondar) o ponto de extremidade Retrieve a single file para o mesmo
{fileId}da importação e, em seguida, verificar a resposta para o seu arquivo.Exemplo:
GET: {baseURL}/api/v1/file/{fileId} Headers: Content-Type: application/json - Se o status for "IMPORTING", a importação ainda está em andamento, portanto, você deve pausar o processo por um período antes de repetir a solicitação anterior (pesquisa).
- Um status de "IMPORTED" indica que o arquivo foi importado com êxito.
- Se o status do seu arquivo ainda for "STAGED" e o "numErrors" for maior que zero, o arquivo não foi importado e você poderá usar o ponto de extremidade Retrieve errors para obter as mensagens de erro ocorridas.
Solução de problemas
Se você não puder fazer nenhuma solicitação à API (erro 401 Unauthorized)
- Verifique se você usou o prefixo de URL correto para o local do seu Workiva Workspace.
- Verifique se você está usando o Client ID e o Secret corretos em sua solicitação, sem espaços antes ou depois.
A autenticação funciona, mas as solicitações subsequentes não funcionam (erros 404 ou 500)
- Verifique se o usuário especificado na concessão de API que você criou tem acesso à ID da tabela Wdata especificada.
- Verifique se a tabela Wdata está no mesmo espaço de trabalho que a concessão da API.
- Verifique se você está usando os IDs de arquivo corretos, sem espaços antes ou depois.
- Verifique se os cabeçalhos, especialmente o "Content-Type", correspondem à documentação.
Meu arquivo é carregado com sucesso, mas dá erro na importação
- Verifique se você especificou o delimitador correto.
- Certifique-se de que os dados em seu arquivo estejam em um formato de arquivo simples com os cabeçalhos na linha 1 da coluna A e os dados na linha 2 da coluna A.
- Certifique-se de que o número de colunas de cabeçalho corresponda ao número de colunas de dados.
- Verifique se os tipos de dados correspondem aos especificados na configuração da tabela Wdata.
- Recupere os erros relacionados à importação de arquivos para solucionar problemas adicionais