Использование параметров URL—ArcGIS Experience Builder

Примечание:

Начиная с версии Experience Builder от февраля 2024 года, сохраненные разделители URL-адресов, которых нет в значениях параметров, должны быть в виде обычного текста и не могут быть закодированы. URL-адреса с кодированными разделителями, созданные до версии февраля 2024 года, больше не работают. Вы должны заменить их на обычный текст.

Experience Builder позволяет добавлять параметры URL в ваши приложения. Вы можете использовать параметры URL для улучшения интерфейса, задав URL-адресу языковой стандарт, перенаправив на определенную страницу, активировать предварительный просмотр печати и многое другое.

Параметры добавляются в конец строки URL и форматируются в виде пар ключ-значение, через знак равенства. Приложения Experience Builder поддерживают параметры, являющиеся строками и фрагментами запроса, то есть начинающиеся с вопросительного знака (?) или решетки (#). Чтобы включить несколько параметров, их необходимо разделять амперсандами (&). URL интерфейса с параметрами использует следующую структуру:

 https://<domain>/experience/<AppID>/[?<param1=value>&<param2=value>#<param3=value>...]

Ниже приведен пример:

https://experience.arcgis.com/experience/<AppId>?locale=fr#data_s=id%3AdataSource_3-World_Cities_8506%3A1

URL интерфейса также может содержать один или несколько параметров, приведенных ниже.

Внимание:

В этом разделе квадратные скобки ([]) указывают на то, что заключенные в них параметр или значение является необязательными. Не добавляйте квадратные скобки к URL.

Основные параметры

В подразделах ниже описаны общие параметры URL.

Переключение языка

Чтобы переключить язык приложения, используйте параметр locale и двухбуквенный код языка ISO 639-1. Experience Builder поддерживает те же языки, что и ArcGIS Online, они представлены следующими языковыми кодами: ar, bg, bs, ca, cs, da, de-at, de-de, de-ch, el, en-au, en-ca, en-gb, en-us, es-es, es-mx, et, fi, fr-fr, fr-ch, he, hr, hu, id, it-it, it-ch, ja, ko, lt, lv, nb, nl, pl, pt-br, pt-pt, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-cn, zh-hk, and zh-tw.

Для использования приложения Experience Builder на французском или швейцарском французском, вы можете добавить код=fr к URL, как в следующих примерах:

https://experience.arcgis.com/experience/<AppId>/?locale=fr

https://experience.arcgis.com/experience/<AppId>/?locale=fr-ch

Примечание:

Если вы назначаете язык без уточненного идентификатора, например, fr а не fr-ch или fr-fr, возможно, формат даты или чисел не подойдет вам. Это связано с тем, что в разных регионах, где говорят на одном и том же языке, иногда используются разные обозначения дат и чисел, например, в Соединенных Штатах (en-us) и в Соединенном Королевстве (en-gb).

Определить веб-карту или веб-сцену

Чтобы отобразить карту или сцену в виджете Карта, используйте webmap или webscene, а затем идентификатор элемента карты или сцены.

https://experience.arcgis.com/builder/?webmap=<ItemID>

https://experience.arcgis.com/builder/?webscene=<ItemID>

https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544

Перейти на страницу

Для перехода на конкретную страницу используйте page после имени страницы. В приложениях ArcGIS Online Experience Builder параметры страницы не являются частью строки запроса, и не начинаются с вопросительного знака. Он добавляется к пути URL, как в следующих примерах:

https://experience.arcgis.com/experience/<AppId>/page/Page-4

https://experience.arcgis.com/experience/<AppId>/page/{xxxHome}/

Перейти к блоку

Для перехода к конкретному блоку используйте block, а затем идентификатор блока blockID. Ниже приведен пример:

https://experience.arcgis.com/experience/<AppId>/?block_id=layout1_block1

Чтобы найти идентификатор блока blockID, вы можете установить ссылку на блок на кнопке, изображении или любом другом виджете, который поддерживает опцию Задать ссылку. Когда вы предварительно просматриваете приложение и нажимаете связанный виджет, в URL-адресе появляется идентификатор блока.

Перейти к виду

Чтобы напрямую перейти к указанному конкретному виду раздела, используйте views после подписи вида, например v1 или View 1.

https://experience.arcgis.com/experience/<AppId>/?views=View-2

https://experience.arcgis.com/experience/<AppId>/?views=v1

Открыть окно

Чтобы напрямую перейти к указанному активному окну, используйте dlg после ID или подписи окна.

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1

Фокус окна элементов управления

Чтобы встроить приложение Experience Builder с окнами приветствия или окнами страниц или фиксированными окнами без автоматического перехода приложения к этим окнам, вы можете используйте параметр disable_window_focus. Добавьте следующий URL-адрес на веб-страницу хоста, чтобы отключить поведение перемещения. По умолчанию disable_window_focus имеет значение false.

https://experience.arcgis.com/experience/<AppId>/?disable_window_focus=true

Чтобы управлять фокусом для определенного окна, используйте dlg с последующим идентификатором окна или надписи и параметр disable_window_focus, как в следующем примере:

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1&disable_window_focus=true

Режим просмотра черновика

Каждый раз при предварительном просмотре приложения, параметр draft добавляется автоматически. Это позволяет вам получать доступ к ресурсам элементов для неопубликованных приложений.

https://experience.arcgis.com/experience/<AppId>/?draft=true

https://experience.arcgis.com/experience/<AppId>/?draft=1

Открыть предварительный просмотр печати

Для активации режима предварительного просмотра печати используйте print_preview.

https://experience.arcgis.com/experience/<AppId>/?print_preview=true

https://experience.arcgis.com/experience/<AppId>/?print_preview=1

Параметры, связанные с данными

В подразделах ниже описаны связанные с данными параметры URL.

Выбор данных

Чтобы выбрать записи данных, используйте параметр data_s, который следует за решеткой (#).

Каждый источник данных в приложении содержит собственный идентификатор (ID) источника данных. Если вы выбираете запись данных, идентификатор источника данных добавляется к URL приложения, а также тип выбора и условие выбора. Если у вас несколько выборок, они будут разделены запятыми (,). Ниже приведен пример:

https://experience.arcgis.com/experience/<AppId>/#data_s=<selection type>:<data source ID>:<selection condition>,<selection type>:<data source ID>:<selection condition>,...

Существует три типа выборок: id, geometry и where.

Если тип выборки id, вы выбираете объекты по их идентификаторам записей. Если вы выбираете несколько записей из одного и того же источника данных, идентификаторы записей разделяются знаком плюс (+). Ниже приведен пример:
```
https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3
```
Если тип выборки geometry, вы выбираете объекты на основе их местоположения относительно других объектов. Идентификаторы нескольких источников данных соединяются тильдами (~). Ниже приведен пример:
```
https://experience.arcgis.com/experience/<AppId>/#data_s=geometry:widget_1-dataSource_1-1871234a785-layer-2~widget_1-dataSource_1-1871234a785-layer-3:<the geometry JSON>
```
Если тип выборки where, вы выбираете объекты на основе их атрибутов. Ниже приведен пример:
```
https://experience.arcgis.com/experience/<AppId>/#data_s=where:widget_1-dataSource_1-1871234a785-layer-2:a>1
```

Вы можете использовать этот параметр для поиска ID источников данных слоя. Например, вы можете добавить виджет Список и подключить его к слою, просмотреть приложение и выбрать любую запись в списке. URL-адрес заполняется как указано в следующем примере:

https://experience.arcgis.com/experience/<AppID>/#data_s=id%3AdataSource_3-World_Cities_8506%3Axxxxxx

Значение после id%3A и перед %3Axxxx является идентификатором источника данных слоя (ID). Зная ID вы можете использовать его с другими параметрами, чтобы применять фильтры к источникам данных или изменять версии.

Примечание:

Experience Builder ранее использовал параметр ?data_id для выбора данных. Этот параметр в настоящее время ещё поддерживается, но вскоре станет устаревшим.

Фильтр источников данных

Чтобы напрямую использовать фильтр источника данных data_filter. Формат фильтра - стандартный синтаксис условия WHERE. Для применения фильтра к нескольким источникам данных используйте формат [<dsId:filter>,<dsId:filter>].

Внимание:

Некоторые фильтры могут содержать символы, которые являются сохраненными разделителями URL-адресов (например, "&", "=", "'" и "?"). Чтобы быть уверенными в правильной интерпретации значений URL-адресом, необходимо закодировать небезопасные символы URL-адресом, заменив их символом %, за которым будет идти значение, соответствующее их шестнадцатеричному эквиваленту UTF-8.

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


Небезопасный символ	Закодированное значение
ПРОБЕЛ	%20
#	%23
%	%25
&	%26
'	%27
,	%2C
:	%3A
=	%3D
?	%3F

Примечание:

Вам нужно закодировать небезопасные символы только в значениях параметров. Если символ выполняет функцию разделителя URL-адресов, то есть не является значением параметра, он должен быть обычным текстом и не подлежит кодированию.

Ниже следует URL-адрес с незакодированным фильтром, который не будет правильно работать:

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name='Even&Odd'

Следующий URL-адрес представляет собой правильно закодированную версию URL-адреса выше. Обратите внимание, что некоторые символы из приведенной выше таблицы не закодированы. Это потому, что они действуют как разделители URL-адресов.

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27

Далее показан другой URL с кодированными параметрами фильтра (objectid=1 и fieldA>2):

https://experience.arcgis.com/experience/<AppId>/?data_filter=ds1:objectid%3D1,ds2:fieldA%3E2

Изменение версии базы геоданных источника данных

Чтобы изменить версию базы геоданных источника данных, используйте data_version.

https://experience.arcgis.com/experience/<AppId>/?data_version=<dsId:version>,<dsId:version>

https://experience.arcgis.com/experience/<AppId>/?data_version=dsId1:v1, dsID2:v1

Параметры, связанные с виджетом

Вы можете использовать URL-адрес приложения, чтобы влиять на поведение виджета, добавляя параметры URL-адреса виджета. Хотя разные параметры встраиваются разными методами, они обычно придерживаются одного и того же синтаксиса:

https://experience.arcgis.com/experience/<AppId>#widget_1=param1:<value>,param2:<value>&widget_2=param1:<value>&...

Параметры виджета начинаются в URL-адресе с хэш-меток (#) и объединяются в цепочку с помощью амперсандов (&). Если у вас есть несколько параметров, влияющих на один и тот же виджет, они разделяются запятыми.

Некоторые значения могут содержать символы, которые являются сохраненными разделителями URL-адресов (например, "&", "=", "'" и "?"). Чтобы быть уверенными в правильной интерпретации значений URL-адресом, необходимо закодировать небезопасные символы URL-адресом, заменив их символом %, за которым будет идти значение, соответствующее их шестнадцатеричному эквиваленту UTF-8. Разделители URL-адресов вне значений параметров должны быть в виде обычного текста и не подлежат кодированию.

Например, параметр center в следующем примере не будет работать правильно, поскольку необходимо закодировать два символа запятой.

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100,100,102100,rotation:45

Ниже приведена правильно написанная версия URL-адреса выше:

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45

Параметры виджета Карта

В подразделах ниже описаны связанные с картой параметры URL. Можно использовать настройки в разделе Управление статусом URL, чтобы эти параметры появлялись в URL-адресе, когда пользователь взаимодействует с виджетом Карта. Все параметры виджета Карта следуют за решетками (#).

Примечание:

Параметры виджета Карта center, scale и rotation работают только с веб-картами, а не с веб-сценами.

Определить веб-карту или веб-сцену при первой загрузке виджета Карта

Если виджет Карта содержит несколько веб-карт или веб-сцен, вы можете определить, какая из них активна при загрузке приложения, используя active_datasource_id, за которым следует идентификатор источника данных нужного элемента. Ниже приведены примеры:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>

https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4

Центрировать карту

Чтобы центрировать карту в определенном месте, используйте center, затем укажите нужные координаты и известный идентификатор данной системы координат (WKID). Ниже приведены примеры:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=center:<x,y,wkid>

https://experience.arcgis.com/experience/<AppId>#map_1=center:-10373125.398783844%2C4598516.55871741%2C102100

Определить масштаб карты

Чтобы определить масштаб карты, используйте параметр scale, за которым следует значение масштаба. Ниже приведены примеры:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>

https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833

Определить поворот карты

Чтобы определить поворот карты, используйте параметр rotation, за которым следует значение градусов. Ниже приведены примеры:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>

https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45

Определение точки обзора карты

Чтобы определить параметр viewpoint, т.е. местоположение или положение камеры, с которого можно просматривать карту или сцену, используйте viewpoint. Если виджет Карта содержит несколько карт или сцен, параметр точки обзора влияет на все из них.

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

 {
  "rotation": 0,
  "scale": 19966005.903731048,
  "targetGeometry": {
    "spatialReference": {
      "latestWkid": 3857,
      "wkid": 102100
    },
    "x": -9870655.016044471,
    "y": 4724533.527708739
  }
}

Чтобы определить конкретную точку обзора с помощью URL-адреса, вы должны закодировать все эти свойства, обычно записанные в формате JSON, в URL-адрес. Ниже приведен пример:

https://experience.arcgis.com/experience/<AppId>#map_1=viewpoint:%7B"rotation"%3A0%2C"scale"%3A24387741.012671936%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-10078461.002935613%2C"y"%3A4523117.553838721%7D%7D

Примечание:

Параметры center, scale и rotation имеют более высокий приоритет, чем параметр viewpoint, и будут переопределять его, если вы используете несколько параметров, связанных с веб-картой.

Примечание:

Изменения экстента карты, вызванные действиями с сообщением, имеют более высокий приоритет, чем изменения экстента, вызванные параметрами URL. Например, если вы попытаетесь открыть виджет Карта с предустановленными экстентами, используя приведенные выше параметры URL-адреса, но при этом виджет Карта также настроен как цель триггера Изменения выборки записей и действий с сообщениями Переместить или Приблизить, тогда экстенты, связанные с действиями с сообщением заменяют экстенты, которые вы установили с помощью параметров URL-адреса.

Определить видимость слоев карты

Чтобы определить видимость слоя карты, используйте параметр layer_visibility.

Видимость слоя обычно записывается в формате JSON, как в следующем примере:

 {
  "widget_1-dataSource_1": {
    "widget_1-dataSource_1-187938b7328-layer-2": false
  },
  "widget_1-dataSource_4": {
    "widget_1-dataSource_4-18a690b433a-layer-4": false
  }
}

Чтобы сделать слои на карте видимыми или скрытыми с помощью URL-адреса, вы должны закодировать всю информацию в URL-адресе после параметра layer_visibility. Ниже приведен пример:

https://experience.arcgis.com/experience/<AppId>#map_1=layer_visibility:%7B%22widget_1-dataSource_1%22%3A%7B%22widget_1-dataSource_1-187938b7328-layer-2%22%3Afalse%7D%2C%22widget_1-dataSource_4%22%3A%7B%22widget_1-dataSource_4-18a690b433a-layer-4%22%3Afalse%7D%7D

Параметры виджета Поиск

В подразделах ниже описаны связанные с поиском параметры URL. Можно использовать настройки в разделе Управление статусом URL, чтобы эти параметры появлялись в URL-адресе, когда пользователь выполняет поиск. Параметры виджета поиска следуют за хэш-метками (#).

Показать вводимые данные поиска

Параметр searchText показывает, какой текст ввел пользователь для выполнения поиска. Ниже приведен пример URL-адреса с параметром searchText:

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D

Показать источник поиска

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

Если хотя бы один источник поиска не отмечен в раскрывающемся меню виджета во время запуска, появляется параметр serviceEnabledList, определяющий, какие источники поиска отмечены. Этот параметр скрыт, когда отмечены все источники поиска. Ниже приведен пример закодированного URL-адреса:
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D
```
Если пользователь нажимает на предложение поиска, чтобы применить поиск, появляется параметр "status":{"configId":"<SourceID>"}, определяющий уникальный источник поиска, используемый в текущем поиске. В URL-адресе появляются как вводимые данные поиска, так и источник поиска. Ниже приведен пример закодированного URL-адреса:
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D
```

Если пользователь нажимает на предложение поиска из источника локатора, в URL-адресе отображается magicKey, связанная с этим предложением. magicKey - это уникальный идентификатор, который связывает предположение конкретным адресом или местом. Ниже приведен пример свойств и параметров поиска, записанных в формате JSON:

{
	"searchText": "<text>",
	"status":{
		"configId": "<SourceID>",
		"magicKey": "<key>"
	}
}

Ниже приведен пример тех же свойств и параметров, что и выше, записанных в закодированном URL-адресе:

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%2C"magicKey"%3A"<key>"%7D%7D

Параметры, связанные с именем пользователя

В подразделах ниже описаны связанные с именем пользователя параметры URL.

Доступ к аутентификации через виджет Встроить

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

Чтобы встроить веб-приложение ArcGIS в приложение Experience Builder и обязать пользователей выполнять вход в систему, вы можете добавить параметры URL arcgis-auth-origin и arcgis-auth-portal, чтобы совместно использовать аутентификацию между обоими приложениями, а пользователям нужно было входить только один раз.

Чтобы встроить частное приложение Experience Builder в другое приложение Experience Builder, используйте ?arcgis-auth-origin= для определения URL-адреса домена хост-приложения для аутентификации. Ниже приведен пример:

https://<orgdomain>/experience/<AppID>/?arcgis-auth-origin=<your host app domain, such as https://localhost:3001>

Чтобы внедрить приложение на основе JavaScript API, например, приложение Web AppBuilder, используйте ?arcgis-auth-origin= для проверки подлинности домена хост-приложения и ?arcgis-auth-portal= для JavaScript для портала ArcGIS, с которого требуется проверка подлинности приложения на основе JavaScript API. Ниже приведены примеры:

https://<orgdomain>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>&arcgis-auth-portal=<orgA URL>

https://www.arcgis.com/apps/dashboards/index.html#/<appID>?arcgis-auth-origin=https://experience.arcgis.com&arcgis-auth-portal=https://<myorg>.maps.arcgis.com

Переход пользователей на страницу входа в организацию

Как правило, если пользователи пробуют получить доступ к персональному приложению Experience Builder на ArcGIS Online, они перенаправляются на основную страницу входа ArcGIS Online. Чтобы перенаправить пользователей на страницу входа в организацию, используйте org после короткого имени вашей организации.

https://experience.arcgis.com/experience/<AppId>/?org=<yourorgshortname>

Отзыв по этому разделу?