式を使用して、ArcGIS Survey123 でスマートなフォームを作成します。
以前の質問は必ず ${field_name} という形式によって式で参照される必要があります。
演算子
Survey123 では、以下の演算子がサポートされています。
演算子 | 説明 | 例 |
---|---|---|
。 | 現在の回答 | .=1 |
+ | 加算 | ${question_one} + 4 |
- | 減算 | ${question_one} - 4 |
* | Multiplication | ${question_one} * 4 |
div | Division | ${question_one} div 4 |
= | 等しい | ${price}=9.80 |
!= | 等しくない | ${price}!=9.80 |
< | より小さい | ${price}<9.80 |
<= | 以下 | ${price}<=9.80 |
> | より大きい | ${price}>9.80 |
>= | 以上 | ${price}>=9.80 |
and | And | ${price}>9.00 and ${price}<9.90 |
mod | 剰余 (除算の余り) | ${question_one} mod ${question_two} |
or | Or | ${price}=9.80 or ${price}=9.70 |
関数
Survey123 では、以下の関数がサポートされています。
関数 | 説明 | 例 |
---|---|---|
boolean(question, expression, or value) | 指定された値が NULL でない場合に TRUE を返します。 代わりに boolean-from-string() を使用することをお勧めします。 注意:この関数は、Survey123 Web アプリでは必ず true を返します。 その他については、「空の値」をご参照ください。 | boolean(${question_one}) |
boolean-from-string() | 指定された文字列が 'true' または '1' の場合に TRUE を返します。 それ以外の場合は FALSE を返します。 | boolean-from-string(${question_one}) |
coalesce(value1, value2) | 空でない最初の値を返します。 この関数では 2 つの値しか使用できません。 | coalesce(${question_one}, ${question_two}) |
concat(value1, value2, …) | 文字列値の連結を返します。 | concat(${question_one}, ' and ', ${question_two}) |
contains(string, substring) | 指定の文字列にサブ文字列が含まれている場合に TRUE を返します。 | contains(${question_one}, 'red') |
count(repeat) | 回答の合計を、繰り返し全体で所定の質問に返します。 詳細については、「集約関数」をご参照ください。 注意:この関数を Survey123 フィールド アプリで使用する場合、繰り返し内または繰り返し外に配置できます。 この関数を Survey123 Web アプリで使用する場合は、繰り返し外に配置する必要があります。 繰り返し外からの個数を、繰り返し内の計算で参照できます。 | count(${question}) |
count-selected(question) | [select_one] 質問と [select_multiple] 質問に対し、選択された回答の数を返します。 さらに、multiline の表示設定を使用し、[image]、[audio]、[file] の質問の添付ファイルの数も返します。 | count-selected(${question_one}) |
date(question, expression, or value) | 時間を維持しないで数値または文字列を日付オブジェクトに変換します。 | date('2017-05-28T04:39:02+10:00') |
date-time(question, expression, or string) | 数値または文字列を日付オブジェクトに変換します。 | date-time('2017-05-28T04:39:02+10:00') |
日付オブジェクトを 10 進数の日付/時間の値に変換します。 | decimal-date-time(${date_question}) | |
decimal-time(question, expression, or string) | 時刻オブジェクトを、デバイスのタイムゾーンでの日の小数部分を表す数値に変換します。 | decimal-time(${time_question}) |
ends-with(string, substring) | 指定の文字列がサブ文字列で終わる場合に TRUE を返します。 | ends-with(${question_one}, 'hand.') |
false() | False | false() |
既存の日付または時刻の値を、定義した形式に合わせます。 | format-date(${previous_time}, '%H:%M') | |
if(condition, a, b) | 条件が true と評価されると a を返し、それ以外の場合は b を返します。 | if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no') |
indexed-repeat(question, repeat, index number) | 繰り返しレコード内の特定の質問から値を返します。 詳細については、「繰り返し」をご参照ください。 | indexed-repeat(${room_no}, ${floor}, 3) |
int(question, expression, or value) | 整数に変換します。 変換方法はデータ型によって異なります。 注意:この関数が空の場合、NaN が返され、質問は空のままになります。 | int(${question_one}) |
join(separator, question) | 繰り返し内の指定の質問にすべての回答を指定の区切り記号で区切って結合します。 注意:この関数を Survey123 フィールド アプリで使用する場合、繰り返し内または繰り返し外に配置できます。 この関数を Survey123 Web アプリで使用する場合は、繰り返し外に配置する必要があります。 繰り返し外からの結合値を、繰り返し内の計算で参照できます。 | join(',', ${question_in_repeat}) |
jr:choice-name(choice_name, 'question') | [select_one] 質問に使用されます。 指定の質問に含まれる選択肢の名前に関連付けられたラベルを返します。 質問は引用符で囲んで定義する必要があるので注意してください。 | jr:choice-name(${select_one}, '${select_one}') |
select_multiple 質問に使用されます。 指定の質問に含まれる選択肢の名前に関連付けられたラベルを返します。 個々の回答のラベルを抽出するために selected-at() 関数を使用する必要があります。 質問は引用符で囲んで定義する必要があるので注意してください。 | jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}') | |
max(value1, value2, ...) | 所定の範囲内の最大値をそのまま返すか、所定の範囲内の最大値を繰り返し全体で 1 つの質問に返します。 | max(${question_one}, ${question_two}) |
min(value1, value2, ...) | 所定の範囲内の最小値をそのまま返すか、所定の範囲内の最小値を繰り返し全体で 1 つの質問に返します。 | min(${question_one}, ${question_two}) |
not(expression) | 式が true を返す場合は false の値、false を返す場合は true の値を返します。 | not(selected(., 'yes')) |
now() | 現時点のタイム スタンプを返します。 この関数は、time および dateTime の質問で使用されます。 date の質問の today() と同じ動作をします。 | now() |
number(question, expression, or value) | 数値に変換します。 変換方法はデータ型によって異なります。 注意:この関数が空の場合、NaN が返され、質問は空のままになります。 | number(${question_one}) |
once() | 質問にすでに値が設定されている場合は、既存の値を返します。 この関数は、繰り返しの質問で random() または uuid() を使用して、フォーム内の繰り返しレコードを参照しても値が変わらないことを確認する場合に役立ちます。 | once(uuid()) |
position(..) | 繰り返し内の現在のレコードのインデックスを返します。 詳細については、「繰り返し」をご参照ください。 | position(..) |
pulldata() | 外部の CSV ファイルの値を返します。 詳細については、「CSV からの値の取得」をご参照ください。 | pulldata('users', 'email', 'name', ${respondent_name}) |
pulldata("@exif") | 画像の EXIF メタデータから値を返します。 詳細については、「画像メタデータの抽出」をご参照ください。 | pulldata("@exif", ${photo}, "GpsLatitude") |
pulldata("@geopoint") | ジオポイントの質問から値を返します。 詳細については、「ジオポイント値の抽出」をご参照ください。 | pulldata("@geopoint", ${location}, "horizontalAccuracy") |
pulldata("@javascript") | フォームの JavaScript 関数を実行し、結果を返します。 詳細については、「調査フォームの JavaScript 関数」をご参照ください。 | pulldata("@javascript", "functions.js", "uniqueID", ${buildings}) |
pulldata("@json") | JSON オブジェクトから値を返します。 詳細については、「JSON からの値の取得」をご参照ください。 | pulldata("@json", ${json_output}, "attributes.ZIP_CODE") |
pulldata("@layer") | ArcGIS フィーチャ レイヤー、フィーチャ テーブル、またはクエリ対応のマップ サービスをクエリし、結果を返します。 詳細については、「フィーチャ レイヤーのクエリ」をご参照ください。 | pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location}) |
pulldata("@property") | デバイスまたはサインインしているユーザーに関する情報を返します。 詳細については、「デバイスとユーザー プロパティ」をご参照ください。 | pulldata("@property", 'username') |
random() | 0 (含まれる) と 1 (含まれない) のランダムな値を返します。 | random() |
regex() | 正規表現を質問の入力に適用します。 パターンが一致すると true を返します。 詳細については、「正規表現」をご参照ください。 | regex(., '^\d{5}$') |
selected(質問, 値) | 回答が選択されているかどうかを確認します。 この関数は、[select_one] 質問と [select_multiple] 質問に使用されます。 | selected(${question_one}, 'a') |
selected-at(question, number) | select_multiple 質問に使用されます。 指定の数値に対してゼロから数えて選択された選択肢の名前を返します。たとえば、'2' の場合は、3 番目に選択された選択肢を返します。 | selected-at(${question_one}, 2) |
starts-with(string, substring) | 指定の文字列がサブ文字列で始まる場合に TRUE を返します。 | starts-with(${question_one}, 'The') |
string(question, expression, or value) | 文字列に変換します。 変換方法はデータ型によって異なります。 | string(${question_one}) |
string-length(question, expression, or value) | 空でない文字列の長さを返します。 | string-length(${question_one}) |
substr(question, start, end) | 指定された開始の値から、インデックスの終了 -1 の文字までのサブ文字列を返します。ここで、開始と終了の値は 0 で始まります。 | substr(${question_one}, 1, 2) |
sum(repeat) | すべての回答の合計を、繰り返し全体で所定の質問に返します。 詳細については、「集約関数」をご参照ください。 注意:この関数を Survey123 フィールド アプリで使用する場合、繰り返し内または繰り返し外に配置できます。 この関数を Survey123 Web アプリで使用する場合は、繰り返し外に配置する必要があります。 繰り返し外からの合計値を、繰り返し内の計算で参照できます。 | sum(${question}) |
today() | 現地時間の正午として内部的に格納されている、本日の日付を返します。 この関数は、date の質問で使用されます。 | today() |
true() | True | true() |
uuid() | ランダムな UUID 文字列を返します。 | uuid() |
version() | [設定] ワークシートで定義された調査のバージョンを返します。 | version() |
Survey123 では、次の数学関数がサポートされています。
関数 | 説明 | 例 |
---|---|---|
acos(値) | 値の逆余弦を返します。 | acos(${question_one}) |
asin(値) | 値の逆正弦を返します。 | asin(${question_one}) |
atan(値) | 値の逆正接を返します。 | atan(${question_one}) |
atan2(値 1, 値 2) | 値の商の逆正接を返します。 | atan2(${question_one}, ${question_two}) |
cos(値) | 値の余弦を、ラジアン単位の角度として返します。 | cos(${question_one}) |
sin(値) | 値の正弦を、ラジアン単位の角度として返します。 | sin(${question_one}) |
tan(値) | 値の正接を、ラジアン単位の角度として返します。 | tan(${question_one}) |
exp(値) | 値の自然指数を返します。 | exp(${question_one}) |
exp10(値) | 10 の値乗を返します。 | exp10(${question_one}) |
log(値) | 値の自然対数を返します。 | log(${question_one}) |
log10(値) | 値の基数 10 の対数を返します。 | log10(${question_one}) |
pi() | pi を返します。 | pi() |
pow(値, 指数) | 値を指定の指数で累乗して求められた結果を返します。 | pow(${question_one}, 3) |
round(値, 桁) | 四捨五入された値を返します。 | round(${question_one}, 5) |
sqrt(値) | 値の平方根を返します。 | sqrt(${question_one}) |
制限
調査の質問に制限を追加すると、回答用に入力可能な内容が制限されます。 ここには、特定の範囲の数値、文字と数字の組み合わせ、または一般的なパターン マッチングなどが含まれます。 スプレッドシートでは、制限の式は制限のフィールドに入力され、情報目的のテキストは survey ワークシートの constraint_message 列に入力されます。 制限の式では、質問の入力が常にピリオドによって表されます。
たとえば、次の式を使用して、整数のフィールドの入力を正の数のみに制限できます。
.>= 0
この式を date フィールドに適用すると、ユーザーは今日より前の日付の値を入力できなくなります。
.>= today()
制限には計算も使用できます。 次の式は、ユーザーが今日と今日から 14 日後までの間の日付のみを選択できるようにするための計算を実行します。
(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))
ヒント:
予期しないエラーを防ぐため、-1 ~ 1 の間の小数値が式に含まれる場合には、値の前に先行ゼロを挿入してください。 先行ゼロを挿入しない場合、小数点が操作文字 . (または -) と間違われる可能性があります。 たとえば、次の式は失敗します。
.> .25 and .< 24.25
次の式は期待どおりに実行されます。
.> 0.25 and .< 24.25
正規表現
正規表現とは、文字列のパターンに一致させるために使用される一連の文字のことです。 Survey123 では、パターンが一致すると式は true を返し、パターンに一致しなければ false を返します。
正規表現をパターン マッチングの方法としてさまざまな場面で使用して、有効な回答を一定の形式に制限したり、特定のコンテンツを確実に含むようにしたりすることができます。 この例では、質問への回答のどこかに単語「road」が含まれている必要があります。
regex(., 'road')
これらの例の先頭に使用されているピリオドにより、式が現在のフィールドに適用されます。 代わりに別のフィールドの名前を追加すると、そのフィールドに正規表現が適用されます。これは、関連する式に最適です。 カンマは、このフィールド定義と式の間の区切り文字として機能します。
この正規表現は、回答が単語「road」に完全一致し、前後に付属する文字がないことを保証します。
regex(., '^road$')
正規表現は、質問の入力を標準形式に限定するのに最適です。 この例では、米国の 5 桁の郵便番号の入力のみを受け付けます。
regex(., '^\d{5}$')
この例では、次の写真のようなインドネシアの現在のライセンス プレート形式と回答を照合します。
regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')
標準化が緩い形式の場合、複雑な正規表現が必要になることがあります。 Survey123 Web アプリが使用するこの正規表現は、メール アドレスのフォーマットに合わせて文字列フィールドの入力を制限します。
regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$')
この式の変更は、電子メール アドレスの書式に一致する入力に制限しますが、英語以外の文字を使用可能にします。
regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\u0400-\uffff\-0-9]+\.)+[a-zA-Z\u0400-\uffff]{2,}))$')
この例でも、Survey123 アプリの正規表現が使用され、フィールドが Web アドレスのフォーマットに一致する回答のみを受け入れるよう制限されています。
regex(., '^((https?|ftps?)\://|)(((?:(?:[\da-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.)+(?:[a-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.?)|localhost)(\:\d+)?(/(?:[^?#\s/]+/)*(?:[^?#\s/]+(?:\?[^?#\s/]*)?(?:#[A-Za-z][\w.:-]*)?)?)?')
正規表現の詳細については、Mozilla Developer Network のドキュメントをご参照ください。 正規表現の文字と関数のリストについては、Survey123 テンプレートの [Reference] ワークシートか、「クイック リファレンス」をご参照ください。
計算
計算は、質問の calculation 列で実行されます。 計算はほとんどの場合に calculate タイプの質問に関連付けられますが、integer、decimal、text、select_one の質問に適用することもできます。 計算の結果を使用して、calculate の質問のフィールド名を参照することで関連する式や制限の式を設定することができます。
タイプの質問は非表示になっているため、フォーム上に表示されません。 つまり、計算タイプの質問を使用すると、フォーム上に表示する必要はないが、フィーチャ レイヤーに含める必要がある値を保持することができます。
たとえば、タイプが calculate の質問を作成して calc という名前を付け、その calculation 列に次の式を挿入することができます。
${question_1} + ${question_2} + ${question_3}
この結果を使用して、次の質問に対する関連性を設定します。
${calc} <= 100
計算は date フィールドの回答とともに使用できます。 この計算は入力の日付と今日との間の年数を推定するもので、誰かの年齢を計算するために適しています。
int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25))
場合によっては、値の一部のみ、または完全な回答を切詰めたものが必要になることもあります。 substr 演算子は文字列の一部 (後の数値で定義された部分) のみを返します。 最初の数値は選択の開始点を決定し、2 つ目の数値は長さを決定します (2 つ目の値がない場合は、文字列の末尾まで続きます)。 次の例では、substr 演算子により 10 番目から 15 番目の文字以外が削除されます。
substr(${previous_question}, 10, 15)
最初の数値が負の数の場合、substr は文字列の先頭からではなく末尾からカウントを開始します。 次の例では、回答の最後の 5 文字のみが返されます。
substr(${previous_question}, -5)
calculationMode パラメーターを使用して、フォームで計算が行われるタイミングを制御できます。 詳細については、「計算モード」をご参照ください。
calculation 列を繰り返しの集約関数に使用することもできます。 詳細については、「繰り返し」をご参照ください。
計算の使用時には、次のベスト プラクティスを厳守してください。
- random() を使用する場合には、結果がゼロ (0) になるのを避けるため、定数を加算することを検討してください (例: random()+0.5)。 値が 0 になると、空白の回答になる可能性があります。
- 制限をかける場合、式内の -1 ~ 1 のすべての小数値には先頭にゼロを挿入してください。小数点が先頭に来るとエラーの原因となります。
- 計算結果のデータ タイプは、計算の各エレメントのデータ タイプに依存します。 2 つの整数に対して計算を行った場合、計算結果は整数になります。 計算に文字列データ タイプが含まれている場合、+ 演算子は値を加算するのではなく、値を連結することになります。 予期しない結果を避けるため、number() 関数を使用して、計算内の文字列値が数値として処理されるようにします。 たとえば、question1 (整数タイプ) を question2 (テキスト タイプ) に加算する計算は、${question1} + number(${question2}) になります。
ヒント:
計算の質問の XLSForm のデフォルトのバインド タイプは string です。 このデフォルトを上書きするには、質問に対して必要なタイプを bind::type 列に入力します (たとえば、int や decimal など)。 希望する質問タイプ (integer や decimal など) を使用して、この質問の表示設定を hidden に設定することもできます。
注意:
テキストの質問で数学関数または演算子を使用すると、Survey123 Web アプリに NaN の結果が返されます。テキストの質問を連結するには、+ 演算子の代わりに concat() 関数を使用します。
複雑な計算関数
calculation 列では、より複雑な数学演算も処理できます。 次の例では、円周率と累乗の関数を使用して、半径からプロットの面積を決定しています。
pi() * pow(${plot_radius}, 2)
樹木の高さを計測する一般的な方法は、観測ポイントの目の高さから樹木の先端までの角度と、同じ観測ポイントから樹木の根元までの距離を計測することです。 樹木の先端までの角度を度単位で計測した場合、次の計算を使用してラジアン単位に変換します。
${angle_to_top_degrees} * (pi() div 180)
角度の計測値がラジアン単位になったので、次の計算で樹木の高さを求めることができます (小数点以下 2 桁に丸めました)。
round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)
日付の書式設定
format-date 関数を calculation フィールドで使用し、日付と時刻の値を書式設定できます。 日付の一部をユーザーに表示したい場合、または文字列として保持したい場合に便利です。
この例では、過去の time または dateTime の質問に含まれていた値は 24 時間形式で返されます。
format-date(${previous_time},'%H:%M')
format-date 関数で使用できる修飾子は以下のとおりです。
修飾子 | 説明 |
---|---|
%3 | 0 埋めしたミリ秒 (000 ~ 999) |
%a | 3 文字に短縮した曜日 |
%b | 月名の省略形 |
%d | 0 埋めした日付 |
%e | 日付 |
%h | 時刻 (24 時間形式) |
%H | 0 埋めした時刻 (24 時間形式) |
%m | 0 埋めした月 |
%M | 0 埋めした分 |
%n | 数で表した月 |
%S | 0 埋めした秒 |
%W | 週数 注意:%W 修飾子は、日付の質問が計算を使用している format-date 関数では使用できません。 この修飾子は、デフォルトが設定されている日付の質問で機能します。 |
%y | 2 桁の年 |
%Y | 4 桁の年 |
注意:
dateTime の質問は、1 分未満の時間解像度はサポートしていません。 1 分未満の日付の時間解像度を捕捉するには、start および end の質問の使用を検討します。
空の値
他の質問を指す制限や計算を使用する場合には、その質問が空白である (つまり、回答が存在しない) 場合に発生する処理に注意してください。 空の値は次のように表されます。
- 整数および小数の質問の場合は、NaN (数値ではないという意味)。 これは、有効な値が存在しないことを表す特別な値です。
- テキストの質問の場合は、'' (空の文字列という意味)。 select_one、select_multiple、rank、および hidden の質問のデフォルトのデータ タイプもテキストです。 select_one、select_multiple、hidden の質問タイプが空の場合、または rank 質問がユーザーによって変更されていない場合は、ここには空の文字列が格納されます。
値が数値またはテキストのどちらかによって、計算の挙動が異なります。
整数または小数の質問の場合、次の挙動が発生します。
- NaN の値を含む数式は正常に実行されず、質問は空のままになります。
- min() および max() 関数は正常に実行され、すべての NaN 値が無視されます。
- NaN 値と他の値との比較は、is not equal 値の比較の計算においてのみ true になります。 その他すべての式では false になります。
テキストの質問の場合、次の挙動が発生します。
- テキストの質問の連結は、空の値が存在する場合も正常に実行されます。 たとえば、concat("Hello" + ${firstName}, ", how are you?") は、質問 firstName が空の場合は "Hello , how are you?" になります。
- min() および max() 関数は正常に実行され、すべての空の文字列が無視されます。
- 空のテキストの回答は別の空のテキストの回答と等しく、空でないテキストよりも小さくなります。
string-length 関数を使用して、質問が空かどうかを判別できます。 string-length 関数はすべての質問タイプに使用できます。 たとえば、Question1 が空の場合、string-length(${Question1}) は 0 を返します。
count-selected 関数を使用して、select_one または select_multiple の質問が空かどうかも判別できます。 たとえば、question2 で選択が行われていない場合、count-selected(${question2}) は 0 を返します。
Select_multiple と rank の質問
select_multiple と rank の質問タイプに対する回答の保存方法は他とは異なります。 select_multiple の質問でチェックされた各回答は選択順に入力され、カンマで区切られます。 たとえば、回答 'A' と 'B' をこの順序で選択すると、回答は 'A,B' と表示されます。 rank の質問への回答は、送信時にランクが一番高いものから一番低い順に、カンマ区切りリストに保存されます。
一部の XLSForm 機能は select_multiple と rank の質問では動作しません。 たとえば、select_multiple の質問を指す質問の relevant 列に 'A' という回答を入力し、調査の回答が 'A,B' である場合、この回答は適切だと見なされません。 この場合の解決策は selected() 関数を使用することです。この関数はいずれかの値がリストに表示されるかどうかを判別します。
次の式を質問の relevant 列で使用すると、参照される select_multiple の質問の回答の 1 つとして 'A' をユーザーが選択した場合に、質問が表示されます。 select_multiple の質問に回答が追加されても、この挙動は変更されません。
selected(${previous_question}, 'A')
.csv ファイルからの値の取得
質問の calculation 列で pulldata() 関数を使用すると、.csv ファイルからデータをあらかじめロードできます。 .csv ファイルは 2 つの方法で追加できます。調査の media フォルダーに手動で配置する方法か、ArcGIS でホストされている .csv ファイルにリンクする方法です。
pulldata() 関数では、次の 4 つのパラメーターをここに示す順序で指定する必要があります。
- 値のリストを格納する .csv ファイルの名前。 この名前には .csv というファイル名の接尾辞は含まれません。
- 戻り値が格納されている、.csv ファイル内の列の名前。
- 値の検索に使用する、.csv ファイル内のキー フィールドの名前。
- キー フィールドで検索するキー値。
これらの値は直接定義するか、調査内のどこかで定義された変数を使用して定義できます。 次の例の計算では、以前の質問で名前指定された誰かの電子メール アドレスを、info という名前の .csv ファイルから取得して返します。
pulldata('info', 'email', 'name', ${respondent_name})
同じ pulldata() 関数を constraints 列で使用して、ユーザーが .csv ファイルに存在しない回答を送信するのを防ぐこともできます。 constraints 列では、これと同じ式によって、.csv ファイルの name 列に存在しない値をフォームが受け入れるのを防ぐことになります。
pulldata() 関数にはいくつかの制限事項があります。 キー フィールドの名前には、[choices] ワークシートの name 列と同じ制限事項があります。つまり、これらの値には空白や非 ASCII 文字を含むことができません。 さらに、これらは .csv ファイルなので、フィールドのいずれかでカンマを使用すると、pulldata() 関数が不正な結果を生成します。
.csv ファイル内の値が 255 文字を超える場合は、.csv コンテンツを使用して入力している質問と、pulldata() 関数への入力として使用されている質問に対して、bind::esri:fieldLength 列にそれより大きい値を入力する必要があります。 これらのフィールドのいずれかの最大長より大きい値が .csv ファイル内にある場合は、調査の回答が送信されず、エラー コード 1000 が表示されます。
注意:
pulldata() 関数を使用して、select_multiple の質問の値を入力することはできません。
pulldata() 関数を使用する場合、.csv の列名は空白にすることができず、スペース、ハイフン、他の特殊文字を含めることはできません。
UTF-8 文字エンコーディングを使用して .csv ファイルをエンコードすることをお勧めします。 Microsoft Excel を使用して .csv ファイルを作成している場合は、CSV UTF-8 で保存します。
JSON からの値の取得
pulldata("@json") 関数を使用すると、JSON オブジェクトから個々のプロパティを抽出できます。 この関数は、pulldata("@javascript") や pulldata("@layer") など他の関数を補完するために使用されます。 この関数の構文は以下のとおりです。
pulldata("@json", <question name>, "<JSON property>")
pulldata("@json") のパラメーターは以下のとおりです。
- question name - JSON オブジェクトを含む質問の名前 (例: ${json_response})。
- JSON property - JSON から取得したいプロパティ。 JSON 構造のプロパティの位置を指定するには、ピリオドを使用します。 たとえば、address オブジェクトから City プロパティを取得するには、"address.City" を使用します。
次の例では、リバース ジオコード操作の結果は、json_response というテキストの質問に JSON として返されます。
次のようなロケーターからの応答が返されます。
{
"address": {
"Match_addr": "Eiffel Tower",
"LongLabel": "Eiffel Tower, Paris, Île-de-France, FRA",
"ShortLabel": "Eiffel Tower",
"Addr_type": "POI",
"Type": "Historical Monument",
"PlaceName": "Eiffel Tower",
"AddNum": "",
"Address": "",
"Block": "",
"Sector": "",
"Neighborhood": "Paris 07",
"District": "Paris",
"City": "Paris",
"MetroArea": "",
"Subregion": "Paris",
"Region": "Île-de-France",
"RegionAbbr": "",
"Territory": "",
"Postal": "",
"PostalExt": "",
"CntryName": "France",
"CountryCode": "FRA"
},
"location": {
"x": 2.294520000000034,
"y": 48.85832000000005,
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
}
}
}
pulldata("@json") 関数は、address オブジェクトから City プロパティを取得するために使用されます。
pulldata("@json", ${json_response}, "address.City")
経度と緯度は location オブジェクトから取得されます。
pulldata("@json", ${json_response}, "location.x")
pulldata("@json", ${json_response}, "location.y")
注意:
親オブジェクトの個別のプロパティにアクセスする場合にピリオドを使用します。 ピリオド自体がプロパティの一部になっている場合、ピリオドを角括弧 [] で囲む必要があります。 たとえば、address オブジェクトから City.Population というプロパティを取得する場合、式は pulldata("@json", ${json_response}, "address.[City.Population]") となります。オブジェクトの配列内にあるオブジェクトにアクセスするには、配列内の位置を角括弧で囲んで指定します。 JSON 配列のインデックスはゼロから始まります。 以下に、スマート属性から返される JSON オブジェクトの例を示します。 これには classes 配列が含まれています。
{
"classNames": "person,bottle,keyboard",
"classes": [
{
"name": "person",
"score": 0.67421875,
"xmin": 47,
"ymin": 20,
"xmax": 1086,
"ymax": 262
},
{
"name": "bottle",
"score": 0.7625,
"xmin": 237,
"ymin": 469,
"xmax": 552,
"ymax": 639
},
{
"name": "keyboard",
"score": 0.55078125,
"xmin": 28,
"ymin": 49,
"xmax": 1078,
"ymax": 385
}
]
}
上記の例では、次の式は classes 配列の最初のオブジェクトからスコア 0.67421875 を返します。
pulldata("@json", ${results}, "classes[0].score")
length プロパティを使用し、配列内のオブジェクト数を返すことができます。 上記の例では、次の式は長さ 3 を返します。
pulldata("@json", ${results}, "classes.length")
フィーチャ レイヤーのクエリ
pulldata("@layer") 関数を使用して、フィーチャ レイヤー、フィーチャ テーブル、またはクエリ対応のマップ サービスを検索できます。 属性検索と空間検索を実行できます。 属性検索では getRecord または getValue 操作を使用します。
pulldata("@layer", "getRecord", "<URL>", "<WHERE clause>")
pulldata("@layer", "getValue", "<JSON property>", "<URL>", "<WHERE clause>")
空間検索では getRecordAt または getValueAt 操作を使用します。
pulldata("@layer", "getRecordAt", "<URL>", <location>, "<WHERE clause>")
pulldata("@layer", "getValueAt", "<JSON property>", "<URL>", <location>, "<WHERE clause>")
注意:
空間検索で指定された位置はジオポイントの質問である必要があります。
1 つのフィーチャとそのすべての属性を含む JSON フィーチャ オブジェクトが getRecord 操作と getRecordAt 操作によって返されます。 検索応答全体ではなく、フィーチャ オブジェクトの 1 つの値が getValue 操作と getValueAt 操作によって返されます。
pulldata("@layer") のパラメーターは以下のとおりです。
パラメーター | 説明 |
---|---|
JSON property | getValue 操作と getValueAt 操作で必須です。 検索応答から取得する値。 例:
|
location | getRecordAt 操作と getValueAt 操作で必須です。 フィーチャ レイヤーで検索するポイント位置。 ジオポイントの質問である必要があります。 例:
|
URL | このパラメーターは必須です。 検索するフィーチャ レイヤーの URL またはテーブル。 このパラメーターでは追加のリクエスト パラメーターを指定できます。 例:
|
WHERE clause | オプション。 フィーチャ レイヤーまたはテーブルを絞り込む WHERE 式。 WHERE 句が指定されない場合は、デフォルトの "1=1" が使用されます。 例:
|
ヒント:
クエリ応答の最初のレコードが pulldata("@layer") 関数で返されます。 求める結果が得られるよう、クエリを設計およびテストします。 WHERE 句と以下で説明する追加のリクエスト パラメーターを使用して検索を改善できます。
pulldata("@layer") 関数は効率化のために検索応答をキャッシュします。 キャッシュを無効にして、この関数が実行されるたびに新しいリクエストが作成されるようにするには、time=now パラメーターを URL に追加します (例: concat(${layer_url}, "?t=", now()))。
以下のサンプルでは、世界のタイム ゾーンのポリゴン フィーチャ レイヤーを検索し、対象のジオポイントがあるタイム ゾーンを返しています。
ジオポイントが交差するタイム ゾーンを次の構文で取得するために、getRecordAt 操作が使用されます。
pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
次に、pulldata("@json") 関数を使用して ZONE 属性が検索応答から抽出されます。 getValueAt 操作を pulldata("@layer") 計算で使用して、検索応答を格納する別の質問を用意することなく、ZONE 属性を直接取得することもできます。 以下の例をご参照ください。
pulldata("@layer", "getValueAt", "attributes.ZONE", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
制約には pulldata("@layer") を使用できます。 たとえば、ジオポイントの質問に制約を適用することで、対象地域外でユーザーが位置を送信できないようにすることができます。
次の構文を使用して、対象のジオポイントがある国の JSON フィーチャ オブジェクトが getRecordAt 操作によって返されます。
pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")
pulldata("@json") を使用して、国名がテキストの質問に抽出されます。 その後、${country}='Canada' の制約がジオポイントの質問に適用されることで、位置がカナダの地域に当てはまるようになります。
リクエスト パラメーター
distance や orderByFields、resultOffset などの追加のリクエスト パラメーターで pulldata("@layer") クエリを改善できます。 リクエスト パラメーターの詳細については、「クエリ (フィーチャ サービス/レイヤー)」をご参照ください。 pulldata("@layer") 関数では、フィーチャ オブジェクトを返すリクエストのみがサポートされています。
これらのパラメーターをクエリに含めるには、疑問符の後の URL にパラメーターを追加します。 追加のパラメーターはアンパサンドで区切ります。 以下の例では、orderByFields パラメーターと resultOffset パラメーターがフィーチャ レイヤー URL に追加されているため、カリフォルニアで 10 番目に人口が多い郡の名前が返されます。
pulldata("@layer", "getValue", "attributes.NAME", "https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1?orderByFields=POPULATION DESC&resultOffset=9", "STATE_NAME = 'California'")
集約されたクエリを使用すると、outStatistics パラメーターを使用してフィーチャ レイヤーに関する統計情報を返すことができます。 このパラメーターによって計算できる統計情報には、数、合計、最小値、最大値、平均、標準偏差、分散が含まれます。
次の例では、選択した州内の郡の数が返されます。
pulldata("@layer", "getValue", "attributes.TotalCount", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "count","onStatisticField": "objectId","outStatisticFieldName": "TotalCount"}]'), concat("STATE_NAME = '", ${state_name}, "'"))
次の例では、選択した州内のすべての郡における POPULATION フィールドの合計が返されます。
pulldata("@layer", "getValue", "attributes.TotalPopulation", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "sum","onStatisticField": "POPULATION","outStatisticFieldName": "TotalPopulation"}]'), concat("STATE_NAME = '", ${state_name}, "'"))
注意:
pulldata("@layer") 関数では、クエリ (フィーチャ サービス/レイヤー) に一覧表示されているすべてのリクエスト パラメーターがサポートされています。ただし、以下は除きます。
- f
- outFields
- outSR
- resultRecordCount
- returnCountOnly
- returnGeometry
- returnIDsOnly
- token
リストからの位置の取得
select_one 質問の選択肢のリストでの選択に基づき、ユーザーがフィーチャ レイヤーから位置を取得することを許可できます。 選択肢はテキストとして送信され、それに対応するジオメトリは調査回答の位置として送信されます。 このアプローチは Survey123 Web デザイナーの位置リストの質問に相当します。
位置のリストを作成するには、search と autocomplete の表示設定を持つ select_one 質問を追加します。 search の表示設定は、フィーチャ レイヤーの値をリストに設定します。 autocomplete の表示設定では、値はドロップダウン リストに表示されます。これは、フィーチャ レイヤーから非常に長いリストが返される場合に便利です。
フィーチャ レイヤーから値のリストを取得するよう search() 式を設定します。 リストから選択されたフィーチャのジオメトリを取得するよう、ジオポイント、ジオシェープ、ジオトレースの質問に pulldata("@layer") 式を追加します。
次の質問では、回答者は meter_id という select_one 質問から水道メーターを選択します。 Water Meter フィーチャ レイヤーから水道メーターのジオメトリが取得され、ジオポイントの質問に保存されます。
search の表示設定の詳細については、「検索」をご参照ください。