Xplenty中級編 Part1: User変数を利用する

Xplentyでは変数を使いこなすことにより、きめ細かい設定が可能になります。
今回は、ユーザー自身が定義できるUser変数について紹介したいと思います。

利用シナリオ1： コネクタなどでデータ取得時の日付範囲を動的に設定する

例）Google Analyticsの場合

Step1: 変数を設定する

今回設定する変数は以下の２つです。

today_ggl_anl：今日（日本時間）の日付を取得する
ToString(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'yyyy-MM-dd')

from_ggl_anl：今日（日本時間）から３ヶ月前の日付を取得する
ToString(SubtractDuration(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'P3M'), 'yyyy-MM-dd')

1年前の場合
ToString(SubtractDuration(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'P1Y'), 'yyyy-MM-dd')

３時間前の場合
ToString(SubtractDuration(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'PT3H'), 'yyyy-MM-dd HH:mm:ss')

ヒント：期間指定の値について
SubtractDurationやAddDuration関数の期間指定で使われる記号の詳細は以下のとおりです。

P: 期間表現の先頭に配置される
- Y: 年数
- M: 月数
- W: 週数
- D: 日数

T: 時間単位の先頭に配置される。
- H: 時間数
- M: 分数
- S: 秒数
例）「P3Y6M4DT12H30M5S」は、「3年6ヶ月4日12時間30分5秒」の期間を表します。
詳細はこちらをご覧ください。

便利な例：

• 月初の日付を算出
  ToString(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'yyyy-MM-01')

• 月末の日付を算出
  ToString(SubtractDuration(ToDate(ToString(AddDuration(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'P1M'),'yyyy-MM-01')),'P1d'),'yyyy-MM-dd')

• 前月末の日付を算出
  ToString(SubtractDuration(ToDate(ToString(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'yyyy-MM-01')),'P1d'),'yyyy-MM-dd')

Step2: 変数を使って取得条件をセットする

あとは変数を日付範囲にセットします。
注意点として変数を使う場合、変数名の前に「$」をつけることで、変数として認識されます。

実装時の重要なポイント
変数はパッケージ実行時のみしか参照されません。この原則を忘れないように注意ください。

このため、パッケージ作成中に正しくデータが取得できているかどうかをデータソースのプレビュー機能で確認することができません。コツとしては、ジョブ作成中は、固定値を入力した上で検証を行い、正しく動作することを検証後、固定値を変数に置き換えるのが良いと思います。

利用シナリオ２： RestAPIの認証情報（アクセストークン）の取得に使う

例）Marketoの場合

Step1: 変数を設定する

変数画面でアクセストークンを取得するのに必要な変数をセットします。

BaseURL:'https://xxx-xxx-xxx.yyyy.com/rest'
ClientID:'xxxxxxxxxxxxxxxxxxxx'
ClientSecret:'xxxxxxxxxxxxxxxxxxxx'

さらに上記の変数を使用してCurl Functionでアクセストークンを取得する式をセットします。
accessToken:JsonStringToMap(Curl(CONCAT($BaseURL,'/identity/oauth/token?grant_type=client_credentials&client_id=',$ClientID,'&client_secret=',$ClientSecret),'GET','{"accept":"application/json"}')#'body')#'access_token'

ヒント：変数の設定順序としてaccessTokenは式内で使用する変数より下の順番に定義するようにしてください。

これで変数「accessToken」にトークンの値がセットされます。

Step2: 変数を使って取得条件をセットする

あとはRest APIコンポーネントでURLとヘッダー情報を上記の変数を使ってセットするだけで完了です。

利用シナリオ3： SQL内での変数の利用

要注意: WorkflowのSQLタスクやDBコンポーネントやBigQueryなどのDWHコネクタ内で記述するSQL文に変数を組み込む際は、以下のように記述ください。
例）
数値型の場合：SELECT * FROM tableA Where price>=${変数名}
文字列型や日付型の場合：SELECT * FROM tableA BETWEEN '${start_date}' AND '${end_date}'　※変数の前後にシングルクォートをつける

MongoDBの場合

{"\$and": [{"LastModifiedDate": {"\$lt": {"\$date": "$last_modified"}}}, {"CreatedDate": {"\$gte": {"\$date": "$created_at"}}}, {"SLA__c": "Bronze"}]}
※MongoDBソースコンポーネントのフィルタ条件で変数を使用する場合は、"$last_modified"のように「$変数名」をダブルクォートで囲む

Workflowレベルの変数とDataflowの変数の関係について

Workflowパッケージレベルの変数は、Dataflowレベルの変数を上書く（オーバーライド）のに使用することができます。

例1: Workflow変数とDataflow変数の両方が同じ名前を持つ場合

Workflow変数をDataflow変数に代入する必要があります。

例2: Workflowレベルでのみ変数が定義されている場合

Workflow内のDataflow（タスク）がそのDataflow内で定義されていない変数を使用していても、Workflowレベルで値がセットされている場合、そのDataflowタスクは、Workflow変数の値を使用して実行されます。

変数の表記に注意:

SQL内での変数の指定方法: 「${変数名}」
通常パッケージ内のURLやファイルパスなど:「$変数名」

まとめ

変数を使えば、柔軟なジョブを実装することができます。これ以外にも使い方は様々ですが、ファイルストレージ（取得もしくは保存時）などでの使用例を知りたい場合は、こちらのブログもチェックしてみてください。