Paramètres URL

Les tableaux de bord peuvent être améliorés grâce à lʼutilisation efficace de paramètres URL. Un paramètre URL est une propriété ajoutée à la configuration du tableau de bord par son auteur et utilisée pour déclencher des actions. Les paramètres URL permettent ainsi d'afficher le tableau de bord d’une certaine façon. Les paramètres URL sont également utiles lorsqu’un tableau de bord est intégré dans une autre application. Dans ce cas de figure, l’application d’hébergement peut être utilisée pour modifier la vue actuelle du tableau de bord.

Remarque :

À l’exception du paramètre de locale intégré, la modification des paramètres du tableau de bord en cours de fonctionnement n’entraîne pas l'actualisation du tableau de bord avec la majorité des navigateurs modernes.

Un paramètre URL est une paire nom-valeur. Dans chaque paramètre, le nom et la valeur sont séparés par un signe égal (=). Lors de l’exécution, un paramètre est ajouté à l’extrémité de l’URL du tableau de bord après un point d'interrogation (?).

Voici un exemple d’URL de tableau de bord contenant un paramètre : <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value.

Dans le cas de paramètres multiples, le et commercial (&) est ajouté entre chaque paramètre : <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value&param2=value2

Astuce:

L’ordre des paramètres n’a pas d’importance. Par exemple, param=value&param2=value2 et param2=value2&param=value produisent le même résultat.

Les noms de paramètres sont composés de caractères ASCII alphanumériques. Le trait d’union (-) et trait de soulignement( _ ) peuvent également être utilisés, sauf en première position. Les caractères non valides sont bloqués lors de la conception et génèrent un avertissement de validation. L’utilisation de noms de paramètres longs est déconseillée.

Astuce:

Certains noms de paramètres sont réservés à une utilisation interne, par exemple, mode et edit. Lors de la création d’un paramètre, un avertissement de validation Already used (Déjà utilisé) s’affichera si le nom utilisé est un nom réservé.

Attention :

Les paramètres URL et les sélecteurs sont tous les deux utilisés afin de permettre l’interaction entre les éléments d’un tableau de bord. Cependant, lorsqu’ils sont utilisés pour cibler les mêmes éléments, ils peuvent générer des instructions contradictoires et provoquer des résultats non souhaités. Veillez à concevoir soigneusement les interactions de votre tableau de bord.

Encodage d’URL

Encodez la valeur du paramètre lorsque celui-ci est transmis au tableau de bord lors de l’exécution. L’encodage garantit que les caractères non valides sont remplacés par le signe % suivi de leur équivalent hexadécimal.

Par exemple, voici à quoi ressemblerait la transmission de la valeur Main Street (Rue principale) via un paramètre d’URL :

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

Gardez à l’esprit les points suivants pour transmettre un paramètre URL sous forme de liste de valeurs séparées par une virgule :

• Chaque valeur doit être encodée séparément.

  Correct

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

  Faux N’encodez pas la virgule utilisée pour séparer les valeurs.

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

• Il ne doit pas y avoir d’espaces entre les valeurs.

  Correct

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

  Incorrect

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

Types de paramètres URL

Il existe cinq types de paramètres URL : catégorie, numérique, date, entité, et géométrie. Pour plus d’informations sur les types d’actions que peuvent déclencher les différents types de paramètres, reportez-vous à la rubrique Configurer des actions sur les paramètres URL

Paramètre de catégorie

Un paramètre de catégorie permet d’appliquer un filtre sur un ou plusieurs éléments. Lors de la conception, les auteurs de tableaux déterminent le nom du paramètre, si les entrées seront de type chaîne ou chiffre et si les requêtes de filtre incluront ou excluront les valeurs transmises.

Lors de l’exécution, les paramètres de catégorie acceptent une valeur unique ou plusieurs valeurs séparées par une virgule. Il ne doit pas y avoir d’espace après la virgule.

Lorsqu’une valeur unique est transmise, la requête en arrière-plan exécutée utilise l’opérateur comparatif égale à ou non égale à pour filtrer les éléments cibles. Lorsque plusieurs valeurs sont transmises, les opérateurs logiques IN et NOT IN sont utilisés.

Exemples

Dans la table suivante, des notes indiquent si le paramètre de catégorie a été configuré pour recevoir une chaîne ou un nombre :

Paramètre	Remarque
?status=DAMAGED	Chaîne
?status=DAMAGED,DESTROYED	Chaîne avec valeurs multiples
?category=1	Nombre
?category=1,2	Nombre avec valeurs multiples

Exemples de cas spéciaux

Les catégories de données ne sont pas systématiquement définies, et dans le cas de chaînes, peuvent être vides. Par conséquent, les paramètres de catégorie prennent en charge les quatre cas spéciaux suivants :

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

Paramètre	Remarque
?status=((null))	Filtrer les valeurs NULL (nulles)
?status=((notnull)	Filtrer les valeurs qui sont NOT NULL (non nulles)
?status=((empty))	Filtrer les valeurs vides
?status=((notempty))	Filtrer les valeurs qui ne sont pas vides
?status=DAMAGED,((null))	Filtrer les valeurs transmises OU qui sont NULL (nulles)
?status=DAMAGED,DESTROYED,((null))	Filtrer les valeurs multiples transmises OU qui sont NULL (nulles)

Paramètres numériques

Les paramètres numériques permettent d’appliquer un filtre sur un ou plusieurs éléments cibles. Lors de la conception, les auteurs de tableaux de bord déterminent le nom du paramètre et si les valeurs en entrée attendues sont uniques, ou deux valeurs représentant une plage. Lorsqu’une valeur unique est utilisée, le paramètre est configuré de façon à appliquer l’un des opérateurs de comparaison suivants :

• égaux
• différent de
• plus petit que
• inférieur ou égal à
• supérieur à
• supérieur ou égal à

Astuce:

Pour contrôler de manière plus précise ce qu’offre le type de valeurs de la plage, créez deux paramètres numériques uniques et appliquez la condition de filtre (opérateur) qui correspond à vos besoins. Lors de l'exécution, les paramètres uniques seront associés à l’opérateur logique ET pour filtrer les éléments cibles.

Lors de l’exécution, les paramètres numériques sont transmis sous forme de valeur unique ou de deux valeurs séparées par une virgule.

Exemples

Dans la table suivante, des notes indiquent si le paramètre numérique a été configuré pour recevoir une valeur unique ou une plage.

Paramètre	Remarque
?meas=10	Valeur unique
?meas=10,15	Plage

Exemples de cas spéciaux

Les valeurs numériques des données ne sont pas systématiquement définies. Par conséquent, les paramètres numériques prennent en charge deux cas spéciaux : ((null)) et ((notnull)). Ces étiquettes de cas spéciaux peuvent être utilisées pour le processus de valeur unique comme pour celui de plage numérique

Paramètre	Remarque
?meas=((null))	Valeur de date unique ou plage numérique. Filtrer les valeurs qui sont NULL (nulles)
?meas=((notnull))	Valeur de date unique ou plage numérique. Filtrer les valeurs qui sont NOT NULL (non nulles)
?meas=10,((null))	Valeur unique. Filtrer selon la valeur OU les valeurs qui sont NULL (nulles)
?meas=10,15,((null))	Plage numérique. Filtrer par nombres dans la plage OU valeurs NULL (nulles)

Un autre cas spécial survient lorsqu'un paramètre numérique attend une plage, mais que seule une valeur unique est fournie lors de l’exécution.

Paramètre	Remarque
?meas=,10	Extrémité gauche ouverte. Les valeurs inférieures ou égales à cette valeur seront filtrées
?meas=10,	Extrémité droite ouverte. Les valeurs supérieures ou égales à cette valeur seront filtrées
?meas=10	Extrémité droite ouverte. Les valeurs supérieures ou égales à cette valeur seront filtrées
?meas=10,((null))	Extrémité droite ouverte. Filtre Les valeurs supérieures ou égales à cette valeur OU les valeurs NULL (nulles)

Paramètres de date

Les paramètres de date permettent d’appliquer un filtre sur un ou plusieurs éléments cibles. Lors de la conception, les auteurs de tableaux de bord déterminent le nom du paramètre et si les valeurs en entrée attendues sont de type chaîne de date au format ISO 8601 ou Epoch UNIX

Les paramètres de date peuvent être configurés afin de traiter une valeur unique ou deux valeurs représentant une plage de dates. Lorsqu’une valeur unique est utilisée, le paramètre est configuré de façon à appliquer l’un des opérateurs de comparaison suivants :

• is
• n’est pas
• est avant
• est ou est avant
• est après
• est ou est après

Astuce:

Pour contrôler de manière plus précise ce qu’offre le type de valeurs de la plage, créez deux paramètres date uniques et appliquez la condition de filtre (opérateur) qui correspond à vos besoins. Lors de l'exécution, les paramètres de date uniques seront associés à l’opérateur logique ET pour filtrer les éléments cibles.

Lors de l’exécution, les paramètres de date sont transmis sous forme de valeur unique ou de deux valeurs séparées par une virgule. Lorsqu’un paramètre de date est au format Epoch UNIX, il attend un entier 32 bits signé. Lorsqu'il s'agit d’une chaîne, les dates doivent avoir le format AAAA-MM-JJ ou AAAAMMJJ Les dates sont saisies d’après le calendrier grégorien et exprimées en années, mois et jours.

• AAAA : année exprimée par quatre chiffres (AAAA)
• MM : mois de l’année exprimé par deux chiffres (de 01 à 12)
• JJ : jour du mois exprimé par deux chiffres (de 01 à 31)

Astuce:

La liste des formats de date pris en charge par les paramètres de date est différente de celle du diagramme de série pour les dates d’analyse.

Une partie heure peut également être indiquée avec la date. Les heures sont entrées au format 24 heures et exprimées en heures, minutes et secondes. L’heure peut être exprimée au format hh:mm:ss ou hhmmss. Si la partie heure n’est pas indiquée avec la date, la totalité de la journée comprise entre 00:00:00 et 23:59:59 est utilisée.

• hh : l’heure avec ajout de zéro entre 00 et 24
• mm : les minutes avec ajout de zéro entre 00 et 59
• ss : les secondes avec ajout de zéro entre 00 et 59

Lorsqu’elle est spécifiée, la partie heure est séparée de la partie date par un espace ou un T majuscule. Les exemples suivants sont des dates valides transmises sous forme de chaînes :

Date	Remarque
2018-10-31	Date uniquement
20181031	Date uniquement (format alternatif)
2018-10-31T23:14:42	Date et heure séparées par la lettre T
20181031T231442	Date et heure séparées par la lettre T (format alternatif)
2018-10-31 23:14:42	Date et heure séparées par un espace
20181031 231442	Date et heure séparées par un espace (format alternatif)

Astuce:

Il est recommandé de séparer la date et l’heure par un T majuscule. Si vous utilisez un espace, encodez-le.

Lorsque les dates sont transmises à un tableau de bord lors de l’exécution, le composant heure est supposé être spécifié selon le fuseau horaire local. C’est-à-dire le fuseau horaire de l’ordinateur ou du dispositif sur lequel est exécuté le navigateur. Pour davantage de contrôle, l’heure peut également être exprimée en temps universel coordonné (UTC) ou selon un décalage par rapport au temps UTC. Pour indiquer que l’heure est exprimée en temps UTC, ajoutez Z directement après l’heure sans espace. La lettre Z désigne le fuseau horaire UTC sans décalage. Un décalage par rapport à l’heure UTC est ajouté à l’heure sous la forme ±hh:mm, ±hhmm, ou ±hh.

Date	Remarque
2018-10-31T23:14:42Z	UTC
2018-10-31T23:14:42+01:00	Une heure de plus que le temps UTC
2018-10-31T23:14:42+0100	Une heure de plus que le temps UTC
2018-10-31T23:14:42+01	Une heure de plus que le temps UTC
2018-10-31T23:14:42-05:00	Cinq heures de moins que le temps UTC
2018-10-31T23:14:42-0500	Cinq heures de moins que le temps UTC
2018-10-31T23:14:42-05	Cinq heures de moins que le temps UTC

Lors de la construction de filtres à partir de paramètres de date, les tableaux de bord examinent la source des données de l’élément cible pour obtenir les informations de fuseau horaire. S’il en trouve, des requêtes sont envoyées dans ce fuseau horaire. Si aucune information de fuseau horaire n’est trouvée, la source des données cible est supposée être le temps UTC. Dans les deux cas, le tableau de bord peut devoir convertir l’heure en entrée pour correspondre à celle de la cible.

Astuce:

Si un tableau de bord reçoit un paramètre de date dans un format non reconnu, ce paramètre sera ignoré lors de l’exécution.

Exemples

Dans la table suivante, des notes indiquent si le paramètre date a été configuré pour recevoir une date unique ou une plage de dates. Des exemples de formats Epoch UNIX et chaîne de date sont fournis.

Paramètre	Remarque
?created=1541027682	Valeur unique. Epoch UNIX
?created=2018-10-31	Valeur unique. Chaîne de date. Journée entière supposée
?created=2018-10-31T23:14:42	Valeur unique. chaîne de date avec heure. Fuseau horaire local supposé
?created=2018-10-31T23:14:42Z	Valeur unique. chaîne de date avec heure. UTC

Exemples de cas spéciaux

Les valeurs de dates ne sont pas systématiquement définies. Par conséquent, les paramètres de date prennent en charge deux cas spéciaux : ((null)) et ((notnull)). Ces étiquettes de cas spéciaux peuvent être utilisées pour le processus de valeur unique comme pour celui de plage de dates.

Paramètre	Remarque
?created=((null))	Valeur de date unique ou plage de dates. Filtrer par dates NULL (nulles)
?created=((notnull))	Valeur de date unique ou plage de dates. Filtrer par dates qui sont NOT NULL (non nulles)
?created=2018-10-31,((null))	Valeur de date unique. Filtrer sur le 31 octobre, OU des dates NULL (nulles)
?created=2018-10-31,2018-11-05,((null))	Plage de dates. Filtrer des dates dans la plage OU des dates NULL (nulles)

Un autre cas spécial survient lorsqu'un paramètre de date attend une plage, mais que seule une valeur unique est fournie lors de l’exécution.

Paramètre	Remarque
?created=,2018-10-31	Extrémité gauche ouverte. Filtre appliqué sur date spécifiée et dates antérieures
?created=2018-10-31,	Extrémité droite ouverte. Filtre appliqué sur date spécifiée et dates postérieures
?created=2018-10-31,((null))	Extrémité droite ouverte. Filtre appliqué sur date spécifiée ou postérieures OU dates NULL (nulles)

Paramètres d’entité

Les paramètres d’entité permettent de transmettre un ou plusieurs identifiants d’entité à un tableau de bord. Ils peuvent être utilisés pour filtrer les éléments du tableau de bord, ou pour appliquer des actions d’emplacement : Zoom, Pan (Déplacement), Show pop-up (Afficher la fenêtre contextuelle), Follow Feature (Suivi d'entité), et Flash (Faire clignoter) aux cartes du tableau de bord.

Lors de la conception, les auteurs de tableaux de bord déterminent le nom du paramètre et sélectionnent une source de données. Le champ de l’identifiant unique de la source des données doit être identifié. La sélection d’un champ contenant des valeurs non uniques entraînera un comportement inattendu lors de l’exécution.

Astuce:

Si la source de données sélectionnée contient des polygones, elle peut être utilisée pour appliquer des filtres spatiaux aux éléments cibles.

Lors de l’exécution, veillez à encoder dans l’URL les identifiants d’entités si les valeurs dans la couche cible sont des chaînes. Plusieurs identifiants d’entité peuvent être transmis en les séparant par des virgules, par exemple, ?asset=1240,1241,1242. N’utilisez pas d’espace après les virgules.

Astuce:

Si un paramètre d’entité est configuré afin d’accomplir une action de suivi d'entité, seul un identifiant est attendu. Si plusieurs valeurs sont transmises, seule l’une des entités sera suivie. L’entité suivie ne dépend pas nécessairement de l’ordre dans lequel les identifiants ont été transmis.

Exemples

Paramètre	Remarque
?id=11033	Valeur unique
?id=11033,23034,34035	Valeurs multiples

Paramètres de géométrie

Il existe deux types de paramètres de géométrie : point et étendue. Lorsque le type est point, les paramètres de géométrie sont utilisés pour zoomer, déplacer, ou faire clignoter un emplacement sur une ou plusieurs cartes du tableau de bord. Lorsque le type est étendue, les paramètres de géométrie peuvent être utilisés pour définir l’étendue d’une carte de tableau de bord ou filtrer ses autres éléments. Lors de la conception, les auteurs de tableaux de bord doivent spécifier le nom du paramètre et choisir un type de géométrie avant de pouvoir configurer une action.

Lors de l’exécution, toutes les coordonnées de géométrie sont transmises sous forme de valeurs du système de coordonnées géographiques World Geodetic System 1984 (WGS84). Pour les paramètres ponctuels, le format est x,y. Pour les paramètres d’étendue, le format est leftX,leftY,rightX,rightY. Dans tous les cas, aucun espace n’est toléré après la virgule.

Exemples

Paramètre	Remarque
?pt=-75.6971931,45.4215296	Le paramètre de géométrie attend un point
?ext=-80.6,40.6,-70.7,47.7	Le paramètre de géométrie attend une étendue

Changer de langue

Un paramètre URL, appelé locale, et intégré aux tableaux de bord permet de changer la langue d’affichage du contenu. Ajoutez le paramètre ?locale=<language code> à la fin de l’URL du tableau de bord. Le paramètre intégré peut être utilisé avec n’importe quel autre paramètre URL configuré par l’auteur. Les paramètres URL devant être séparés à l’aide du caractère &.

La table suivante répertorie les codes de langue pris en charge :

Code de la langue	Langue
ar	Arabe
bs	Bosniaque
ca	Catalan
cs	Tchèque
da	Danois
de	Allemand
el	Grec
fr	Anglais
es	Espagnol
et	Estonien
fi	Finlandais
fr	Français
he	Hébreu
hi	Hindi
hr	Croate
hu	Hongrois
id	Indonésien
it	Italien
ja	Japonais
ko	Coréen
lt	Lituanien
lv	Letton
nb	Bokmål norvégien
nl	Néerlandais
pl	Polonais
pt-br	Portugais (Brésil)
pt-pt	Portugais (Portugal)
ro	Roumain
ru	Russe
sl	Slovène
sr	Serbe
sv	Suédois
th	Thaï
tr	Turc
uk	Ukrainien
vi	Vietnamien
zh-ch	Chinois (simplifié)
zh-hk	Chinois traditionnel (Hong Kong)
zh-tw	Chinois traditionnel (Taïwan)

L’URL suivante indique comment définir la langue française :

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