Items in API Script

フィードは、アイテムにより成り立ちますが、API Script ではアイテムはフィードの部品という以上の働きをします。アイテムは、オペレーションにインプットを提供するために使われることもあります。

アイテムの宣言

API Script では、アイテムは、api:set キーワードを通じて作成され、名付けられ、アトリビュート値を与えられます。

<api:set item="input" attr="mask" value="*.txt" />

このラインは、"input" という名前のアイテムの、"mask" アトリビュートに"*text" という値をセットします。この場合、インプットアイテムはAPI Script の変数の働きをします。

ただし、"input" という名前のアイテムは宣言されていません。その代わりに、初回にアトリビュートをセットしようとすると、そのアイテムが生成されます。上の例では、インプットアイテムが存在していない場合、そのアイテムが生成され、mask アトリビュートがセットされます。

アトリビュート値の選択

アトリビュートを参照するには、 item.attribute (e.g., "input.mask") シンタックスを使います。あるアトリビュート値をクエリするには、括弧 ([]) でアトリビュート名を囲います。これは、文字列リテラルとしてではなく、文字列を評価したいということを示します。

例えば、次のコードスニペットを見てください：

<api:set item="item1" attr="attr1" value="value1"/>
<api:set item="item1" attr="attr2" value="item1.attr1"/>
<api:set item="item1" attr="attr3" value="[item1.attr1]"/>

結果は次のとおりです：

item1.attr1 は、"value1" のリテラル文字列の値を割り振られます。
item1.attr2 は、"item1.attr1" のリテラル文字列の値を割り振られます。
item1.attr3 は、"value1" の値を割り振られます。これは、文字列"[item1.attr1]" がitem1 のattr1 アトリビュートとして評価されるからです。

文字列リテラルにおいて、\ を使って、括弧からエスケープすることができます。

デフォルトアイテム

API Script では、デフォルトアイテムという、アイテムの層の中に黙示的で名付けられていないアイテムがあります。次の2つのケースでは、デフォルトアイテムは共通してスクリプトをより短く、簡単に書くために使われています。

オペレーションの呼び出し：デフォルトアイテムは、他に指定されたアイテムがない場合に、デフォルトで呼び出されたオペレーションに渡されるアイテムです。これはつまり、api:set を使って、デフォルトの名付けられていないアイテムのアトリビュートを書いて、そのアトリビュートがスクリプト内の次のオペレーションのインプットとして渡されることを意味します。これは、オペレーションに必要なパラメータを提供する一つの方法です。
オペレーションまたはスクリプトのアウトプット内の現在のアイテムを処理：オペレーションの結果の変数名を指定しなかった場合、オペレーションを起動するapi:call ブロックの内部でデフォルトアイテムはオペレーションで生成された現在のアイテムを参照します。

API Script のキーワードのアイテムアトリビュートを単に省略することでデフォルトアイテムを操作する：

<api:set attr="path" value="." />

Named Items

スクリプト内で宣言されたアイテムに加えて、スクリプトのスコープでは、いくつかのビルトインアイテムが利用可能です。 API Script では、ビルトイン、もしくは特殊なアイテムが利用可能で、接続文字列およびSQL クエリへのアクセスのインターフェースを提供します。これらの特殊なアイテムはインプットをデータ処理オペレーションにマッピングするために役立ちます。

以下のセクションで、特殊なアイテムについて説明します。

Script Inputs (_input)

スクリプトへのインプットは_input アイテムから参照されます。 SQL ステートメントはテーブルおよびストアドプロシージャのスキーマへのインプットを提供します：SELECT ステートメントでは、_input アイテムは、WHERE 句において指定されたカラム、もしくは疑似カラムを含みます。

スクリプト内のデフォルトアイテムから値を読む場合、_input から値を読んでいます。同様に、デフォルトアイテムに書き込みたいアトリビュートは、インプットスクリプトと共にオペレーションのパラメータとして渡されます。情報ブロック、もしくはスクリプト内に定義された変数だけが_input アイテム内では有効です。

api:call ブロックの内部では、_input はデフォルトアイテムではなく、アクセスするためには名前を参照しなければなりません。

Script Outputs (_out[n])

api:call キーワードにより生成されたフィード内の現在のアイテムは、デフォルトアイテムもしくは名前を指定された特殊アイテム"_outX" を通じてアクセスすることができます。X はapi:call のネスティングのレベルです。例えば、単一のapi:call キーワードの内部の場合、アイテム名は"_out2" です。api:call キーワードの3つのネストレベルの内部の場合、_out3 となります。

接続文字列プロパティ (_connection)

The _connection item has the connection properties of the connector.The connector does not perform any validation of the connection string properties.It is left to the schema author to decide which properties are required, how they are used, etc.

In addition to providing access to the connection properties, the _connection item can be used to store pieces of data in a connection.For example, it may be necessary to store session tokens that can be reused while a connection lasts.You can use the api:set keyword to store any values, as shown in the code example below:

<api:set attr="_connection._token" value="[oauth.connection_token]"/>

Note：You can set only the attributes that start with the _ symbol.This is done so that the connection properties set by the user cannot be overriden.

SQL Clauses (_query)

The _query item has the following attributes that describe the query that was issued to the connector:


query	SQL ステートメント。次に例を示します。 SELECT Id, Name FROM Accounts WHERE City LIKE '%New%' AND COUNTRY = 'US' GROUP BY CreatedDate ORDER BY Name LIMIT 10,50;
selectcolumns	A comma-separated list of the columns in the SELECT clause.For example, the Id and Name columns in the example.If "" is specified in the SELECT clause, the value of [_query.selectcolumns] is "".
table	テーブル名。For example, Accounts in the example.
isjoin	Whether the query is a join.
jointable	The table in the JOIN clause.
criteria	The WHERE clause.For example, the following WHERE clause in the example: City LIKE '%New%' AND COUNTRY = 'US'
orderby	The ORDER BY clause.For example, Name in the example.
groupby	The GROUP BY clause.For example, CreatedDate in the example.
limit	The limit specified in the LIMIT or TOP clauses of the SELECT statement.For example, 50 in the example.
offset	The offset specified in the LIMIT or TOP clauses of the SELECT statement.For example, 10 in the example.
insertselect	The SELECT statement nested in an INSERT statement.
updateselect	The SELECT statement nested in an UPDATE statement.
upsertselect	The SELECT statement nested in an UPSERT statement.
deleteselect	The SELECT statement nested in a DELETE statement.
bulkoperationcolumns	The columns of the table the bulk operation modifies, separated by commas.For example, consider the following query: INSERT INTO Account(account_name, account_type) SELECT customer_name, customer_type FROM Customer#TEMP [_query.bulkoperationcolumns] returns the following: [account_name], [account_type]
temptablecolumns	The columns selected from the temp table in a bulk operation, separated by commas.For example, consider the following query: DELETE FROM Account WHERE EXISTS SELECT customer_name, customer_type FROM Customer#TEMP [_query.temptablecolumns] returns the following: [customer_name], [customer_type]
nullupdates	The columns of an UPDATE statement, separated by commas, that contain a null value or a null parameter value.
isschemaonly	Whether the query retrieves only schema information.

Tableau Connector for JSON