URL パラメーター

URL パラメーターを効果的に利用することで、ダッシュボードを拡張することができます。URL パラメーターは、作成者によってダッシュボードの構成に追加されるプロパティで、アクションを引き起こすために使用できます。URL パラメーターを使用すると、ダッシュボードをあらかじめ決められた方法で表示することができます。URL パラメーターは、ダッシュボードを別のアプリに埋め込む場合にも便利です。このシナリオでは、ホスティング アプリを使用して、ダッシュボードの現在のビューを変更できます。

メモ:

組み込みのロケール パラメーターは例外ですが、ダッシュボードのパラメーターを実行時に変更しても、最新のブラウザーで再読み込みされることはありません。

URL パラメーターは、名前と値のペアです。各パラメーターでは、名前と値は等号 (=) で区切られます。パラメーターは実行時にダッシュボードの URL の末尾に疑問符 (?) を付けて追加できます。

たとえば、パラメーターを含むダッシュボードの URL は、次のようになります。<scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value

パラメーターが複数ある場合、パラメーター間にアンパサンド (&) を追加します。<scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value&param2=value2

ヒント:

パラメーターの順序は重要ではありません。たとえば、param=value&param2=value2 と param2=value2&param=value は、同じ結果を生成します。

パラメーター名は、ASCII の英数文字から構成されます。ダッシュ (-) とアンダースコア ( _ ) も先頭以外の位置に使用できます。無効な文字は設計時にブロックされ、整合チェックの警告が表示されます。ベスト プラクティスとして、長いパラメーター名は使用しないでください。

メモ:

mode や edit など、一部のパラメーターは内部使用のために予約されています。パラメーターを作成するときに予約済みの名前を使用すると、[すでに使用されています] という整合チェックの警告が表示されます。

注意:

URL パラメーターとセレクターは、ダッシュボード エレメント間の相互作用を提供するために使用されます。ただし、同じエレメントを対象にすると、不整合が生じて予期しない結果を生じる可能性があります。ダッシュボードの対話的な操作を設計する際は注意してください。

URL のエンコード

実行時にパラメーターをダッシュボードに渡すとき、その値をエンコードします。エンコードによって、無効な文字は % と 16 進数表記に置き換えられます。

たとえば、URL パラメーターを介して Main Street という値を渡す場合、次のようになります。

<scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=Main%20Street

URL パラメーターを値のカンマ区切りリストとして渡すとき、次の点に注意してください。

• 各値を別々にエンコードします。

  正しい例

  ?param=Main%20Street,Broadway%20Avenue

  間違っている例 値を区切るために使用されるカンマはエンコードしません。

  ?param=Main%20Street%2CBroadway%20Avenue

• 値の間にスペースは入れません。

  正しい例

  ?param=Main%20Street,Broadway%20Avenue

  間違っている例

  ?param=Main%20Street, Broadway%20Avenue

URL パラメーターのタイプ

URL パラメーターには、カテゴリ、数値、日付、フィーチャ、ジオメトリの 5 つのタイプがあります。さまざまなパラメーター タイプによって引き起こされるアクションのタイプについては、「URL パラメーターでのアクションの構成」をご参照ください。

カテゴリ パラメーター

カテゴリ パラメーターを使用すると、フィルター アクションを 1 つ以上のエレメントに適用できます。設計時に、パラメーターの名前、入力のタイプが文字列と数値のどちらであるか、フィルターのクエリで渡される値を含めるか除外するかを指定します。

実行時に、カテゴリ パラメーターは、単一の値またはカンマで区切られた複数の値を受け取ります。カンマの後ろにスペースを入れないでください。

単一の値が渡される場合、クエリは内部で比較演算子の「に等しい」または「に等しくない」を使用して、ターゲット エレメントをフィルタリングします。複数の値が渡される場合、論理演算子の IN または NOT IN が使用されます。

例

次の表の備考は、カテゴリ パラメーターが文字列または数値のどちらを使用するように構成されているかを示しています。

パラメーター	備考
?status=DAMAGED	文字列
?status=DAMAGED,DESTROYED	複数の値を持つ文字列
?category=1	数値
?category=1,2	複数の値を持つ数値

特殊なケースの例

データ カテゴリは、設定されない場合や、文字列のときに空である場合があります。このため、カテゴリ パラメーターは、次の 4 つの特殊なケースをサポートしています。

• ((null))
• ((notnull))
• ((empty))
• ((notempty))

パラメーター	備考
?status=((null))	NULL である値のフィルター。
?status=((notnull)	NULL でない値のフィルター。
?status=((empty))	空である値のフィルター。
?status=((notempty))	空でない値のフィルター。
?status=DAMAGED,((null))	渡された値または NULL である値のフィルター。
?status=DAMAGED,DESTROYED,((null))	渡された複数の値または NULL である値のフィルター。

数値パラメーター

数値パラメーターを使用すると、フィルター アクションを 1 つ以上のターゲット エレメントに適用できます。設計時に、パラメーターの名前と、必要な入力値が単一の値と範囲を表す 2 つの値のどちらであるかを指定します。単一の値を使用する場合、パラメーターは、次のいずれかの比較演算子を適用するように構成されます。

• に等しい
• に等しくない
• 未満
• 以下
• より大きい
• 以上

ヒント:

範囲値タイプをより細かく制御するには、2 つの単一の数値パラメーターを作成し、要件を満たすフィルター条件 (演算子) を適用します。実行時に、単一のパラメーターは、フィルターをターゲット エレメントに適用する際に論理演算子の AND と組み合わされます。

実行時に、数値パラメーターは、単一の値またはカンマで区切られた 2 つの値として渡されます。

例

次の表の備考は、数値パラメーターが単一の値または範囲のどちらを使用するように構成されているかを示しています。

パラメーター	備考
?meas=10	単一の値
?meas=10,15	範囲

特殊なケースの例

データ内の数値は、設定されない場合があります。このため、数値パラメーターは、((null)) と ((notnull)) という 2 つの特殊なケースをサポートしています。これらの特殊なケースのラベルは、単一の値と数値範囲の両方のワークフローで使用できます。

パラメーター	備考
?meas=((null))	単一のデータ値または数値範囲。NULL である値のフィルター。
?meas=((notnull))	単一のデータ値または数値範囲。NULL でない値のフィルター。
?meas=10,((null))	単一の値。値または NULL である値のフィルター。
?meas=10,15,((null))	数値範囲。範囲内の数値または NULL である値のフィルター。

もう 1 つの特殊なケースは、数値パラメーターが範囲を使用するのに、実行時に単一の値のみが指定される場合です。

パラメーター	備考
?meas=,10	下限がありません。この値以下の値がフィルタリングされます。
?meas=10,	上限がありません。この値以上の値がフィルタリングされます。
?meas=10	上限がありません。この値以上の値がフィルタリングされます。
?meas=10,((null))	上限がありません。この値以上の値または NULL である値をフィルタリングします。

日付パラメーター

日付パラメーターを使用すると、フィルター アクションを 1 つ以上のターゲット エレメントに適用できます。設計時に、パラメーターの名前と、必要な入力値が ISO 8601 の日付文字列とエポックのどちらであるかを指定します。

日付パラメーターは、単一の値または日付範囲を表す 2 つの値を処理するように構成できます。単一の値を使用する場合、パラメーターは、次のいずれかの比較演算子を適用するように構成されます。

• に等しい
• に等しくない
• より前
• 以前
• より後
• 以後

ヒント:

範囲値タイプをより細かく制御するには、2 つの単一の日付パラメーターを作成し、要件を満たすフィルター条件 (演算子) を適用します。実行時に、単一の日付パラメーターは、フィルターをターゲット エレメントに適用する際に論理演算子の AND と組み合わされます。

実行時に、日付パラメーターは、単一の値またはカンマで区切られた 2 つの値として渡されます。日付パラメーターがエポックの場合は、符号付きの 32 ビット整数である必要があります。文字列である場合、日付の書式は YYYY-MM-DD または YYYYMMDD である必要があります。日付はグレゴリオ暦を使用して入力され、年、月、および日から構成されます。

• YYYY - 4 桁の年 (YYYY)
• MM - 2 桁の月 (01 ～ 12)
• DD - 2 桁の日 (01 〜 31)

ヒント:

日付パラメーターでサポートされる日付形式のリストは、日付を解析するためにシリアル チャートでサポートされている形式とは異なります。

時刻の部分も日付に含めることができます。時刻は 24 時間制を使用して入力され、時間、分、秒から構成されます。時刻の書式は hh:mm:ss または hhmmss を使用できます。日付に時刻の部分が含まれていない場合は、00:00:00 ～ 23:59:59 の丸一日を示唆します。

• hh - ゼロを付けた時間 (00 ～ 24)
• mm - ゼロを付けた分 (00 ～ 59)
• ss - ゼロを付けた秒 (00 ～ 59)

指定した場合、時刻の部分は日付の部分とスペースまたは大文字の T で区切られます。以下は文字列として渡される有効な日付です。

日時	備考
2018/10/31	日付のみ
20181031	日付のみ (代替形式)
2018-10-31T23:14:42	T で区切られた日付と時刻
20181031T231442	T で区切られた日付と時刻 (代替形式)
2018-10-31 23:14:42	スペースで区切られた日付と時刻
20181031 231442	スペースで区切られた日付と時刻 (代替形式)

ヒント:

大文字の T で日付と時刻を区切る方法をお勧めします。スペースを使用する場合はエンコードします。

実行時に日付をダッシュボードに渡す際、時刻コンポーネントはローカル タイム ゾーンで指定されていると見なされます。つまり、ブラウザーが動作しているコンピューターまたはデバイスのタイム ゾーンです。さらに細かく制御するために、協定世界時 (UTC) または UTC からのオフセットとして指定することもできます。その時刻が UTC であることを示すには、時刻の直後にスペースを入れずに Z の文字を追加します。Z は、UTC のオフセットがゼロのゾーン指示子です。UTC からのオフセットは、±hh:mm、±hhmm、または ±hh の形式で時刻に追加されます。

日時	備考
2018-10-31T23:14:42Z	UTC
2018-10-31T23:14:42+01:00	UTC の 1 時間先
2018-10-31T23:14:42+0100	UTC の 1 時間先
2018-10-31T23:14:42+01	UTC の 1 時間先
2018-10-31T23:14:42-05:00	UTC の 5 時間前
2018-10-31T23:14:42-0500	UTC の 5 時間前
2018-10-31T23:14:42-05	UTC の 5 時間前

日付パラメーターからフィルターを作成するとき、ダッシュボードはタイム ゾーンの情報についてターゲット エレメントの日付ソースを調べます。見つかった場合は、クエリがそのタイム ゾーンで送信されます。タイム ゾーン情報が見つからない場合、ターゲット データ ソースは UTC であると見なされます。どちらの場合も、ダッシュボードは入力時刻をターゲットの時刻と合わせるために変換する必要がある場合があります。

ヒント:

ダッシュボードが日付パラメーターを認識できない形式で受け取った場合、そのパラメーターは実行時に無視されます。

例

次の表の備考は、日付パラメーターが単一の日付または日付範囲のどちらを使用するように構成されているかを示しています。エポックおよび日付文字列の例を示します。

パラメーター	備考
?created=1541027682	エポックを使用した単一の値。
?created=2018-10-31	終日を示唆する日付文字列を使用した単一の値。
?created=2018-10-31T23:14:42	時刻付きの日付文字列を使用した単一の値。ローカル タイム ゾーンの使用が示唆されています。
?created=2018-10-31T23:14:42Z	UTC の時刻付きの日付文字列を使用した単一の値。

特殊なケースの例

日付の値は、設定されない場合があります。このため、日付パラメーターは、((null)) と ((notnull)) という 2 つの特殊なケースをサポートしています。これら特殊なケースのラベルは、単一の値と日付範囲の両方のワークフローで使用できます。

パラメーター	備考
?created=((null))	単一の日付値または日付範囲。NULL の日付のフィルター。
?created=((notnull))	単一の日付値または日付範囲。NULL でない日付のフィルター。
?created=2018-10-31,((null))	単一の日付値。10 月 31 日または NULL である日付のフィルター。
?created=2018-10-31,2018-11-05,((null))	日付範囲。範囲内の日付または NULL である日付のフィルタリング。

もう 1 つの特殊なケースは、日付パラメーターが範囲を使用するのに、実行時に単一の値のみが指定される場合です。

パラメーター	備考
?created=,2018-10-31	下限がありません。以前の日付がフィルタリングされます。
?created=2018-10-31,	上限がありません。以後の日付がフィルタリングされます。
?created=2018-10-31,((null))	上限がありません。以後の日付または NULL である日付をフィルタリングします。

フィーチャ パラメーター

フィーチャ パラメーターは、1 つ以上のフィーチャ ID をダッシュボードに渡すために使用されます。これを使用して、ダッシュボードのエレメントをフィルタリングしたり、位置のアクション ([ズーム]、[画面移動]、[ポップアップの表示]、[フィーチャに追従]、および [フラッシュ]) をダッシュボードのマップに適用したりできます。

設計時に、パラメーターの名前を指定し、データ ソースを選択します。データ ソースの一意の ID フィールドを特定する必要があります。一意でない値を含むフィールドを選択してしまうと、実行時に予期しない動作が発生する可能性があります。

ヒント:

選択したデータ ソースにポリゴンが含まれている場合、ターゲット エレメントに空間フィルターを適用するために使用できます。

実行時に、ターゲット レイヤー内の値が文字列である場合、必ずフィーチャ ID の URL をエンコードしてください。複数のフィーチャ ID は、カンマで区切って渡すことができます (例: ?asset=1240,1241,1242)。カンマの後ろにスペースを入れないでください。

ヒント:

フィーチャ パラメーターが [フィーチャに追従] アクションを実行するように構成されている場合、必要な ID は 1 つのみです。複数の値が渡される場合、1 つのフィーチャのみが追跡されます。追従されるフィーチャは、必ずしも渡される ID の順序を反映しません。

例

パラメーター	備考
?id=11033	単一の値
?id=11033,23034,34035	複数の値

ジオメトリ パラメーター

ジオメトリ パラメーターには、ポイントと範囲の 2 つのタイプがあります。タイプがポイントの場合、ジオメトリ パラメーターは、1 つ以上のダッシュボードのマップ上の位置をズーム、画面移動、またはフラッシュするために使用されます。タイプが範囲の場合、ジオメトリ パラメーターを使用して、ダッシュボードのマップ範囲を設定したり、他のエレメントをフィルタリングしたりできます。設計時に、アクションを構成する前に、パラメーターの名前を指定して、ジオメトリ タイプを選択します。

実行時に、すべてのジオメトリ座標は、カンマで区切られた WGS84 (World Geodetic System 1984) の値として渡されます。ポイント パラメーターの場合、書式は x,y です。範囲パラメーターの場合、書式は leftX,leftY,rightX,rightY です。すべての場合で、カンマの後ろにスペースは入りません。

例

パラメーター	備考
?pt=-75.6971931,45.4215296	ジオメトリ パラメーターはポイントである必要があります
?ext=-80.6,40.6,-70.7,47.7	ジオメトリ パラメーターは範囲である必要があります

ロケールの切り替え

ダッシュボードには、コンテンツを表示する際に、言語、数字、および日付の形式を変更するためのロケールという組み込み URL パラメーターがあります。ダッシュボードの URL の末尾に ?locale=<language code> パラメーターを追加します。この組み込みパラメーターを作成者が構成した URL パラメーターと組み合わせて使用するには、複数の URL パラメーターをアンパサンド (&) で区切ります。

以下の表に、サポートされている言語コードを示します。

言語コード	言語
ar	アラビア語
bs	ボスニア語
ca	カタロニア語
cs	チェコ語
da	デンマーク語
de	ドイツ語
el	ギリシャ語
en	英語
es	スペイン語
et	エストニア語
fi	フィンランド語
fr	フランス語
he	ヘブライ語
hr	クロアチア語
hu	ハンガリー語
id	インドネシア語
it	イタリア語
ja	日本語
ko	韓国語
lt	リトアニア語
lv	ラトビア語
nb	ノルウェー語 (ブークモール)
nl	オランダ語
pl	ポーランド語
pt-br	ポルトガル語 (ブラジル)
pt-pt	ポルトガル語 (ポルトガル)
ro	ルーマニア語
ru	ロシア語
sl	スロベニア語
sr	セルビア語
sv	スウェーデン語
th	タイ語
tr	トルコ語
uk	ウクライナ語
vi	ベトナム語
zh-cn	中国語 (簡体字)
zh-hk	中国語 (繁体字 - 香港)
zh-tw	中国語 (繁体字 - 台湾)

英語、スペイン語、フランス語、ドイツ語、イタリア語の言語コードの使用時に、以下のロケールを使用して、数値および日付の形式を設定することもできます。

ロケール	数字および日付の形式
en-au	英語 (オーストラリア)
en-ca	英語 (カナダ)
en-gb	英語 (英国)
es-es	スペイン語 (スペイン)
es-mx	スペイン語 (メキシコ)
fr-ch	フランス語 (スイス)
de-ch	ドイツ語 (スイス)
it-ch	イタリア語 (スイス)

次の URL は、フランス語のロケールを指定する例です。

https://<yourPortalUrl>/apps/opsdashboard/index.html#/4f539791b2f1418cb5403891f1a7be50?locale=fr