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