> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ETL: 中級編 Part1: Package変数を利用する

> Integrate.io ETLでUser変数を定義し、日付範囲の動的設定やREST APIの認証情報取得、SQL内での変数利用などの活用例を紹介します。

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

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

例）Google Analyticsの場合

### Step1: 変数を設定する

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-1.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=d3f751ebdc7da74f50ac7056d8273616" alt="intermediate-part01-jp image 1" width="1051" height="365" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-1.webp" />
</Frame>

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

| 変数名                 | 求める値              | 数式(Expression)                                                                               |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------- |
| **today\_ggl\_anl** | 今日（日本時間）の日付       | `ToString(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'yyyy-MM-dd')`                          |
| **from\_ggl\_anl**  | 今日（日本時間）から３ヶ月前の日付 | `ToString(SubtractDuration(SwitchTimeZone(CurrentTime(),'Asia/Tokyo'),'P3M'), 'yyyy-MM-dd')` |

ご参考まで他の例もどうぞ。

| 求める値        | 数式(Expression)                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| **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: 秒数

例）「**P**3Y6M4D**T**12H30M5S」は、「3年6ヶ月4日12時間30分5秒」の期間を表します。
詳細は[こちら](https://en.wikipedia.org/wiki/ISO_8601#Durations)をご覧ください。

**便利な例**

| 求める値   | 数式(Expression)                                                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 月初めの日付 | `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: 変数を使って取得条件をセットする

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

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-2.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=f3650a2a56a2b81daf33b02f73208bb9" alt="intermediate-part01-jp image 2" width="1001" height="576" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-2.webp" />
</Frame>

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

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

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

### Step1: 変数を設定する

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

**BaseURL**:'[https://test.base.integrate.io/rest](https://test.base.integrate.io/rest)'
**ClientID**:'Str\_Client\_ID'
**ClientSecret**:'Str\_Client\_Secret'

さらに上記の変数を使用して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'`

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-3.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=9dc415abb76b7cd5f81526a14f549857" alt="intermediate-part01-jp image 3" width="1025" height="404" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-3.webp" />
</Frame>

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

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

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

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

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-4.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=8a264879455ab30214d48ae8d7204ccc" alt="intermediate-part01-jp image 4" width="1096" height="829" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-4.webp" />
</Frame>

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

**要注意**: WorkflowのSQLタスクやDBコンポーネントやBigQueryなどのDWHコネクタ内で記述するSQL文に変数を組み込む際は、以下のように記述ください。

※**変数の前後にシングルクォートをつける**

| 変数の種類        | 変数を使用したSQL                                                       |
| ------------ | ---------------------------------------------------------------- |
| **数値型**      | `SELECT * FROM tableA Where price >= ${変数名}`                     |
| **文字列型や日付型** | `SELECT * FROM tableA BETWEEN '${start_date}' AND '${end_date}'` |

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-5.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=8de9fc834d2cf351114bc0c67ecdb0c0" alt="intermediate-part01-jp image 5" width="1034" height="461" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-5.webp" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-6.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=3c24800626bc1d37ec62a1713963557a" alt="intermediate-part01-jp image 6" width="1109" height="829" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-6.webp" />
</Frame>

### 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変数に代入する必要があります。

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-7.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=ef67534d8def83792dabcc10237403d4" alt="intermediate-part01-jp image 7" width="1049" height="286" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-7.webp" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/integrateio/S5PjFuXd0nNm4BaF/images/japanese-knowledge-base/intermediate-part01-jp/image-8.webp?fit=max&auto=format&n=S5PjFuXd0nNm4BaF&q=85&s=03c4c0efbcb873d4388467a301d726c5" alt="intermediate-part01-jp image 8" width="1106" height="804" data-path="images/japanese-knowledge-base/intermediate-part01-jp/image-8.webp" />
</Frame>

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

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

### 変数の表記に注意:

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

## まとめ

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