Guide du développeur GlideGeoPoint
Le guide du développeur GlideGeoPoint contient des informations sur la façon de calculer les distances entre les valeurs de latitude et de longitude (géopoints), de renvoyer les emplacements dans des valeurs de géopoint et de rayon données et d’utiliser des fonctionnalités supplémentaires fournies par les fonctions de l’API GlideGeoPoint prises en charge.
L’vous Geo point field type permet de stocker une paire de latitudes et de longitudes dans un seul champ. Les géopoints peuvent être utiles chaque fois que vous souhaitez stocker un point d’intérêt géographique, pour demander à quelle distance se trouvent deux points d’intérêt l’un de l’autre ou pour rechercher tous les points situés à une certaine distance d’un autre point. Par exemple, vous pouvez utiliser la fonctionnalité de géopoint pour déterminer rapidement tous les lieux de livraison de vos clients, puis ajuster les frais de livraison en fonction de leur distance par rapport au magasin.
- Il se compose d’une paire de nombres décimaux représentant les valeurs de longitude et de latitude.
- La plage de longitude est de (-180, 180). Toute valeur en dehors de cette plage est normalisée à la valeur équivalente à l’intérieur de cette plage.
- La plage de latitude est [-90, 90]. Toute valeur en dehors de cette plage est normalisée à la valeur équivalente à l’intérieur de cette plage.
- Les valeurs de géopoints sont toujours acceptées en entrée et s’affichent sous la forme d’une paire séparée par des virgules : « longitude,latitude ». Des parenthèses peuvent éventuellement entourer l’expression.
- Les valeurs de longitude et de latitude sont stockées jusqu’à 6 décimales de précision.
Pour plus d’informations sur le type de données de géopoint, reportez-vous à la section Function field.
Les exemples de ce guide supposent qu’une table personnalisée, u_geopoint, est renseignée avec les champs u_name et u_location, où u_name est de type « chaîne » et répertorie les noms des grandes villes et u_location est de type « géopoint » et répertorie les points de latitude/longitude de chaque ville respectivement.
Créer des géopoints à l’aide de l’API GlideGeoPoint
Utilisez l’API GlideGeoPoint pour insérer de nouveaux enregistrements et créer de nouveaux géopoints.
L’API GlideGeoPoint : global vous permet de définir et de récupérer des valeurs de géopoints. Toutefois, vous pouvez exécuter des fonctionnalités supplémentaires pour insérer de nouveaux enregistrements en définissant des géopoints directement dans un script à l’aide d’une notation de chaîne ou d’un objet GlideGeoPoint.
- Insertion d’un nouvel enregistrement à l’aide de la notation de chaînes.
- Définissez la valeur du champ de géopoint
u_locationà l’aide d’une chaîne. La chaîne se compose d’une paire de valeurs de longitude et de latitude séparées par des virgules. L’exemple suivant montre comment définir un nouveau géopoint dans la tablede u_geopointà l’aide de la notation de chaînes.Remarque :GlideGeoPoint (en anglais seulement) Les valeurs API sont toujours répertoriées par ordre de longitude et de latitude.const longitude = "-87.628018"; const latitude = "41.885778"; const geopoint = longitude + "," + latitude; const myGeoPoint = new GlideRecord("u_geopoint"); myGeoPoint.initialize(); myGeoPoint.setValue("u_name", "Chicago"); myGeoPoint.setValue("u_location", geopoint); myGeoPoint.insert(); - Insertion d’un nouvel enregistrement à l’aide de l’objet GlideGeoPoint.
- Définissez la valeur du champ de géopoint
u_locationà l’aide d’un objet GlideGeoPoint.const longitude = -87.628018; const latitude = 41.885778; const geopoint = new GlideGeoPoint(longitude, latitude); const myGeoPoint = new GlideRecord("u_geopoint"); myGeoPoint.initialize(); myGeoPoint.setValue("u_name", "Chicago"); myGeoPoint.setValue("u_location", geopoint); myGeoPoint.insert();
Lire les valeurs de géopoints à l’aide de l’API GlideGeoPoint
Utilisez la fonction de l’API GlideGeoPoint getDisplayValue() pour lire toutes les valeurs de géopoint d’une table spécifique.
L’API standard GlideGeoPoint vous permet de récupérer une valeur de géopoint via la GlideGeoPoint : getDisplayValue() fonction. Cependant, il est possible de lire tous les géopoints définis dans un tableau entier. L’exemple de script suivant montre comment utiliser la fonction getDisplayValue() pour récupérer tous les enregistrements de la table u_geopoint , qui inclut le champ u_location de type « geopoint ». Vous pouvez utiliser cet exemple de script et l’adapter à votre cas d’utilisation spécifique.
const myGeoPoint = new GlideRecord("u_geopoint");
myGeoPoint.query();
while (gr.next())
gs.info("Name: {0} Location: {1}",
myGeoPoint.getDisplayValue('u_name'),
myGeoPoint.getDisplayValue('u_location'));La sortie renvoie tous les enregistrements de la table u_geopoint . La valeur d’affichage d’un géopoint comprend la longitude suivie de la latitude, séparée par une virgule et entourée de parenthèses.
Name: London Location: (-0.189937, 51.473584)
Name: Puerto Rico Location: (-66.561301, 18.291136)
Name: Glasgow Location: (-4.223964, 55.867846)
Name: Chicago Location: (-87.628018, 41.885778)
Name: Tasmania Location: (146.757677, -42.173578)
Name: Bermuda Location: (-64.761595, 32.315798)
Name: Miami Location: (-80.206458, 25.767242)
Name: Sydney Location: (151.205230, -33.890115)
Name: Perth Location: (115.871253, -31.971583)
Name: Dublin Location: (-6.304994, 53.348317)Calculer la distance entre deux géopoints
Utilisez la fonction de glissement distance_sphere pour renvoyer la distance entre les géopoints en mètres.
La fonction de glissement du géopoint, distance_sphere, vous permet de calculer la distance entre deux géopoints. La fonction renvoie la distance en mètres. distance_sphere peut être utilisé dans la définition d’un élément de champ de fonction sur une table ou via un script. Trois syntaxes sont prises en charge et tous les paramètres sont requis :
glidefunction :distance_sphere(geopoint1, geopoint2)glidefunction :distance_sphere(geopoint1, longitude2, latitude2)glidefunction :distance_sphere(longitude1, latitude1, longitude2, latitude2)
Lorsque vous utilisez ces syntaxes, notez que :
- geopoint1 et geopoint2 sont des éléments de table de type 'geopoint'
- longitude1, longitude 2, latitude 1, latitude 2 sont des éléments de table numérique ou des constantes
- Dans tous les cas, la valeur de retour de cette fonction est une décimale représentant la distance entre deux géopoints en mètres
L’exemple de script suivant définit une fonction distance_sphere pour calculer la distance entre tous les géopoints stockés dans le champ u_location de la table u_geopoint et le point -0,189937 de longitude, 51,473584 de latitude (qui correspond approximativement à l’emplacement de Londres). La fonction est ajoutée à la requête GlideRecord pour produire des résultats.
const distToLondon =
"glidefunction:distance_sphere(u_location, '-0.189937', '51.473584')";
const myGeoPoint = new GlideRecord('u_geopoint');
gr.addFunction(distToLondon);
gr.query();
while(myGeoPoint.next())
gs.info("Name: {0} Dist to London(m): {1}",
myGeoPoint.u_name, gr.getValue(distToLondon));La sortie indique la distance entre Londres et les villes dans le champ u_location en mètres.
Name: London Dist to London(m): 0
Name: Glasgow Dist to London(m): 555985.58456358
Name: Dublin Dist to London(m): 464000.328892816
Name: Miami Dist to London(m): 7123803.25406323
Name: Bermuda Dist to London(m): 5547607.95564083
Name: Puerto Rico Dist to London(m): 6799201.00905107
Name: Perth Dist to London(m): 14485217.5596414
Name: Sydney Dist to London(m): 17001034.4875494
Name: Tasmania Dist to London(m): 17324634.4559516 Filtrer la distance entre deux géopoints
Utilisez la condition de requête DISTANCE_SPHERE_WITHIN pour filtrer les enregistrements dont la valeur de géopoint est comprise dans le rayon d’un point de latitude et de longitude défini.
DISTANCE_SPHERE_WITHIN doit suivre la syntaxe geopointDISTANCE_SPHERE_WITHINlongitude,latitude<rayon où :
geopointest un champ de géopointLa longitude et lalatitudesont des constantes décimalesradiusest une constante décimale (en mètres)
Le DISTANCE_SPHERE_WITHIN accepte les valeurs de kilomètre ou de compteur dans la demande, mais renvoie toujours la valeur de sortie en mètres.
L’exemple de script suivant montre comment créer une requête codée qui renvoie uniquement les enregistrements dont la u_location est située à moins de 1 000 000 kilomètres du point -0,189937 de longitude, 51,473584 de latitude (qui correspond approximativement à l’emplacement de Londres). Lorsqu’elle est exécutée, elle renvoie trois enregistrements représentant des villes dans le rayon spécifié de Londres.
const myGeoPoint = new GlideRecord("u_geopoint");
myGeoPoint.addEncodedQuery("u_locationDISTANCE_SPHERE_WITHIN-0.189937,51.473584<1000000");
myGeoPoint.query();
while(gr.next())
gs.info("Name:" + myGeoPoint.getDisplayValue("u_name")
+ " Location:" + myGeoPoint.getDisplayValue("u_location"));Sortie :
Name:London Location:(-0.189937, 51.473584)
Name:Dublin Location:(-6.304994, 53.348317)
Name:Glasgow Location:(-4.223964, 55.867846)L’exemple de script suivant est équivalent au premier, mais utilise une syntaxe alternative pour GlideRecord.
const myGeoPoint = new GlideRecord("u_geopoint");
myGeoPoint.addQuery("u_location", "DISTANCE_SPHERE_WITHIN", "-0.189937,51.473584<1000000");
myGeoPoint.query();
while(myGeoPoint.next())
gs.info("Name:" + myGeoPoint.getDisplayValue("u_name")
+ " Location:" + myGeoPoint.getDisplayValue("u_location"));Sortie :
Name:London Location:(-0.189937, 51.473584)
Name:Dublin Location:(-6.304994, 53.348317)
Name:Glasgow Location:(-4.223964, 55.867846)