Paramètres URL

Une utilisation efficace des paramètres URL permet d’améliorer les tableaux de bord. 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 incorporé dans une autre application. Dans ce cas de figure, vous pouvez utiliser l’application d’hébergement 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, vous pouvez ajouter un paramètre à la fin 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, ajoutez le caractère et commercial (&) 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.

Remarque :

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’affiche 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 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 :

• Encodez chaque valeur 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

• N’ajoutez pas d’espace 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

Vous pouvez utiliser un paramètre de catégorie pour appliquer une action de filtre sur un ou plusieurs éléments. Lors de la conception, déterminez 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. N’utilisez pas d’espace après la virgule.

Lorsqu’une valeur unique est transmise, la requête en arrière-plan utilise l’opérateur comparatif égal à ou non égal à 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 est 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 qui sont NULL (nulles).
?status=((notnull)	Filtrer les valeurs qui sont NOT NULL (non nulles).
?status=((empty))	Filtrer les valeurs qui sont 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

Vous pouvez utiliser des paramètres numériques pour appliquer une action de filtre sur un ou plusieurs éléments cibles. Lors de la conception, déterminez le nom du paramètre et si les valeurs en entrée attendues sont une valeur unique 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 sont 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 est 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)). Vous pouvez utiliser ces étiquettes de cas spéciaux pour les processus avec valeur unique et avec 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 sont filtrées.
?meas=10,	Extrémité droite ouverte. Les valeurs supérieures ou égales à cette valeur sont filtrées.
?meas=10	Extrémité droite ouverte. Les valeurs supérieures ou égales à cette valeur sont 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

Vous pouvez utiliser des paramètres de date pour appliquer une action de filtre sur un ou plusieurs éléments cibles. Lors de la conception, déterminez 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

Vous pouvez configurer les paramètres de date 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 sont 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 doit s’agir d’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 pourl’analyse de dates.

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. Vous pouvez leur appliquer le 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 des dates sont transmises à un tableau de bord au moment de l’exécution, leur composant temporel est censé être spécifié dans le fuseau horaire local, c’est-à-dire le fuseau horaire de l’ordinateur ou de l’appareil sur lequel s’exécute le navigateur. Pour davantage de contrôle, vous pouvez également exprimer l’heure 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 la lettre 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 est ignoré lors de l’exécution.

Exemples

Dans la table suivante, des notes indiquent si le paramètre de date est 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 avec UNIX Epoch.
?created=2018-10-31	Valeur unique avec chaîne de date, journée entière supposée.
?created=2018-10-31T23:14:42	Valeur unique avec chaîne de date et heure. Fuseau horaire local supposé.
?created=2018-10-31T23:14:42Z	Valeur unique avec chaîne de date et heure en 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 ou dates antérieures.
?created=2018-10-31,	Extrémité droite ouverte. Filtre appliqué sur date spécifiée ou dates postérieures.
?created=2018-10-31,((null))	Extrémité droite ouverte. Filtre appliqué sur date spécifiée ou dates 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, déterminez le nom du paramètre et sélectionnez 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îne 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 est 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, vous pouvez utiliser les paramètres de géométrie pour définir l’étendue de la carte d’un tableau de bord ou filtrer ses autres éléments. Lors de la conception, déterminez le nom du paramètre et sélectionnez le type de géométrie avant de configurer des actions.

Lors de l’exécution, toutes les coordonnées de géométrie sont transmises sous forme de valeurs séparées par des virgules 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é paramètre régional, et intégré aux tableaux de bord permet de changer les formats numériques, de langue et de date pour afficher 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	English (Anglais)
es	Espagnol
et	Estonien
fi	Finlandais
fr	Français
he	Hébreu
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
sur 5	Thaï
tr	Turc
uk	Ukrainien
vi	Vietnamien
zh-cn	Chinois (simplifié)
zh-hk	Chinois traditionnel (Hong Kong)
zh-tw	Chinois traditionnel (Taïwan)

Avec les codes de langue anglaise, espagnole, française, allemande et italienne, vous pouvez également utiliser les paramètres régionaux suivants pour définir le format numérique et de date :

Paramètre régional	Format de nombre et de date
en-au	Anglais (Australie)
en-ca	Anglais (Canada)
en-gb	Anglais (Grande-Bretagne)
es-es	Espagnol (Espagne)
es-mx	Espagnol (Mexique)
fr-ch	Français (Suisse)
de-ch	Allemand (Suisse)
it-ch	Italien (Suisse)

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

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