URL パラメーターの使用—ArcGIS Experience Builder

注意:

2024 年 2 月リリースの Experience Builder では、保持された URL の区切り文字のうち、パラメーター値に含まれていない文字はプレーンテキストである必要があり、エンコードすることはできません。 2024 年 2 月リリース以前に作成された、エンコードされた区切り文字を含む URL は機能しなくなりました。プレーンテキストに変更する必要があります。

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 には、次に示す 1 つ以上のパラメーターが含まれていることがあります。

注意:

このトピックでは、角括弧 ([]) で囲まれたパラメーターまたは値は任意であることを意味します。 URL に角括弧を追加しないでください。

一般パラメーター

次のサブセクションでは、一般的な URL パラメーターについて説明します。

ロケールの切り替え

アプリの言語を切り替えるには、locale パラメーターと 2 文字の 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、zh-tw。

Experience Builder アプリをフランス語とスイス・フランス語で使用するには、次の例に示すように locale=fr を URL に追加します。

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

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

注意:

fr-ch や fr-fr ではなく fr のように、詳細ロケールなしで言語のみを指定した場合、日付と数値の形式が正しく表示されない可能性があります。これは、米国 (en-us) と英国 (en-gb) のように、同じ言語を話す異なるロケールで、日付と数値の表記が異なる場合があるためです。

Web マップまたは Web シーンの定義

マップウィジェットにマップまたはシーンを表示するには、webmap または webscene の後ろにマップまたはシーンのアイテム ID を指定します。

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 アプリでは、page パラメーターはクエリ文字列の一部ではないため、先頭に疑問符を付けません。次の例に示すように、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 に blockID が表示されます。

ビューに移動

特定のアクティブなセクションビューに移動するには、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 をホスト Web ページに追加して、移動の動作を無効にします。デフォルトでは、disable_window_focus は false です。

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

特定のウィンドウに対し、ウィンドウのフォーカスを制御するには、次の例に示すように、dlg の後にウィンドウ ID またはラベルを付け、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 があります。データレコードを選択すると、データソースの 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 の 3 種類があります。

選択タイプが id の場合、フィーチャは recordID で選択されています。同じデータソースから複数のレコードを選択する場合、recordID はプラス記号 (+) で区切られます。例を以下に示します。
```
https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3
```
選択タイプが geometry の場合、フィーチャは、他のフィーチャに対する位置に基づいて選択されます。複数のデータソース ID は、チルダ (~) で接続されます。例を以下に示します。
```
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 16 進数に相当する値を入力します。

パラメーター値に含まれる場合にエンコードの必要がある一般的な文字を次の表に示します。


安全でない文字	エンコード値
スペース	%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

次に、2 つのエンコードされたフィルターパラメーター (objectid=1 と fieldA>2) を含む URL の例を示します。

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 16 進数に相当する値を入力します。パラメーター値以外の URL の区切り文字は、プレーンテキストである必要があり、エンコードすることはできません。

たとえば、以下に示す「center」パラメーターは正しく機能しません。これは、カンマ文字の 2 つをエンコードする必要があるからです。

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」パラメーターは、Web マップでのみ使用できます。Web シーンでは使用できません。

マップウィジェットの初回読み込み時の Web マップまたは Web シーンの定義

マップウィジェットに複数の Web マップまたは Web シーンが含まれている場合、アプリが読み込まれたときにアクティブになる Web マップまたは Web シーンを指定するには、「active_datasource_id」の後に目的のアイテムのデータソース 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」の後に目的の座標と、目的の座標系の Well-Known ID (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 パラメーターよりも優先度が高く、Web マップに関連する複数のパラメーターが使用される場合は、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 を使用して、マップのレイヤーを表示したり非表示にしたりするには、「layer_visibility」パラメーターの後に続くすべての情報を URL にエンコードする必要があります。例を以下に示します。

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」パラメーターは、検索の実行のためにユーザーが入力したテキストを表示します。「searchText」パラメーターを使用した URL の例を次に示します。

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

検索ソースの表示

ユーザーが利用可能な検索ソースの一部のみを使用して検索を実行する場合、次の 2 つのパラメーターの 1 つが URL に表示されます。

実行時にウィジェットのドロップダウンメニューで少なくとも 1 つの検索ソースがオフになっている場合、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
```

ユーザーがロケーターソースから検索候補をクリックした場合、候補に関連付けられている magicKey が URL に表示されます。 magicKey は、候補を特定の住所または場所にリンクする一意の ID です。 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 パラメーターについて説明します。

埋め込みウィジェットによる認証の共有

Web アプリの中には、ArcGIS アカウントを使用してサインインするよう求めるものがあります。共有設定のため、プレミアムコンテンツを使用するウィジェットがアプリに含まれるため、その他の理由により、アプリによってはユーザーのサインインが必要な場合があります。

ArcGIS Web アプリを Experience Builder アプリに埋め込み、両アプリがユーザーのサインインを必要とする場合、arcgis-auth-origin パラメーターと arcgis-auth-portal URL パラメーターを追加して両アプリで認証を共有すると、一度サインインするだけで済みます。

プライベートの 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=、JavaScript API ベースのアプリが認証を必要とする ArcGIS ポータル用に JavaScript 用の ?arcgis-auth-portal= を使用します。以下に例を示します。

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

組織のサインインページへのユーザーの移動

一般に、ユーザーが ArcGIS Online 上のプライベートの Experience Builder アプリにアクセスしようとすると、メインの ArcGIS Online サインインページに移動します。ユーザーが代わりに組織のサインインページに移動するようにするには、org の後ろに組織の略称を指定します。

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

このトピックへのフィードバック

注意:

注意: