はじめに
このガイドでは、Workiva API を使用して、Wdata にファイルをインポートする方法を紹介します。
Wdata テーブル へのデータセットファイルのインポートを自動化したいが、チェーン とWorkiva コネクター を使用したくない場合、代わりにHTTP コネクター を使用してチェーンから直接 Workiva API を使用するか、OAuth 2.0 で保護された REST API と対話できる外部ソフトウェアから使用することができます。
初期セットアップ
まず、クライアントIDとシークレットを生成するAPIグラントを作成する必要がある。これは、少なくとも "Workspace Owner "または "Org Security Administrator "の 権限を持つ Workiva のユーザーアカウントであれば誰でも、ここで提供される指示に従って行うことができます。 。
認証
APIグラントが正しくセットアップされたら、APIとの通信の最初のステップは認証を得ることだ。これには業界標準の oauth 2.0 ベアラートークン交換が使用され、の説明（ ）に詳述されているように、POSTコールが必要です。
インポート
Workiva APIを使用してWdataテーブルにデータをロードするには、2つのステップが必要です：
- 選択した Wdata テーブル (https://developers.workiva.com/wdata-v1/wdata-uploadfile/) にファイルをアップロードします。これにより、あなたのファイルがデータセットとしてテーブルに追加され、ステータスは"staged"となる。したがって、この時点では、新しいデータはテーブルのクエリやビューには表示されません。
- ( https://developers.workiva.com/wdata-v1/wdata-importfile/ ) ファイルをインポートする。 アップロードのレスポンスで受け取った "Id "を "fileId "プロパティで使用することで、ファイルをインポートし、成功すればデータをテーブルに追加し、クエリやビューで利用できるようになります。
実例とともに
キー
| テキスト | 置換後の文字列 |
{ベースURL}。 |
、ここに定義されているあなたのロケーションコード |
{tableId} |
Wdataテーブルのidは、URLの（こちらをご覧ください。） |
{fileId} |
アップロードステップでインポートしたファイルのID |
以下の例では、EUプラットフォームのURLを示しています。USまたはAPACの場合、"eu "はそれぞれ "app "または "apac "に変更する必要があります。
-
アップロード
選択したWdataテーブルにファイルをアップロードする：https://developers.workiva.com/wdata-v1/wdata-uploadfile/
例：
POST：{baseURL}/api/v1/fileヘッダー：Content-Type: multipart/form-data; boundary="boundary" Body: --boundary Content-Disposition: form-data; name="delimiter" セミコロン --boundary Content-Disposition: form-data; name="tableId" {ttableId} --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-- -バウンダリ--。 -
インポート
そして、レスポンスで受け取った「Id」を「fileId」として使用し、次のようにファイルをインポートする：https://developers.workiva.com/wdata-v1/wdata-importfile/
例：
POST：{baseURL}/api/v1/table/{tableId}/importヘッダ：Content-Type: application/json Body: { "delimiter":";", "fileId":"{fileId}" }.注： このリクエストはファイルのインポートを開始するだけで、その成否を待たずにレスポンスが送信される。
ステータス確認
これは必須ではありませんが、ファイルのインポートが成功したかどうかを確認し、ログ/レポートすることは、ほとんどのユースケースにおいて良い習慣となるでしょう。これは以下の2つのGETリクエストで実行できる。
-
インポートファイルエンドポイントがファイルのインポートに成功したことを確認するには、Retrieve a single file endpoint for the same
{fileId}from the import を使用（ポーリング）し、ファイルのレスポンスを確認する必要があります。例：
GET：{baseURL}/api/v1/file/{fileId}ヘッダ：コンテントタイプ: application/json - ステータスが "IMPORTING "の場合、インポートはまだ進行中であるため、前回のリクエスト（ポーリング）を繰り返す前に、プロセスを一時停止する必要があります。
- IMPORTED "のステータスは、ファイルが正常にインポートされたことを示す。
- ファイルのステータスが "STAGED "のままで、"numErrors "がゼロより大きい場合は、ファイルのインポートに失敗しています。Retrieve errorsエンドポイント を使用して、発生したエラーメッセージをフェッチすることができます。
トラブルシューティング
APIへのリクエストができない場合（401 Unauthorizedエラー）
- Workiva Workspace の場所に正しい URL 接頭辞 を使用していることを確認します。
- リクエストに正しいクライアントIDとシークレットが使用されているか、前後にスペースがないことを確認してください。
認証はうまくいくが、その後のリクエストがうまくいかない（404または500エラー）
- 作成したAPIグラントで指定したユーザーが、指定したWdataテーブルIDにアクセスできることを確認する。
- WdataテーブルがAPIグラントと同じワークスペースにあることを確認する。
- ファイルIDの前後にスペースがないことを確認してください。
- ヘッダー、特に "Content-Type "がドキュメントと一致していることを確認してください。
ファイルのアップロードは成功するが、インポート時にエラーが発生する
- 正しい区切り文字が指定されているか確認してください。
- ファイルのデータがフラットファイル形式で、ヘッダーがA列から1行目、データがA列から2行目にあることを確認する。
- ヘッダー列の数とデータ列の数が一致していることを確認する。
- データ型がWdataテーブル・セットアップで指定されたものと一致していることを確認する。
- さらなるトラブルシューティングのために、ファイルのインポートに関連するエラー を取得します。