Guide du développeur GlideGeoPoint

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 6 minutes de lecture

    • Le guide du développeur GlideGeoPoint contient des informations sur le calcul des distances entre les valeurs de latitude et de longitude (géopoints), le renvoi des emplacements dans des valeurs de géopoint et de rayon données et l’utilisation des fonctionnalités supplémentaires fournies par les fonctions de l’API GlideGeoPoint prises en charge.

    Cela Geo point field type vous permet de stocker une paire de latitude et de longitude dans un seul champ. Les géopoints peuvent être utiles chaque fois que vous souhaitez stocker un point d’intérêt géographique, demander à quelle distance se trouvent deux points d’intérêt l’un de l’autre ou rechercher tous les points à une certaine distance d’un autre point. Par exemple, vous pouvez utiliser la fonctionnalité geopoint 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.

    Les principaux aspects du type de données GeoType sont les suivants :
    • Il se compose d’une paire de nombres décimaux représentant les valeurs de longitude et de latitude.
    • La plage de longitude est (-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 comme 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 geopoint, reportez-vous à la section Function field.

    Les exemples de ce guide supposent qu’une table personnalisée, u_geopoint, est remplie de 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 effectuer des fonctionnalités supplémentaires pour insérer de nouveaux enregistrements en définissant des géopoints directement dans un script à l’aide de la notation de chaîne ou d’un objet GlideGeoPoint.

    Insertion d’un nouvel enregistrement à l’aide de la notation de chaîne.
    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 table u_geopoint à l’aide de la notation de chaîne.
    Remarque :
    GlideGeoPoint Les valeurs API sont toujours répertoriées par longitude et par ordre 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 geopoint 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éopoint à l’aide de l’API GlideGeoPoint

    Utilisez la fonction d’API GlideGeoPoint getDisplayValue() pour lire toutes les valeurs de géopoint à partir d’une table spécifique.

    L’API GlideGeoPoint standard 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 une table entière. 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 propre cas d’utilisation.

    Remarque :
    GlideGeoPoint Les valeurs API sont toujours répertoriées par longitude et par ordre de latitude.
    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 de 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 :

    • Fonction Glide :distance_sphere(geopoint1, geopoint2)
    • Fonction de glissement :distance_sphere(géopoint1, longitude2, latitude2)
    • GlideFonction :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ériques 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 est à peu près 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 répertorie 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 ayant une valeur de géopoint dans le rayon d’un point de latitude et de longitude défini.

    DISTANCE_SPHERE_WITHIN doit suivre la syntaxe geopointDISTANCE_SPHERE_WITHINlongitude,latitude<radius où :

    • géopoint est un champ de géopoint
    • La longitude et lalatitude sont des constantes décimales
    • rayon est une constante décimale (en mètres)
    Remarque :
    Le symbole inférieur à (<) dans cette expression est requis et n’est utilisé que comme délimiteur. Tout autre opérateur de comparaison n’est pas valide.

    Le DISTANCE_SPHERE_WITHIN accepte les valeurs de kilomètres ou de mètres 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 se trouve à moins de 1 000 000 kilomètres du point - 0,189937 de longitude, 51,473584 de latitude (qui est à peu près l’emplacement de Londres). Lorsqu’il est exécuté, il renvoie trois enregistrements représentant les 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)