テンプレートで Start 式を使用する

以下の各セクションでは、Start 式を使用する方法を説明します。

テンプレートで Start 式を使用してレコードのリストを表示する
親レコードと祖父母レコードの列にアクセスする
一般的な Start 式
レコードの順序をコントロールする
表示するレコード数をコントロールする
Start 式と End 式をトラブルシューティングする

テンプレートで Start 式を使用してレコードのリストを表示する

Start 式はレコードのリストを表示するためにテンプレートで使用されます。テンプレートの最初に置かれる Start 式は、どのレコードを表示するかをコントロールします。その後、テンプレートを使用して各レコードの書式設定を行います。

各テンプレートは、<<Start:Start 式>> で始まり <<End>> で終わります。コロンに続く Start 式により、テンプレートを使用して書式設定するレコードのリストが生成されます。より具体的には、Start 式はテンプレートを使用して書式設定するテーブル行のキー値のリストを生成します。

テンプレートには 1 つ以上の埋め込みテンプレートが含まれる場合があります。あるテンプレートを別のテンプレートに埋め込むことで、レコードの階層を表示できます。たとえば、次の方法で、Customers、Orders、Order Details レコードを 3 階層で表示できます。

Customers 用のテンプレートを作成します。
Customers 用テンプレート内に Orders 用の埋め込みテンプレートを作成します。
Orders 用テンプレート内に Order Details 用の埋め込みテンプレートを作成します。

Start 式を含む埋め込みテンプレートは、次のユースケースで使用されます。

データ変更 bot の埋め込み式
データ変更 bot は、テーブル内の特定のレコードが変更されると呼び出されます。たとえば、Orders テーブルに関連付けられたデータ変更 bot は、ある注文 が変更されるとトリガーされます。テンプレートは、変更されたレコードのコンテキストで評価されます。テンプレートでは、Orders レコードの詳細と Orders レコードに関連付けられた Order Details レコードの両方を表示できます。Order Details レコードを表示するには、テンプレートに Start 式を含む埋め込みテンプレートが含まれている必要があります。
スケジュール設定された bot のトップ階層の式
スケジュール設定された bot では、一連のレコードを表示できます。たとえば、すべての Orders やすべての未処理の Orders を表示できます。Orders レコードを表示するには、テンプレートに Start 式を含む埋め込みテンプレートが含まれている必要があります。
スケジュール設定された bot の埋め込み式
スケジュール設定された bot では、レコードの階層を表示できます。たとえば、すべての未処理の Orders レコードを関連する Order Details レコードとともに表示できます。Orders レコードを表示するには、テンプレートに Start 式を含む埋め込みテンプレートが含まれている必要があります。その後、Orders 用テンプレート内に Order Details 用の埋め込みテンプレートを作成します。

例

Orders レコードが更新されるときにデータ変更 bot で使用されるこのテンプレートについて考えてみましょう。このテンプレートには、更新された Orders レコードのすべての Order Details レコードを表示する埋め込みテンプレートが含まれています。

埋め込みテンプレートには、次の Start 式が含まれています。
<<Start:[Related Order Details]>>

Start 式は、この式を含むテンプレートのコンテキストで評価されることに留意することが重要です。この場合、外側のテンプレートは Orders レコードの書式設定をするために使用されるので、Start 式はその Orders レコードのコンテキストで評価されます。そのため、Start 式は現在の Orders レコードの列を利用できます。

対照的に、<<Start>> と <<End>> の間の Start 式以外の式は、各子レコードのコンテキストで評価されます。この例では、Start 式は Order Details レコードを参照するため、<<Start>> と <<End>> の間の式は子である Order Details レコードのコンテキストで評価されます。<<Start>> と <<End>> の間の式は、通常 Order Details レコードの列を参照します。

埋め込みテンプレートは、Start 式によって返される子レコードごとに 1 回評価されます。たとえば、子である Order Details レコードが 5 つある場合、埋め込みテンプレートは 5 回評価されます。

親レコードと祖父母レコードの列にアクセスする

埋め込みテンプレート内では、外側階層のテンプレートのテーブルの列を参照できます。たとえば、Customer レコード、埋め込まれた子の Order レコード、さらに埋め込まれた孫の Order Detail レコードで構成される 3 階層構造のテンプレートの場合です。

親レコードの列にアクセスする

埋め込まれた Order Detail テンプレートでは、次の形式で式の逆参照を指定して、親である Order レコードの列を参照します。
[_THISROW-1].[親レコードの列名]

たとえば、[_THISROW-1].[Order Date] は親である Order レコードの Order Date 列の値を取得します。

注: [_THISROW-n] 文字列には空白を埋め込むことはできません。値 n は定数の数値になります。式にすることはできません。

祖父母レコードの列にアクセスする

埋め込まれた Order Detail テンプレートでは、次の形式で式の逆参照を指定して、祖父母である Customer レコードの列を参照します。
[_THISROW-2].[祖父母レコードの列名]

たとえば、[_THISROW-2].[Phone] は祖父母である Customer レコードの Phone 列の値を取得します。

[_THISROW] => トップ階層
[_THISROW-1] => 1 階層さかのぼって親を参照
[_THISROW-2] => 2 階層さかのぼって祖父母を参照
[_THISROW-3] => 3 階層さかのぼって曽祖父母を参照
[_THISROW-n] => n 階層さかのぼる

一般的な Start 式

Start 式にはいくつかの形式があります。以下に一般的な例を示します。

テーブル全体

最もシンプルな Start 式は、テーブルの名前とそのキー列です。

<<Start:Orders[Order Id]>>

この形式の Start 式は通常、スケジュール設定された bot のトップ階層の Start 式としてのみ意味を持ちます。

逆参照

一般的な Start 式は、逆参照の仮想列の名前です。以下に例を示します。
<<Start:[Related Order Details]>>

Orders レコードには、逆参照の仮想列 Related Order Details が含まれています。この仮想列は、Orders テーブルから子である Order Details テーブルへの逆参照を含めるために、AppSheet によって自動的に追加されたものです。これには、関連する子である Order Details レコードのキー値のリストが含まれます。上の例では、列名 Related Order Details を角括弧で囲む必要があります。

条件付き逆参照

もう一つの一般的な Start 式は、参照されるレコードのサブセットを選択する逆参照の仮想列の名前です。これは、SELECT 式で逆参照を囲むことで実現できます。以下に例を示します。
<<Start:SELECT([Related Order Details][OrderDetail Id], [Order Status] = "Open")>>

Orders レコードには、逆参照の仮想列 Related Order Details が含まれています。上の例では、列名 Related Order Details を角括弧で囲む必要があります。

この仮想列は、Orders テーブルから子である Order Details テーブルへの逆参照を含めるために、AppSheet によって自動的に追加されたものです。これには、関連する子である Order Details レコードのキー値のリストが含まれます。AppSheet では当初、この列には Related Order Details [Order Id] という名前が付けられていました。この例では、SELECT 式で使用するために列の名前を Related Order Details に変更する必要がありました。これは、元の AppSheet で生成された名前である [Order Id] は角括弧で囲まれていることから、式が機能しなくなるためです。

Start 式の SELECT は常にキー値のリストを返す必要があるため、SELECT 式の最初の引数は [Related Order Details][OrderDetail Id] になります。値 [Related Order Details] は、逆参照列の名前です。値 [OrderDetail Id] は、Order Details テーブルのキー列の名前です。まとめると、最初の引数は、参照されているすべての Order Details レコードのキーを返します。

SELECT 式の 2 番目の引数には、Order Status が Open である参照された Order Details レコードのみが含まれます。

SELECT 式

表示したい子レコードのキー値を生成する SELECT 式を指定することで、子レコードのサブセットを表示できます。
<<Start: SELECT(Orders[Order Id], AND(IN([Order Id],[_THISROW].[Related Orders]), [Order Status] = "Open"))>>

SELECT 式はキー値のリストを生成する必要があります。この例では、Order Id 列が Orders テーブルのキーです。

レコードの順序をコントロールする

OrderBy を使用して、レコードの表示順序をコントロールできます。

OrderBy() 関数のパラメータは、OrderBy(キー, 並べ替えキー, 降順かどうか) です。

次の Start 式を使用すると、Order Details レコードを価格が最も高いものから最も安いものの順に表示できます。Total 列には各 Order Details レコードの合計値が含まれます。
<<Start:OrderBy([Related Order Details], [Total], FALSE)>>

次の Start 式を使用すると、「未処理」の Orders レコードを Order Date 順に表示できます。
<<Start:OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],FALSE)>>

次の Start 式を使用すると、「未処理」の Orders レコードを Order Date の逆順に表示できます。
<<Start:OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],TRUE)>>

表示するレコード数をコントロールする

Top 関数を使用すると、表示するレコードの最大数を制限できます。

Top 関数のパラメータは、Top(並び替え済みレコードリスト, レコードの最大数) です。

注: Top は、OrderBy とのみ機能し、単独では使用できません。

次のようにして最大 3 つのレコードを表示します。
<<Start:Top(OrderBy([Related Orders], [Order Date]), 3)>>

この Start 式を使用して、最新の「未処理」の Orders レコードを表示します。<<Start:Top(OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],TRUE),1)>>

この Start 式を使用して、最も古い「未処理」の Orders レコードを表示します。<<Start:Top(OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],FALSE),1)>>

Start 式と End 式をトラブルシューティングする

以下に、一般的なエラーメッセージとその対処方法を示します。

Incomplete Start expression

Start 式にエラーがあり、表示されるエラーメッセージに Start 式の一部のみが含まれている場合は、Start 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、Start 式が表のセルに含まれている場合に特によく発生します。この場合、Start 式に誤って改行を入力してしまうことが多々あります。

Found 1 unmatched 'End'

エラーメッセージ Found 1 unmatched 'End' は、式パーサーが End 式を見つけたものの、それに対応する Start 式を見つけられなかったことを示しています。

Start 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、Start 式が表のセルに含まれている場合に特によく発生します。この場合、Start 式に誤って改行を入力してしまうことが多々あります。たとえば、Start 式内、<< と Start の間、Start: の後、終わりの >> の前に改行が挿入されていることがあります。

Found 1 unmatched 'Start'

エラーメッセージ Found 1 unmatched 'Start' は、式パーサーが Start 式を見つけたものの、それに対応する End 式を見つけられなかったことを示しています。

End 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、End 式が表のセルに含まれている場合に特によく発生します。この場合、End 式に誤って改行を入力してしまうことが多々あります。たとえば、<< と End の間、End と >> 間に改行が挿入されていることがあります。

Found n '<<' values but m '>>' values

すべての Start 式と End 式が << で始まり、>> で終わっていることを確認します。

この情報は役に立ちましたか？

改善できる点がありましたらお聞かせください。