このガイドでは、コントロールシートを用いたクエリの実行と結果のダウンロードテンプレートの実装手順を段階的に説明する。このテンプレートはクエリの実行コマンドの代替として機能する。従来はデプロイおよび実行前にチェーン内でパラメータを手動で入力する必要があった。
コントロールシートを使用することで、ユーザーは複数のクエリIDを追加し、ピックリストやマルチセレクトなどのパラメータを動的に定義できる。このテンプレートは既存のチェーンに組み込まれることが多いが、CSV形式でクエリ結果が必要な任意のワークフローでも使用できる。
前提条件
以下のコネクタがワークスペースで有効化され、設定されている必要がある。
以下のワークスペース変数がワークスペース内で作成されている必要がある。
- wsv_API ベース URL - IAM
- wsv_クライアントID
- wsv_Client シークレット
- wsv_API ベース URL - Wdata
テンプレートの検索
コントロールシートを用いたクエリの実行と結果のダウンロードテンプレートは、テンプレート画面のWorkiva Chainsセクションにある。
検索方法はこうだ：
- チェーンビルダーで、テンプレート タブに移動します。
- 上部のメニューからWorkiva チェーン を選択。
- 右上で0.0クエリを実行 | Top-Level Orchestrationを検索し、テンプレートを開く。
-
テンプレートを見つけたら、新規チェーン をクリックし、ワークスペースに配置する。
メモ： 構成されたら、このテンプレートの各チェーンをワークスペースに更新する必要があります。
変数
| 変数タイプ | 変数名称 | 説明 |
|---|---|---|
| ワークスペース変数 | wsv_API ベース URL - IAM |
使用する地域に基づいてAPIのベースURLを入力する。
|
| ワークスペース変数 | wsv_クライアントID |
APIグラントを設定する際に受け取るクライアントIDを入力する。 Workiva APIの詳細な手順についてはこちらを参照する。 |
| ワークスペース変数 | wsv_Client シークレット |
ユーザープロファイルの［セキュリティ］タブに移動し、該当する付与の横にある［アクション］ドロップダウンで［再生成］をクリックすると、API 付与シークレットを表示できる。 Workiva APIの詳細な手順についてはこちらを参照する。 |
| ワークスペース変数 | wsv_API ベース URL - Wdata |
使用する地域に基づいてAPIのベースURLを入力する。 |
ランタイム入力
| ランタイム入力 | 目的 | フィールドのタイプ | 必須 |
|---|---|---|---|
| スプレッドシート ID | これはコントロール用スプレッドシートの所在を示す。 | テキスト | はい |
| シート ID | これはコントロールシートの所在を示す。 | テキスト | はい |
テンプレートの構成
このテンプレートは、0.0 クエリを実行 | Top-Level Orchestrationと0.1 クエリを実行 | 結果をダウンロードの2つのチェーンで構成される。メインのチェーンがワークスペースにデプロイされると、そのサブチェーンも自動的にデプロイされる。
- Top-Level Orchestration：コントロールシートの情報に基づいて、このチェーンはクエリが単一のパラメータ種類（ピックリストまたはマルチセレクトのいずれか）を使用するか、複数のパラメータ種類（ピックリストとマルチセレクトの両方）を使用するかを判定する。
- クエリを実行 | 結果をダウンロード：このチェーンは、指定されたパラメータを使用してクエリを実行し、対応するデータを取得する。クエリの実行後、結果はさらなる分析や利用のためCSV形式でダウンロードされる。
コントロールシートの設定とチェーンテンプレートのワークスペースへのデプロイが完了したら、必要なのはコントロールシートのスプレッドシートIDとシートIDのみである。
これらの値はTop-Level Orchestrationチェーンの実行時入力として追加する必要がある。
パラメータ種類別のコントロールシート設定
コントロールシートの設定方法は、Wdataクエリで定義されたパラメータ種類によって異なる。クエリに複数のパラメータ種類（例えばピックリストとマルチセレクトの両方）が含まれる場合、各パラメータは同じクエリIDを使用して別々の行で定義する必要がある。クエリが1種類のパラメータのみを使用する場合、コントロールシートにはそのクエリについて1行のみが必要である。
以下の例で両方のシナリオを説明する。
例：複数のパラメータ種類を持つクエリ
ピックリストとマルチセレクトの両方のパラメータを必要とするクエリの場合、コントロールシートには各パラメータの別々の行を含め、すべて同じクエリIDを使用する必要がある。
注：キー列は、Wdataクエリで定義されたパラメータ名を指す。
構成例：
| クエリID | タイプ | キー | 値 |
|---|---|---|---|
| Wdata クエリID | Pick-List-Parameters | 年 | 単一のデフォルト値を指定する（例：2023）。 |
| Wdata クエリID | Multi-Select-Parameters | アカウントタイプ | 複数の許容値をカンマ区切りで入力する（例：Asset, Expense, Equity, Revenue）。 |
例：単一のパラメータ種類を持つクエリ
1種類のパラメータのみを使用するクエリの場合、コントロールシートには当該クエリIDについて1行のみを含める。
例えば、クエリがピックリストパラメータのみを使用する場合：
| クエリID | タイプ | キー | 値 |
|---|---|---|---|
| Wdata クエリID | Pick-List-Parameters | 年 | 単一のデフォルト値を指定する（例：January）。 |
誤った設定は後続の問題につながる可能性があるため、コントロールシートが正確に設定されていることを確認する。
テーブルへのデータのロード
出力をテーブルに直接ロードするプロセスを自動化できる。出力データをテーブルにロードするには、「Wdataにデータを読み込む」テンプレートの使用を検討する。これは、結果をダウンロードするHTTPコネクタにチェーン実行イベントを追加することで、プロセスの一部としてトリガーできる。
トラブルシューティング
エラーを含むチェーン実行履歴を表示するには：
- チェーンビルダーで、Monitorに行きます。
-
クエスチョンマークにカーソルを合わせると、チェーン実行のステータスが表示されます。
チェーンがエラーを発生させた場合、またはクエリ結果のダウンロードに失敗した場合は、以下を確認する。
- 両方のチェーンがワークスペースに公開されていることを確認する。各チェーンは別々に更新されなければなりません。
- Wdata内のクエリが最新バージョンに更新されていることを確認する。
- コントロールシートにクエリID、Type、Keys、Valueを入力する際、ID全体が入力されており、先頭または末尾に空白が含まれていないことを確認する。また、KeysおよびValuesがWdataで使用されているパラメータと正しく一致していることを確認する。
- Workiva 接続に関連付けられたOAuth2 grant が適切なアクセス権を持っていることを確認してください。
- クエリで使用されているすべてのパラメータがコントロールシートに含まれていることを確認する。
その他のリソース
- Workiva コネクター
- ファイルユーティリティ・コネクター
- JSONコネクター
- 表形式変換/トランスフォーメーション・コネクター
- チェーンを別のチェーンの中で実行する ("Run Chain events")
- OAuth2 グラント
- Wdataの機能とAPIの制限