Формулы

Вы можете использовать формулы для создания более сложных форм в ArcGIS Survey123.

На предыдущие вопросы всегда следует ссылаться в формулах в формате ${field_name}.

Операторы

В Survey123 поддерживаются следующие операторы Survey123:

Оператор	Описание	Пример
.	Текущий ответ	.=1
+	Сложение	${question_one} + 4
-	Вычитание	${question_one} - 4
*	Умножение	${question_one} * 4
div	Деление	${question_one} div 4
=	Равно	${price}=9.80
!=	Не равно	${price}!=9.80
<	Меньше	${price}<9.80
<=	Меньше или равно	${price}<=9.80
>	Больше	${price}>9.80
>=	Больше или равно	${price}>=9.80
and	И	${price}>9.00 and ${price}<9.90
mod	Модуль (остаток от деления)	${question_one} mod ${question_two}
or	Или	${price}=9.80 or ${price}=9.70

Функции

В Survey123 поддерживаются следующие функции:

Функция	Описание	Пример
boolean(question, expression, or value)	Возвращает true, если введенное значение не null. Лучше использовать boolean-from-string(). Внимание: Эта функция будет всегда возвращать true в веб-приложении Survey123. Для альтернативных вариантов см. Пустые значения.	boolean(${question_one})
boolean-from-string()	Возвращает true, если введенное значение 'true' или '1'. В противном случае возвращается false.	boolean-from-string(${question_one})
coalesce(value1, value2)	Возвращает первое непустое значение. Эта функция поддерживает только два значения.	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, она должна быть расположена снаружи повтора. Значение количества, расположенное снаружи повтора, может учитываться в вычислении внутри повтора.	count(${question})
count-selected(question)	Возвращает число выбранных ответов для вопросов select_one и select_multiple Эта функция также возвращает число вложенных файлов для вопросов с изображениями, аудио и файлами с помощью многострочного интерфейса.	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')
decimal-date-time(question, expression, or string)	Преобразует объект даты в десятичное число дата-время.	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()	Приводит значения даты или времени в соответствие с заданным форматом.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Если условие оценивается как истина, возвращается a, иначе возвращается b.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
индексированный повтор(вопрос, повтор, индексный номер)	Возвращает значение из определенного вопроса в записи повтора. Для получения дополнительных сведений см. раздел Повторы.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Конвертирует в целое число. Конвертация зависит от типа данных. Примечание: Если эта функция пустая, будет возвращено NaN, и вопрос останется пустым.	int(${question_one})
join(separator, question)	Объединяет все ответы на данный вопрос, разделив их указанным разделителем.	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, ...)	Возвращает максимальное значение в заданном диапазоне, или для одного вопроса в повторах.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Возвращает минимальное значение в заданном диапазоне, или для одного вопроса в повторах.	min(${question_one}, ${question_two})
not(expression)	Возвращает булево значение ложь, если выражение вернуло истину, и возвращает булево значение истина, если выражение вернуло ложь.	not(selected(., 'yes'))
now()	Возвращает текущее время для экземпляра. Эта функция используется в вопросах типа Время и ДатаВремя. Работает так же, как выражение today() iв вопросах типа Дата.	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' возвратит третий вариант.	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, она должна быть расположена снаружи повтора. Значение суммы, расположенное снаружи повтора, может учитываться в вычислении внутри повтора.	sum(${question})
today()	Возвращает сегодняшнюю дату, которая хранится внутри, как полдень по местному времени. Эта функция используется в вопросах типа Дата.	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})

Ограничения

Добавление ограничения к вопросу ограничивает допустимые входные данные для ответа. Ограничение может включать определенный диапазон значений, комбинации букв и цифр, или общий шаблон совпадений. В вашей электронной таблице ограничивающее выражение вводится в поле ограничения, а информационный текст вводится в столбце constraint_message рабочего листа опроса. В ограничительном выражении входные данные вопроса всегда представлены периодом.

Например, можно использовать следующую формулу, чтобы ограничить входные данные для целочисленного поля только положительными числами:

.>= 0

Эта формула, примененная к полю date, не позволит пользователю ввести значение ранее сегодняшнего дня.

.>= today()

Вы также можете использовать вычисления в ограничениях. Эта формула выполняет расчет, чтобы позволить пользователю выбрать даты между текущим днем и 14 днями от текущего дня:

(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))

Подсказка:

Чтобы избежать непредвиденных ошибок, если ваша формула включает десятичные значения между -1 и 1, добавьте 0 впереди для всех значений. Если не добавить 0, то десятичные значения могут быть ошибочно приняты за символ операции. (или -.). Например, следующее выражение не будет выполнено:

.> .25 and .< 24.25

Следующее выражение будет выполняться как и ожидалось:

.> 0.25 and .< 24.25

Регулярные выражения

Регулярное выражение — это последовательность символов, используемая для сопоставления шаблонов в строках. В Survey123 в случае совпадения шаблона выражение вернет значение true; в противном же случае - когда шаблон не совпадает - выражение вернет false.

Использовать регулярные выражения для установления соответствий можно по-разному: чтобы ограничить корректные ответы заданным форматом или чтобы убедиться в наличии специального содержимого в ответах. Данный пример требует, чтобы ответ на вопрос включал слово road в любой своей части:

regex(., 'road')

Период, использованный в начале этих примеров, применяет выражение к текущему полю. Добавление имени другого поля на его место сделает так, что регулярное выражение будет применяться к этому другому полю, что идеально подходит для релевантных выражений. Запятая выступает разделителем между определением поля и выражением.

Это регулярное выражение гарантирует, что ответ содержит именно слово road, и ничто не стоит перед ним или после него:

regex(., '^road$')

Регулярные выражения идеально подходят для поддержания соответствия входных данных вопроса в стандартному формату. Этот пример принимает только входные данные пятизначного почтового индекса США:

regex(., '^\d{5}$')

Этот пример соответствует ответу на текущий формат индонезийских табличек номерных знаков, как на следующем фото:

regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')

Более свободно стандартизируемые форматы могут требовать сложных регулярных выражений. Это регулярное выражение, используемое веб-приложением Survey123, ограничивает входные данные строкового поля для соответствия формату адреса эл. почты:

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, ограничивает поле таким образом, чтобы оно принимало только ответы, соответствующие формату веб-адреса:

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 или в Быстрой справке.

Вычисления

Вычисления выполняются в столбце calculation данного вопроса. Вычисления часто связаны с вопросом типа calculate, но они также могут применяться и к целочисленным, десятичным и текстовым вопросам. Выходные данные вычисления могут использоваться для заполнения связанных выражений или выражений ограничений, путем ссылки на имя поля вычисляющего вопроса.

Тип вопроса 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 вернет только часть строки, определенную числами, указанными после нее. Первый символ определяет начальную точку выборки, второе значение определяет длину (если оно не указано, действие будет продолжаться до конца строки). В данном примере оператор substr удаляет все, кроме символов строки с 10 по 15:

substr(${previous_question}, 10, 15)

Если первое число является отрицательным, substr начнет отсчет с конца строки, вместо начала. Этот пример возвращает только последние 5 символов ответа:

substr(${previous_question}, -5)

Вы можете использовать параметр calculationMode для управления вычислениями в форме. Для получения дополнительной информации см. раздел Режим вычислений.

Вы также можете использовать столбец calculation для функций агрегирования в повторах. Для получения дополнительных сведений см. раздел Повторы.

При использовании вычислений придерживайтесь следующих рекомендаций:

• При использовании random() обдумайте возможность добавления постоянного значения, чтобы избежать получения нуля (0) в качестве результата, например, random()+0.5. Нулевое значение может привести к пустому ответу.
• Как и в случае ограничений, если ваша формула включает десятичные значения между -1 и 1, убедитесь, что вы добавили 0 впереди для всех значений, иначе точка перед десятичными значениями будет приводить к ошибкам.
• Тип данных результата вычисления зависит от типа данных каждого из элементов этого вычисления. Если вычисление выполняется для двух целочисленных значений, то результат вычисления будет целочисленным. Если вычисление включает тип строковых данных, вы можете столкнуться с тем, что оператор + выполняет соединение значений, вместо добавления значений. Чтобы избежать ошибочных результатов, используйте функцию number(), чтобы убедиться, что строковые значения в вычислении обрабатываются, как числовые. Например, вычисление для добавления question1 (целочисленного типа) к question2 (текстового типа) выглядит следующим образом: ${question1} + number(${question2}).

Подсказка:

Обязательным типом XLSForm для вопроса вычисления по умолчанию является string. Чтобы перезаписать это значение по умолчанию, введите требуемый тип (например, int или decimal) в столбце bind::type для вашего вопроса. Кроме того, вы можете использовать желаемый тип вопроса (например integer или decimal) и задать для этого вопроса оформление hidden.

Внимание:

Использование математических функций или операторов с текстовыми вопросами возвращает результат NaN в веб-приложении Survey123. Чтобы соединить текстовые вопросы, используйте функцию concat() вместо оператора +.

Сложные математические функции

Столбец calculation может также выполнять более сложные математические операции. В этом примере определяется площадь участка на основе его радиуса, используя число пи и степенные функции:

pi() * pow(${plot_radius}, 2)

Обычный метод измерения высоты дерева заключается в измерении вертикального угла отрезка, соединяющего точку наблюдения с вершиной дерева и расстояния между точкой наблюдения и основанием дерева. Если вертикальный угол отрезка от наблюдателя до вершины дерева измеряется в градусах, для преобразования его в радианы будет использоваться следующая формула:

${angle_to_top_degrees} * (pi() div 180)

Теперь, когда угол измеряется в радианах, высоту дерева (округленную до двух знаков после запятой) можно по следующей формуле:

round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)

Форматирование даты

Функция format-date может использоваться в поле calculation для форматирования значений даты и времени. Это бывает полезным, когда нужно показать части дат пользователям или сохранить их в строковом формате.

В этом примере значение содержит предыдущее время или вопрос dateTime возвращен в 24-часовом формате:

format-date(${previous_time},'%H:%M')

В функции format-date используются следующие квалификаторы:

Квалификатор	Описание
%3	миллисекунды без нулей (000-999)
%a	Трехбуквенное краткое обозначение дня
%b	Аббревиатура имени месяца
%d	День месяца, без нулей
%e	День месяца
%h	Час (24 часа)
%H	Часы без нулей (24 часа)
%m	месяц, без нулей
%M	минуты без нулей
%n	Числовое значение месяца
%S	Секунды без нулей
%W	Порядковый номер недели Примечание: Квалификатор %W не может использоваться в функции format-date, в которой вопрос типа «дата» использует вычисление. Этот квалификатор работает с вопросом типа «дата», который имеет значение по умолчанию.
%y	2 цифры года
%Y	4 цифры года

Примечание:

Вопросы dateTime не поддерживают временное разрешение меньше минуты. Чтобы зафиксировать временное разрешение с датами меньше одной минуты, рассмотрите возможность использования вопросов start и end.

Пустые значения

При использовании ограничений и вычислений, ссылающихся на другие вопросы, необходимо предусмотреть тот случай, когда этот вопрос будет пустым (то есть не получит ответа). Пустые значения отображаются в следующем виде:

• NaN (не число) для целочисленных и десятичных вопросов. Это специальное значение, которое означает отсутствие корректного значения.
• '' (пустая строка) для текстовых вопросов. Типом данных по умолчанию для вопросов select_one, select_mulitple, rank и hidden также является текст. Когда вопросы типа select_one, select_multiple и hidden являются пустыми или в случае, если вопрос rank не был изменен пользователем, все они содержат пустую строку.

Поведение вычислений будет отличаться в зависимости от того, является ли значение числом или текстом.

В вопросах с целочисленными или десятичными ответами произойдет следующее:

• Любое математическое выражение со значением NaN не будет выполнено, и вопрос останется пустым.
• Функции min() и max() будут выполнены и проигнорируют все значения NaN.
• Значение NaN, если сравнивать его с любыми другими значением, может вернуть значение true только при вычислении, использующем сравнение значений is not equal. Значения всех остальных выражений будут ложными.

В текстовых вопросах произойдет следующее:

• Конкатенация текстовых вопросов будет завершена, даже если имеются пустые значения. Например, итогом concat("Hello" + ${firstName}, ", how are you?") будет "Hello , how are you?", если вопрос firstName пустой.
• Функции min() и max() будут выполнены и проигнорируют все пустые строки.
• Пустой текстовый ответ равнозначен другому пустому текстовому ответу и всегда меньше любого непустого текста.

Вы можете определить, является ли вопрос пустым, используя функцию string-length. Функцию string-length можно использовать для всех типов вопросов. Например, string-length(${Question1}) возвращает 0, если Question1 пустой.

Также вы можете определить, является ли вопрос select_one или select_multiple пустым, используя функцию count-selected. Например, count-selected(${question2}) возвращает 0, если для question2 не было сделано выборки.

Вопросы Select_multiple и rank

Ответы на вопросы типа select_multiple и rank хранятся иначе, чем ответы на все другие типы вопросов. Каждый отмеченный ответ в вопросе select_multiple вводится в порядке выбора, а ответы разделяются запятыми. Например, выбор ответов 'A' и 'B' именно в таком порядке приведет к получению ответа 'A,B'. Вопрос rank также сохраняет ответы в виде списка значений, разделенных запятыми, - от самого высокого до самого низкого ранга на момент отправки.

Некоторые элементы XLSForm не работают с вопросами типа select_multiple и rank. Например, если вы вводите ответ 'A' в столбец relevant для вопроса, ссылающегося на вопрос select_multiple, и результатом опроса будет 'A,B', то результат не будет считаться значимым. В данном случае решением будет использование функции selected(), которая проверит, присутствуют ли любые из значений в списке.

Следующее выражение, если оно используется в столбце вопроса relevant, отображает вопрос, если пользователь выбрал 'A' в качестве одного из ответов на связанный вопрос типа select_multiple. Дополнительные ответы вопроса, имеющего тип select_multiple, не меняют это поведение.

selected(${previous_question}, 'A')

Получение значения из файла .csv.

Используя функцию pulldata() в столбце вычисления вопроса, вы можете предварительно загрузить данные из файла .csv. Есть два способа включить файл .csv: вручную поместить его в папку media опроса или связать с файлом .csv, размещенным в ArcGIS.

Для функции pulldata() требуется указать указанные четыре параметра в следующем порядке:

1. Имя файла .csv, который содержит список значений. Это имя не включает расширение файла .csv.
2. Имя столбца в файле .csv, где содержится значение, которое вы хотите вернуть.
3. Имя ключевого столбца в файле .csv, который вы будете использовать для поиска этого значения.
4. Ключевое значение, которое нужно найти в ключевом поле.

Эти значения можно определить напрямую или с помощью переменных, определенных в другой части опроса. В следующем примере вычисление возвращает адрес электронной почты пользователя, имя которого выбрано в предыдущем вопросе, из файла .csv с названием info:

pulldata('info', 'email', 'name', ${respondent_name})

Та же функция pulldata() также работает со столбцом constraints, не позволяя пользователю отправить ответы, не находящиеся в файле .csv. В столбце constraints эта же формула не позволяет форме принять любые значения, не находящиеся в столбце name файла .csv.

При использовании функции pulldata() существуют некоторые ограничения. Имя ключевого поля имеет те же ограничения, что и столбец name в рабочем листе choices, что означает, что эти значения не могут содержать пробелы или символы, не являющиеся символами ASCII. Дополнительно, поскольку эти файлы являются файлами .csv, использование запятых в любом из этих полей приведет к некорректным результатам при использовании функции pulldata().

Если значения в файле .csv превышают 255 символов, потребуется ввести более высокое значение в столбец bind::esri:fieldLength для обоих вопросов, заполняемых содержанием файла .csv, и любых вопросов, которые используются в качестве входных данных для функции pulldata(). Если в файл .csv входят значения, превышающие максимальную длину одного из этих полей, ответ на опрос будет невозможно отправить и будет показана ошибка Code 1000.

Примечание:

Функция pulldata() не может использоваться для подстановки значений вопросов select_multiple.

При использовании функции pulldata() имена столбцов .csv не могут быть пустыми и не могут содержать пробелы, дефисы или другие специальные символы.

Рекомендуется кодировать файл .csv, используя кодировку UTF-8. Если вы используете 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. Например, чтобы получить свойство City из объекта address, используйте "address.City".

В следующем примере результат операции обратного геокодирования возвращается как JSON в текстовом вопросе с названием json_response:

Ответ от локатора похож на пример ниже:

{
    "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") используется для получения свойства City из объекта address:

pulldata("@json", ${json_response}, "address.City")

Широта и долгота получаются из объекта location:

pulldata("@json", ${json_response}, "location.x")

pulldata("@json", ${json_response}, "location.y")

Примечание:

Период используется для доступа к отдельным свойствам родительского объекта. Если период также является частью свойства, он должен быть заключен в квадратные скобки [ ]. Например, чтобы получить свойство City.Population из объекта address, использовалось бы выражение 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
        }
    ]
}

В приведенном выше примере следующее выражение возвращает оценку 0.67421875 для первого объекта массива classes:

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>")

Операции getRecord и getRecordAt возвращают пространственный объект JSON, содержащий один объект и все его атрибуты. Операции getValue и getValueAt возвращают одно значение из векторного объекта, а не весь ответ на запрос.

У pulldata("@layer") следующие параметры:

Параметр	Описание
JSON property	Необходимы для операций getValue и getValueAt. Значение, которое вы хотите получить из ответа на запрос. Примеры: "attributes.COUNTRY" "geometry"
location	Необходимы для операций getRecordAt и getValueAt. Местоположение точки, которую вы хотите запросить для векторного слоя. Это должен быть вопрос Геоточка. Пример: ${location}
URL	Обязательно. URL запрашиваемого векторного слоя или таблицы. Этот параметр поддерживает дополнительные параметры запроса. Пример: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Необязательно. Выражение WHERE, фильтрующее векторный слой или таблицу. Если условие WHERE не указано, используется значение "1=1" по умолчанию. Пример: "COUNTRY='Canada'"

Подсказка:

Функция pulldata("@layer") возвращает первую запись ответа на запрос. Разработайте и протестируйте свой запрос, чтобы убедиться в том, что вы получаете желаемые результаты. Вы можете уточнить свой запрос с помощью выражения WHERE и дополнительных параметров запроса, описанных ниже.

Функция pulldata("@layer") кэширует ответы на запросы для повышения эффективности. Чтобы отключить кеш и обеспечить выполнение нового запроса при каждом запуске функции, добавьте в URL-адрес параметр time=now, например concat(${layer_url}, "?t=", now()).

Следующий пример запрашивает полигональный векторный слой часовых поясов мира и возвращает часовой пояс, в котором находится геоточка:

Операция getRecordAt используется для получения часового пояса, в который попадает геоточка, с помощью следующего синтаксиса:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

Затем атрибут ZONE извлекается из ответа на запрос с помощью функции pulldata("@json"). Кроме того, вы можете использовать операцию 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") в ограничениях. Например, вы можете применить ограничение к вопросу Геоточка, чтобы пользователи не могли отправлять местоположения, находящиеся за пределами интересующей области.

Операция getRecordAt возвращает пространственный объект JSON для страны, в которой находится геоточка, посредством следующего синтаксиса:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")

Название страны извлекается в текстовый вопрос с использованием pulldata("@json"). Затем ограничение ${country}='Canada' применяется к вопросу Геоточка, чтобы убедиться в том, что местоположение попадает внутрь полигона Канады.

Параметры запроса

Можно уточнить запрос pulldata("@layer") с помощью дополнительных параметров, например, distance, orderByFields и resultOffset. Для получения дополнительной информации о параметрах запросов см. Запрос (Векторный слой/Сервис объектов). Функция pulldata("@layer") поддерживает только запросы, которые возвращают пространственный объект.

Чтобы включить эти параметры в запрос, добавьте их к URL-адресу после вопросительного знака. Дополнительные параметры разделяются амперсандами. В следующем примере параметры orderByFields и resultOffset добавляются к URL-адресу векторного слоя для возвращения названия десятого по численности населения округа Калифорнии:

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.

Чтобы создать список местоположений, добавьте вопрос select_one с поиском и автозаполнением. Оформление поиска заполняет список значениями из векторного слоя. Оформление автозаполнения представляет значения в раскрывающемся списке, что полезно, когда из слоя объектов возвращается очень длинный список.

Настройте выражение search(), чтобы извлечь список значений из векторного слоя. В вопросе geopoint, geoshape или geotrace добавьте выражение pulldata("@layer") для получения геометрии для объекта, выбранного из списка.

В приведенном примере респонденты выбирают счетчик воды из вопроса select_one под названием meter_id. Геометрия счетчика воды извлекается из векторного слоя "Water meter" и сохраняется в вопросе геоточки:

Более подробную информацию об оформлении поиска см. в разделе Поиск.