Oktatóanyag: Helyalapú leküldéses értesítések küldése a Notification Hubs és a Bing térbeli adataival

Cikk
06/01/2023

Ebben az oktatóanyagban elsajátíthatja, hogyan küldhet helyalapú leküldéses értesítéseket az Azure Notification Hubs és a Bing térbeli adatainak használatával.

Ebben az oktatóanyagban a következő lépéseket hajtja végre:

Az adatforrás beállítása
Az UWP-alkalmazás beállítása
A háttérrendszer beállítása
Leküldéses értesítések tesztelése Universal Windows Platform (UWP)-alkalmazásban

Előfeltételek

Azure-előfizetés. Ha nem rendelkezik Azure-előfizetéssel, a kezdés előtt hozzon létre egy ingyenes Azure-fiókot .
Visual Studio 2015 1. frissítés vagy újabb (Community Edition.
Az Azure SDK legújabb verziója.
Fiók a Bing Térképek fejlesztői központjához (ingyenesen létrehozható, és hozzárendelhető a Microsoft-fiókjához).

Az adatforrás beállítása

Jelentkezzen be a Bing Térképek fejlesztői központjába.
Kattintson a felső navigációs sáv Data Sources (Adatforrások) elemére, és válassza a Manage Data Sources (Adatforrások kezelése) lehetőséget.
Ha még nincs adatforrása, akkor látni fog egy hivatkozást, amellyel létrehozhat egyet. Válassza az Upload data as a data source (Adatok feltöltése adatforrásként) lehetőséget. Az Adatforrások>Feltöltése menüt is használhatja.

Hozzon létre egy fájlt NotificationHubsGeofence.pipe a merevlemezen a következő tartalommal: Ebben az oktatóanyagban egy csőalapú mintafájlt használ, amely a San Francisco vízpartjának egy részét keretezi:

Bing Spatial Data Services, 1.0, TestBoundaries
EntityID(Edm.String,primaryKey)|Name(Edm.String)|Longitude(Edm.Double)|Latitude(Edm.Double)|Boundary(Edm.Geography)
1|SanFranciscoPier|||POLYGON ((-122.389825 37.776598,-122.389438 37.773087,-122.381885 37.771849,-122.382186 37.777022,-122.389825 37.776598))

A folyamatfájl a következő entitást jelöli:

Képernyőkép a San Francisco-i vízpart térképéről egy piros sokszöggel, amely a mólók egy területét ábrázolja.

Az Upload data as a data source (Adat feltöltése adatforrásként) oldalon tegye a következőket:
1. Válassza ki a pipe (folyamat) elemet a Data format (Adatformátum) beállításnál.
2. Tallózással válassza ki az NotificationHubGeofence.pipe előző lépésben létrehozott fájlt.
3. Válassza az Upload (Feltöltés) gombot.
  
  Megjegyzés
  
  Lehetséges, hogy új, a Lekérdezési kulcstól eltérő Főkulcsot kell megadnia. Csak hozzon létre egy új kulcsot az irányítópulton, és frissítse az adatforrás-feltöltési oldalt.
Az adatfájl feltöltése után közzé kell tennie az adatforrást. Válassza az Adatforrások –>Adatforrások kezelése lehetőséget, mint korábban.
Keresse meg az adatforrást a listában, majd válassza ki a Publish (Közzététel) elemet az Actions (Műveletek) oszlopban.
Váltson a Published Data Sources (Közzétett adatforrások) lapra, és győződjön meg arról az adatforrás szerepel a listán.
Válassza a Szerkesztés elemet. (Egy pillantással) áttekintheti az adatokban létrehozott helyeket.

A portál ekkor még nem jeleníti meg a létrehozott geokerítés határvonalait. Ehhez csak meg kell erősítenie, hogy a megadott hely a megfelelő környéken található.
Most már az adatforrás minden követelménye teljesül. Az API-hívás kérési URL-jének részleteit úgy szerezheti be, ha a Bing Térképek fejlesztői központban kiválasztja a Data Sources (Adatforrások), majd a Data Source Information (Adatforrás adatai) elemet.

A Query URL az a végpont, ahol lekérdezéseket végezhet annak ellenőrzésére, hogy az eszköz egy adott hely határvonalain belül vagy kívül található-e. Ennek az ellenőrzésnek az elvégzéséhez egyszerűen egy GET hívást kell végrehajtania a lekérdezés URL-címén a következő paraméterek hozzáfűzésével:
```
?spatialFilter=intersects(%27POINT%20LONGITUDE%20LATITUDE)%27)&$format=json&key=QUERY_KEY
```
A Bing Térképek automatikusan elvégzi a számítást, így látható, hogy az eszköz a geokerítésen belül van-e. Ha böngésző (vagy a cURL) használatával hajtja végre a kérést, szabványos JSON-választ kap:

Ez a válasz csak akkor jelenik meg, ha a pont a kijelölt határokon belül található. Ha ez nem így van, a results (eredmények) gyűjtő üres lesz:

Az UWP-alkalmazás beállítása

A Visual Studióban indítson egy Üres alkalmazás (Univerzális Windows) típusú új projektet.

A projekt létrehozása után kihasználhatja az alkalmazás lehetőségeit. Most állítsunk be mindent a geokerítési infrastruktúrához. Ehhez a Bing szolgáltatásait fogja használni, és a következő nyilvános REST API-végpont használatával kérdezheti le az adott helyeket:
```
http://spatial.virtualearth.net/REST/v1/data/
```
A következő paramétereket kell megadnia a rendszer működéséhez:
- Adatforrás azonosítója és Adatforrás neve – a Bing Térképek API-adatforrásai számos összegyűjtött metaadatot tartalmaznak, például a helyadatokat és a nyitvatartási időt.
- Entitás neve – az értesítés hivatkozási pontjaként használni kívánt entitás.
- Bing Térképek API-kulcs – ezt a kulcsot már korábban megkapta, amikor létrehozta a fiókját a Bing fejlesztői központjában.
  
  Most, hogy az adatforrás rendelkezésre áll, elkezdhetünk dolgozni az UWP-alkalmazással.
Engedélyezze a helyszínszolgáltatásokat az alkalmazáshoz. Nyissa meg a Package.appxmanifest fájlt a Megoldáskezelőben.
A csomagtulajdonságokat tartalmazó megnyíló lapon válassza a Capabilities (Képességek) elemet, majd a Location (Hely) elemet.

Hozzon létre egy Core nevű új mappát a megoldásban, és adjon hozzá egy LocationHelper.cs nevű fájlt:

Képernyőkép a Megoldáskezelő az új Core-mappa kiemelésével.

A LocationHelper osztály kódja a felhasználó tartózkodási helyének lekérését biztosítja a rendszer API-n keresztül:

using System;
using System.Threading.Tasks;
using Windows.Devices.Geolocation;

namespace NotificationHubs.Geofence.Core
{
    public class LocationHelper
    {
        private static readonly uint AppDesiredAccuracyInMeters = 10;

        public async static Task<Geoposition> GetCurrentLocation()
        {
            var accessStatus = await Geolocator.RequestAccessAsync();
            switch (accessStatus)
            {
                case GeolocationAccessStatus.Allowed:
                    {
                        Geolocator geolocator = new Geolocator { DesiredAccuracyInMeters = AppDesiredAccuracyInMeters };

                        return await geolocator.GetGeopositionAsync();
                    }
                default:
                    {
                        return null;
                    }
            }
        }

    }
}

A felhasználó helyének UWP-alkalmazásokban való lekéréséről további információta Felhasználó helyének lekérése című témakörben talál.

Nyissa meg a főoldal (MainPage.xaml.cs) kódoldalát annak ellenőrzéséhez, hogy a helyadatok lekérése valóban működik-e. Hozzon létre egy új eseménykezelőt a Loaded eseményhez a MainPage konstruktorban.

public MainPage()
{
    this.InitializeComponent();
    this.Loaded += MainPage_Loaded;
}

Az eseménykezelő megvalósítása a következő:

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    var location = await LocationHelper.GetCurrentLocation();

    if (location != null)
    {
        Debug.WriteLine(string.Concat(location.Coordinate.Longitude,
            " ", location.Coordinate.Latitude));
    }
}

Futtassa az alkalmazást, majd engedélyezze a helyadatokhoz való hozzáférést.
Az alkalmazás elindítása után a koordináták a Kimenet ablakban láthatók:

Most már tudja, hogy a helyszerzés működik, eltávolíthatja a betöltött eseménykezelőt, ha szeretné, mert többé nem fogja használni.

A következő lépés a helyadatok módosításainak rögzítése. A LocationHelper osztályban adja hozzá a PositionChanged eseménykezelőjét:

geolocator.PositionChanged += Geolocator_PositionChanged;

A hely koordinátái az Output (Kimenet) ablakban jelennek meg:

private static async void Geolocator_PositionChanged(Geolocator sender, PositionChangedEventArgs args)
{
    await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        Debug.WriteLine(string.Concat(args.Position.Coordinate.Longitude, " ", args.Position.Coordinate.Latitude));
    });
}

A háttérrendszer beállítása

Töltse le a .NET-háttérrendszer mintáját a GitHubról.
A letöltés után nyissa meg a NotifyUsers mappát, majd a NotifyUsers.sln fájlt a Visual Studióban.
Állítsa be Indítási projektként, majd futtassa az AppBackend projektet.

A projekt már konfigurálva van leküldéses értesítések céleszközökre történő küldésére, így csak két dolgot kell megtennie: cserélje le az értesítési központ megfelelő kapcsolati sztringjét, illetve végezzen határvonal-azonosítást, hogy az üzenetet csak a geokerítésen belül tartózkodó felhasználók kapják meg.
A kapcsolati sztring konfigurálásához a Models mappában nyissa meg a következőt: Notifications.cs. A NotificationHubClient.CreateClientFromConnectionString függvénynek tartalmaznia kell az értesítési központ adatait, amelyet az Azure Portalon szerezhet be (nyissa meg a Beállítások menü Hozzáférési szabályzatok oldalát). Mentse a frissített konfigurációs fájlt.

Hozzon létre egy modellt a Bing Térképek API eredményéhez. Ennek legegyszerűbb módja, ha megnyitja a Models mappát, és azAdd Class (Osztályhozzáadása>) lehetőséget választja. Nevezze el a következőképpen: GeofenceBoundary.cs. Ezután másolja át a JSON-t az első szakaszban kapott API-válaszból. A Visual Studióban használja azEdit Paste SpecialPaste JSON as Classes (Speciális > beillesztés JSON beillesztése osztályként) lehetőséget>.

Így biztosítható, hogy az objektum deszerializálása pontosan a kívánt módon történjen. Az eredményül kapott osztály a következőhöz hasonló lesz:

namespace AppBackend.Models
{
    public class Rootobject
    {
        public D d { get; set; }
    }

    public class D
    {
        public string __copyright { get; set; }
        public Result[] results { get; set; }
    }

    public class Result
    {
        public __Metadata __metadata { get; set; }
        public string EntityID { get; set; }
        public string Name { get; set; }
        public float Longitude { get; set; }
        public float Latitude { get; set; }
        public string Boundary { get; set; }
        public string Confidence { get; set; }
        public string Locality { get; set; }
        public string AddressLine { get; set; }
        public string AdminDistrict { get; set; }
        public string CountryRegion { get; set; }
        public string PostalCode { get; set; }
    }

    public class __Metadata
    {
        public string uri { get; set; }
    }
}

Ezután nyissa meg a következőt: Controllers>NotificationsController.cs. Frissítse a Post hívást a kívánt hosszúsági és szélességi értékeknek megfelelően. Ehhez egyszerűen adja hozzá a függvényaláíráshoz a következő két sztringet: latitude és longitude.
```
public async Task<HttpResponseMessage> Post(string pns, [FromBody]string message, string to_tag, string latitude, string longitude)
```
Hozzon létre a projektben egy új, ApiHelper.cs nevű osztályt. Ezzel fog csatlakozni a Binghez, hogy ellenőrizze a pontok határvonalainak metszéspontjait. Adjon hozzá egy IsPointWithinBounds függvényt az alábbi kódban látható módon:
```
public class ApiHelper
{
    public static readonly string ApiEndpoint = "{YOUR_QUERY_ENDPOINT}?spatialFilter=intersects(%27POINT%20({0}%20{1})%27)&$format=json&key={2}";
    public static readonly string ApiKey = "{YOUR_API_KEY}";

    public static bool IsPointWithinBounds(string longitude,string latitude)
    {
        var json = new WebClient().DownloadString(string.Format(ApiEndpoint, longitude, latitude, ApiKey));
        var result = JsonConvert.DeserializeObject<Rootobject>(json);
        if (result.d.results != null && result.d.results.Count() > 0)
        {
            return true;
        }
        else
        {
            return false;
        }
    }
}
```
Fontos

Az API-végpontot cserélje le a Bing fejlesztői központjából korábban beszerzett lekérdezési URL-címre (ugyanez vonatkozik az API-kulcsra is).

Ha a lekérdezés eredményes volt, akkor az adott pont a geokerítés határain belül van, így a függvény a következőt adja vissza: true. Ha a lekérdezés eredménytelen, a Bing ezzel azt jelzi, hogy a pont a keresési területen kívül található, ezért a függvény false értéket ad vissza.

A NotificationsController.cs-hez visszatérve hozzon létre egy ellenőrzést közvetlenül a switch utasítás előtt:

if (ApiHelper.IsPointWithinBounds(longitude, latitude))
{
    switch (pns.ToLower())
    {
        case "wns":
            //// Windows 8.1 / Windows Phone 8.1
            var toast = @"<toast><visual><binding template=""ToastText01""><text id=""1"">" +
                        "From " + user + ": " + message + "</text></binding></visual></toast>";
            outcome = await Notifications.Instance.Hub.SendWindowsNativeNotificationAsync(toast, userTag);

            // Windows 10 specific Action Center support
            toast = @"<toast><visual><binding template=""ToastGeneric""><text id=""1"">" +
                        "From " + user + ": " + message + "</text></binding></visual></toast>";
            outcome = await Notifications.Instance.Hub.SendWindowsNativeNotificationAsync(toast, userTag);

            break;
    }
}

Leküldéses értesítések tesztelése az UWP-alkalmazásban

Az UWP-alkalmazásban most már tudjuk tesztelni az értesítéseket. A LocationHelper osztályba hozzon létre egy új függvényt – SendLocationToBackend:

public static async Task SendLocationToBackend(string pns, string userTag, string message, string latitude, string longitude)
{
    var POST_URL = "http://localhost:8741/api/notifications?pns=" +
        pns + "&to_tag=" + userTag + "&latitude=" + latitude + "&longitude=" + longitude;

    using (var httpClient = new HttpClient())
    {
        try
        {
            await httpClient.PostAsync(POST_URL, new StringContent("\"" + message + "\"",
                System.Text.Encoding.UTF8, "application/json"));
        }
        catch (Exception ex)
        {
            Debug.WriteLine(ex.Message);
        }
    }
}

Megjegyzés

Állítsa be a POST_URL elemet az üzembe helyezett webalkalmazás helyére. Egyelőre nem gond, ha helyileg futtatja, de amikor egy nyilvános verzió üzembe helyezésén dolgozik, külső szolgáltatónál kell üzemeltetnie.

Regisztrálja az UWP-alkalmazást a leküldéses értesítésekre. A Visual Studióban válassza a Project>Store>Alkalmazás társítása az áruházhoz lehetőséget.
Amikor bejelentkezik a fejlesztői fiókba, válasszon ki egy meglévő alkalmazást, vagy hozzon létre egy újat, és társítsa hozzá a csomagot.
Nyissa meg a fejlesztői központot, és nyissa meg a létrehozott alkalmazást. Válassza a Szolgáltatások>leküldéses értesítései>Live Services webhely lehetőséget.
A webhelyen jegyezze fel az Application Secret (Alkalmazástitok) és a Package SID (Csomag biztonsági azonosítója) értékeit. Mindkettőre szüksége van a Azure Portal – nyissa meg az értesítési központot, válassza a Beállítások>Notification Services>Windows (WNS) lehetőséget, és adja meg az adatokat a szükséges mezőkben.
Válassza a Mentés elemet.
Nyissa meg a References (Hivatkozások) elemet a Megoldáskezelőben, és válassza a Manage NuGet Packages (NuGet-csomagok kezelése) lehetőséget. Adjon hozzá egy, a Microsoft Azure Service Bus felügyelt kódtárára mutató hivatkozást. Ehhez csak keressen a WindowsAzure.Messaging.Managed elemre, és adja hozzá a projekthez.

Tesztelési célokra újra hozza létre újra a MainPage_Loaded eseménykezelőt, és adja hozzá a következő kódrészletet:

var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

var hub = new NotificationHub("HUB_NAME", "HUB_LISTEN_CONNECTION_STRING");
var result = await hub.RegisterNativeAsync(channel.Uri);

// Displays the registration ID so you know it was successful
if (result.RegistrationId != null)
{
    Debug.WriteLine("Reg successful.");
}

A kód regisztrálja az alkalmazást az értesítési központban. És már kész is van.

A LocationHelperGeolocator_PositionChanged kezelőjében hozzáadhat egy tesztkódszakaszt, amely a geokerítésen belülre kényszeríti a helyet:
```
await LocationHelper.SendLocationToBackend("wns", "TEST_USER", "TEST", "37.7746", "-122.3858");
```
Mivel nem a valós koordinátákat továbbítja (lehetséges, hogy ezek jelenleg nincsenek a határvonalakon belül), valamint előre meghatározott tesztértékeket használ, frissítéskor a következő értesítés jelenik meg:

Következő lépések

További lépésekre is szükség lehet, hogy a megoldás éles környezetben is használható legyen.

Mindenekelőtt a geokerítések dinamikus viselkedését kell biztosítania. Ehhez úgy kell beállítani a Bing API-t, hogy új határvonalakat tudjon feltölteni a meglévő adatforráson belül. Erről a Bing Spatial Data Services API-dokumentációjában talál további információt.
Ezután címkézéssel megadhat adott felhasználókat, így biztosíthatja, hogy a megfelelő személyek kapják meg az értesítéseket.

A jelen oktatóanyagban bemutatott megoldás egy olyan forgatókönyvet ismertet, amelyben sokféle célplatform lehetséges, ezért nem korlátozza rendszerspecifikus képességekkel a geokerítés-rendszert. A Univerzális Windows-platform ugyanakkor a geokerítések azonnali észlelésére szolgáló képességekkel rendelkezik.

Share via