Kurz: Odesílání nabízených oznámení založených na poloze pomocí Notification Hubs a Bing Spatial Data

Článek
10/16/2024

V tomto kurzu se dozvíte, jak pomocí Azure Notification Hubs a Bing Spatial Data doručovat nabízená oznámení na základě polohy.

V tomto kurzu provedete následující kroky:

Nastavení zdroje dat
Nastavení aplikace pro UPW
Nastavení back-endu
Test nabízených oznámení v aplikaci pro Univerzální platformu Windows (UPW)

Požadavky

Předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet Azure před tím, než začnete.
Visual Studio 2015 Update 1 nebo novější (Community Edition)
Nejnovější verze Azure SDK
Účet na webu Dev Center pro Mapy Bing (Je možné si jej vytvořit zdarma a přidružit si ho k účtu Microsoft.)

Nastavení zdroje dat

Přihlaste se k webu Dev Center pro Mapy Bing.
V horním navigačním panelu vyberte Zdroje dat a vyberte Spravovat zdroje dat.
Pokud nemáte žádný zdroj dat, zobrazí se odkaz na jeho vytvoření. Vyberte Nahrát data jako zdroj dat. Můžete použít také nabídku Zdroje dat>Nahrát data.

Na pevném disku vytvořte soubor NotificationHubsGeofence.pipe s následujícím obsahem: V tomto kurzu použijete ukázkový soubor založený na kanálech, který rámuje oblast pobřeží San Francisco:

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))

Soubor kanálu představuje tuto entitu:

Snímek obrazovky s mapou břehu San Francisca s červenou mnohoúhelníkovou osnovou oblasti molů

Na stránce Nahrát zdroj dat proveďte následující akce:
1. Jako Formát dat vyberte kanál.
2. Vyhledejte a vyberte NotificationHubGeofence.pipe soubor, který jste vytvořili v předchozím kroku.
3. Vyberte tlačítko Nahrát.
  
  Poznámka:
  
  Může se zobrazit výzva k zadání nového klíče jako hlavního klíče, který se bude lišit od klíče dotazu. Nový klíč jednoduše vytvořte přes řídicí panel a aktualizujte stránku pro nahrání zdroje dat.
Jakmile nahrajete datový soubor, bude nezbytné publikovat zdroj dat. Vyberte Zdroje dat –> Spravovat zdroje dat, jako jste to udělali dříve.
V seznamu vyberte váš zdroj dat a ve sloupci Akce zvolte Publikovat.
Přepněte na kartu Publikované zdroje dat a zkontrolujte, že se v seznamu zobrazí váš zdroj dat.
Vyberte položku Upravit. Uvidíte (na první pohled), jaká umístění jsou součástí dat.

V tuto chvíli portál nezobrazuje hranice monitorované geografické zóny, kterou jste vytvořili – stačí vám pouze potvrzení, že zadaná lokalita je ve správném okolí.
Nyní máte všechny požadavky na zdroj dat. Pokud chcete získat podrobnosti o adrese URL žádosti pro volání rozhraní API, na webu Dev Center pro Mapy Bing zvolte Zdroje dat a vyberte Informace o zdroji dat.

Adresa URL dotazu je koncový bod, proti kterému můžete spouštět dotazy, abyste zjistili, jestli se zařízení aktuálně nachází uvnitř lokality nebo ne. K provedení této kontroly stačí na adresu URL dotazu provést volání GET s připojenými následujícími parametry:
```
?spatialFilter=intersects(%27POINT%20LONGITUDE%20LATITUDE)%27)&$format=json&key=QUERY_KEY
```
Služba Mapy Bing automaticky provádí výpočty a kontroluje, jestli se zařízení nachází uvnitř monitorované geografické zóny. Jakmile přes prohlížeč (nebo nástroj cURL) provedete požadavek, obdržíte standardní odpověď JSON:

Tato odpověď se odesílá jen v případě, že se bod nachází v určené oblasti. Pokud se tam nenachází, obdržíte prázdný kontejner výsledku:

Nastavení aplikace pro UPW

V nástroji Visual Studio vytvořte nový projekt typu Prázdná aplikace (univerzální pro Windows).

Jakmile se vytváření projektu dokončí, měli byste mít základ samotné aplikace. Teď nastavíme vše pro infrastrukturu geografického ohraničení. Vzhledem k tomu, že pro toto řešení využijete služby Bing, je k dispozici veřejný koncový bod rozhraní REST API, který umožňuje dotazovat se na konkrétní oblasti lokality:
```
http://spatial.virtualearth.net/REST/v1/data/
```
Zprovozníte ho zadáním následujících parametrů:
- ID zdroje dat a Název zdroje dat – v rozhraní API Map Bing zdroje dat obsahují různá kategorizovaná metadata, například lokality a pracovní doby provozu.
- Název entity – entita, kterou chcete použít jako referenční bod pro oznámení.
- Klíč rozhraní API Map Bing – klíč, který jste dříve získali při vytváření účtu Dev Center pro Bing.
  
  Když teď máte připravený zdroj dat, můžete začít pracovat na aplikaci pro UPW.
Povolte pro vaši aplikaci zjišťování polohy. V Průzkumníku řešení otevřete soubor Package.appxmanifest.
Na kartě vlastností balíčku, která se právě otevřela, přepněte na kartu Schopnosti a vyberte Poloha.

Vytvořte v řešení novou složku Core a přidejte do ní nový soubor LocationHelper.cs:

Snímek obrazovky Průzkumník řešení se zvýrazněnou novou složkou Core

Třída LocationHelper obsahuje kód pro získání polohy uživatele prostřednictvím systémového rozhraní API:

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;
                    }
            }
        }

    }
}

Další informace o získání polohy uživatele v aplikacích pro UPW najdete v tématu Získání polohy uživatele.

Pokud chcete zkontrolovat, že získávání polohy skutečně funguje, otevřete kód hlavní stránky (MainPage.xaml.cs). Vytvořte novou obslužnou rutinu události pro událost Loaded v konstruktoru MainPage.

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

Implementace obslužné rutiny události bude následující:

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));
    }
}

Spusťte aplikaci a povolte jí přístup k informacím o vaší poloze.
Jakmile se aplikace spustí, měli byste v okně Výstup vidět souřadnice:

Teď víte, že získávání polohy funguje, můžete obslužnou rutinu načtené události odebrat, pokud chcete, protože ji už nebudete používat.

Dalším krokem je zachycení změň v poloze. Do třídy LocationHelper přidejte obslužnou rutinu události pro PositionChanged:

geolocator.PositionChanged += Geolocator_PositionChanged;

Implementace zobrazuje souřadnice polohy v okně Výstup:

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));
    });
}

Nastavení back-endu

Stáhněte si ukázku back-endu .NET z GitHubu.
Až se stahování dokončí, otevřete složku NotifyUsers a pak v sadě Visual otevřete soubor NotifyUsers.sln.
Nastavte projekt AppBackend jako Spouštěný projekt a spusťte jej.

Projekt je již nakonfigurovaný tak, aby do cílových zařízení odesílal nabízená oznámení, proto bude potřeba udělat jen dvě věci – zadat správný připojovací řetězec centra oznámení a přidat identifikaci hranice, aby se oznámení odesílalo jenom v případě, že se uživatel nachází uvnitř monitorové geografické zóny.
Pro konfiguraci připojovacího řetězce otevřete ve složce Models soubor Notifications.cs. Funkce NotificationHubClient.CreateClientFromConnectionString by měla obsahovat informace o centru oznámení, které můžete získat na webu Azure Portal (podívejte se na stránku Zásady přístupu v Nastavení). Uložte aktualizovaný konfigurační soubor.

Vytvořte model pro výsledek rozhraní API Map Bing. Nejjednodušší způsob, jak toho docílit, je otevřít složku Models a zvolit Přidat>Třída. Pojmenujte ho GeofenceBoundary.cs. Pak zkopírujte JSON z odpovědi rozhraní API, kterou jste obdrželi v první části. V sadě Visual Studio použijte možnost Upravit>Vložit jinak>Vložit formát JSON jako třídy.

Tímto způsobem zajistíte, že se objekt deserializuje přesně podle očekávání. Výsledná sada tříd by měla vypadat přibližně jako následující třída:

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; }
    }
}

Dále otevřete Controllers>NotificationsController.cs. Upravte volání Post tak, aby používalo cílovou zeměpisnou délku a šířku. Provedete to tak, že do signatury funkce přidáte dva řetězce – latitude a longitude.
```
public async Task<HttpResponseMessage> Post(string pns, [FromBody]string message, string to_tag, string latitude, string longitude)
```

Vytvořte v projektu novou třídu ApiHelper.cs. Použijete ji k připojení k Bingu pro kontrolu průsečíků hranic. Implementujte funkci IsPointWithinBounds, jak je znázorněno v následujícím kódu:

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;
        }
    }
}

Důležité

Je nezbytné nahradit koncový bod rozhraní API adresou URL dotazu, kterou jste získali dříve z webu Dev Center pro Bing (totéž platí pro klíč rozhraní API).

Pokud dotaz vrací výsledky, znamená to, že se zadaný bod nachází uvnitř monitorované geografické zóny, proto funkce vrací true. Pokud žádné výsledky nejsou, Bing vám oznamuje, že se bod nachází mimo rámec vyhledávání, proto funkce vrací false.

V souboru NotificationsController.cs vytvořte kontrolu přímo před příkazem switch:

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;
    }
}

Test nabízených oznámení v aplikaci pro UPW

V aplikaci pro UPW byste nyní měli být schopni oznámení otestovat. Ve třídě LocationHelper vytvořte novou funkci – 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);
        }
    }
}

Poznámka:

Nastavte POST_URL na umístění vaší nasazené webové aplikace. Prozatím je v pořádku ji spustit místně, ale když pracujete na nasazení veřejné verze, musíte ji hostovat s externím poskytovatelem.

Zaregistrujte aplikaci pro UPW k nabízeným oznámením. V sadě Visual Studio zvolte Projekt>Store>Přidružit aplikaci ve Store.
Jakmile se přihlásíte ke svému účtu vývojáře, ujistěte se, že jste vybrali existující aplikaci, nebo vyberte novou a přidružte k ní balíček.
Přejděte na Dev Center a otevřete aplikaci, kterou jste vytvořili. Zvolte Služby>Nabízená oznámení>Web služeb Live Services.
Na webu si poznamenejte Tajný klíč aplikace a SID balíčku. Obojí budete potřebovat na webu Azure Portal – otevřete své centrum oznámení, zvolte Nastavení>Notification Services>Windows (WNS) a do požadovaných polí zadejte příslušné informace.
Vyberte Uložit.
V Průzkumníku řešení otevřete Odkazy a vyberte Spravovat balíčky NuGet. Přidejte odkaz na spravovanou knihovnu Microsoft Azure Service Bus – jednoduše vyhledejte balíček WindowsAzure.Messaging.Managed a přidejte ho do projektu.

Pro účely testování znovu vytvořte obslužnou rutinu události MainPage_Loaded a přidejte do ní tento fragment kódu:

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.");
}

Kód zaregistruje aplikaci do centra oznámení. Jste připraveni!

V LocationHelper uvnitř obslužné rutiny Geolocator_PositionChanged můžete přidat testovací kód, který bod nuceně umístí do monitorové geografické zóny:
```
await LocationHelper.SendLocationToBackend("wns", "TEST_USER", "TEST", "37.7746", "-122.3858");
```
Jelikož nepředáváte skutečné souřadnice (které by v tuto chvíli nemusely odpovídat místu uvnitř oblasti) a používáte předdefinované testovací hodnoty, uvidíte, že se při aktualizaci zobrazí oznámení:

Další kroky

Pokud chcete řešení připravit na reálný provoz, může být zapotřebí podniknout několik kroků.

Nejprve je potřeba zajistit, že monitorované geografické zóny jsou dynamické. To vyžaduje další práci s rozhraním API služby Bing, aby bylo možné nahrávat nové hranice do existujícího zdroje dat. Další informace najdete v dokumentaci rozhraní API pro Bing Spatial Data Services.
Abyste zajistili doručování správným účastníkům, můžete požadovat cílení pomocí tagování.

Řešení uvedené v tomto kurzu popisuje scénář, při kterém můžete mít širokou škálu cílových platforem, proto se monitorování geografické zóny neomezuje schopnostmi specifickými pro daný systém. Je ale nutné dodat, že Univerzální platforma Windows nabízí integrované možnosti pro detekci monitorované geografické zóny.

Sdílet prostřednictvím