Kurz: Přidání přizpůsobení do webové aplikace .NET

Přizpůsobení webové aplikace v jazyce C# .NET pomocí smyčky vlastního nastavení pro poskytnutí správného obsahu uživateli na základě akcí (s funkcemi) a funkcí kontextu.

V tomto kurzu se naučíte:

Výběr nejlepšího obsahu pro webovou aplikaci

Webová aplikace by měla používat přizpůsobený modul, pokud je na webové stránce seznam akcí (nějaký typ obsahu), které je potřeba přizpůsobit na jednu nejvyšší položku (rewardActionId), která se má zobrazit. Příklady seznamů akcí zahrnují články s příspěvky, umístění umístění tlačítek a možnosti Wordu pro názvy produktů.

Seznam akcí spolu s funkcemi kontextu můžete odeslat do smyčky přizpůsobené. Individuální nastavení vybere jednu nejlepší akci, kterou vaše webová aplikace zobrazí.

V tomto kurzu jsou akce typy jídla:

• těstovin
• zmrzlina
• vyrábí
• salát
• popcorn
• internetových
• neobsahuje

Chcete-li lépe přizpůsobovat informace o vašich akcích, odešlete obě akce s funkcemi a kontextovou funkcí s každou žádostí rozhraní API pro řazení.

Funkce modelu je informace o akci nebo kontextu, které mohou být agregovány (seskupeny) mezi členy vaší uživatelské základny webové aplikace. Funkce není individuálně specifická (například ID uživatele) nebo má vysokou specifickou hodnotu (například přesný denní čas).

Akce s funkcemi

Každá akce (položka obsahu) obsahuje funkce, které usnadňují rozlišení položky v potravinách.

Funkce nejsou nakonfigurované jako součást konfigurace smyčky v Azure Portal. Místo toho jsou odesílány jako objekt JSON s každým voláním rozhraní API řazení. To umožňuje flexibilitu při akcích a jejich funkcích v průběhu času zvětšovat, měnit a zmenšovat, což umožňuje přizpůsobovat sledování trendů.

 /// <summary>
  /// Creates personalizer actions feature list.
  /// </summary>
  /// <returns>List of actions for personalizer.</returns>
  private IList<RankableAction> GetActions()
  {
      IList<RankableAction> actions = new List<RankableAction>
      {
          new RankableAction
          {
              Id = "pasta",
              Features =
              new List<object>() { new { taste = "savory", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
          },

          new RankableAction
          {
              Id = "ice cream",
              Features =
              new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
          },

          new RankableAction
          {
              Id = "juice",
              Features =
              new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
          },

          new RankableAction
          {
              Id = "salad",
              Features =
              new List<object>() { new { taste = "sour", spiceLevel = "low" }, new { nutritionLevel = 8 } }
          },

          new RankableAction
          {
              Id = "popcorn",
              Features =
              new List<object>() { new { taste = "salty", spiceLevel = "none" }, new { nutritionLevel = 3 } }
          },

          new RankableAction
          {
              Id = "coffee",
              Features =
              new List<object>() { new { taste = "bitter", spiceLevel = "none" }, new { nutritionLevel = 3 }, new { drink = true } }
          },

          new RankableAction
          {
              Id = "soup",
              Features =
              new List<object>() { new { taste = "sour", spiceLevel = "high" }, new { nutritionLevel =  7} }
          }
      };

      return actions;
  }

Kontextové funkce

Kontextové funkce přizpůsobují usnadnění pro pochopení kontextu akcí. Kontext této ukázkové aplikace zahrnuje:

• čas od dne do ráno, odpoledne, večer, noc
• preference uživatele pro chuti – sůl, sladké, hořký, zdrojová nebo Savory
• kontext prohlížeče – uživatelský agent, zeměpisné umístění, odkazujícího uživatele

/// <summary>
/// Get users time of the day context.
/// </summary>
/// <returns>Time of day feature selected by the user.</returns>
private string GetUsersTimeOfDay()
{
    Random rnd = new Random();
    string[] timeOfDayFeatures = new string[] { "morning", "noon", "afternoon", "evening", "night", "midnight" };
    int timeIndex = rnd.Next(timeOfDayFeatures.Length);
    return timeOfDayFeatures[timeIndex];
}

/// <summary>
/// Gets user food preference.
/// </summary>
/// <returns>Food taste feature selected by the user.</returns>
private string GetUsersTastePreference()
{
    Random rnd = new Random();
    string[] tasteFeatures = new string[] { "salty", "bitter", "sour", "savory", "sweet" };
    int tasteIndex = rnd.Next(tasteFeatures.Length);
    return tasteFeatures[tasteIndex];
}

Jak Web App používá přizpůsobování?

Webová aplikace používá přidaný nástroj k výběru nejlepší akce ze seznamu možností potravinové služby. Odešle následující informace s každým voláním rozhraní API řazení:

• Akce s jejich funkcemi, jako jsou taste a spiceLevel
• kontextové funkce, jako jsou například uživatelské time taste Předvolby a informace o uživatelském agentovi prohlížeče a funkce kontextu
• akce, které se mají vyloučit , jako je například šťáva
• ID události, která se liší pro každé volání rozhraní API řazení.

Funkce modelu přizpůsobení ve webové aplikaci

Přizpůsobování vyžaduje funkce pro akce (obsah) a aktuální kontext (uživatel a prostředí). Funkce se používají k zarovnávání akcí s aktuálním kontextem v modelu. Tento model představuje informace o akcích, kontextu a jejich funkcích přizpůsobeného přizpůsobování, které umožňuje provádět kvalifikovaná rozhodnutí.

Model, včetně funkcí, se aktualizuje podle plánu na základě nastavení četnosti aktualizace modelu v Azure Portal.

Plánování funkcí a jejich hodnot

Funkce by se měly vybrat se stejným plánováním a návrhem, který byste použili pro jakékoli schéma nebo model v technické architektuře. Hodnoty funkcí je možné nastavit pomocí obchodní logiky nebo systémů třetích stran. Hodnoty funkcí by neměly být tak vysoce specifické, aby se neprojevily v rámci skupiny nebo třídy funkcí.

Generalizace hodnot funkcí

Generalizace do kategorií

Tato aplikace používá time jako funkci, ale seskupuje čas do kategorií, jako jsou morning ,, afternoon evening a night . To je příklad použití informací o čase, ale ne vysoce specifických způsobem, jako je 10:05:01 UTC+2 .

Generalizace do částí

Tato aplikace používá funkce požadavku HTTP z prohlížeče. Začíná velmi specifickým řetězcem, který má všechna data, například:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/530.99 (KHTML, like Gecko) Chrome/80.0.3900.140 Safari/537.36

Knihovna tříd HttpRequestFeatures generalizuje tento řetězec do objektu userAgentInfo s použitím individuálních hodnot. Všechny hodnoty, které jsou příliš specifické, jsou nastaveny na prázdný řetězec. Po odeslání funkcí kontextu pro požadavek má následující formát JSON:

{
  "httpRequestFeatures": {
    "_synthetic": false,
    "OUserAgent": {
      "_ua": "",
      "_DeviceBrand": "",
      "_DeviceFamily": "Other",
      "_DeviceIsSpider": false,
      "_DeviceModel": "",
      "_OSFamily": "Windows",
      "_OSMajor": "10",
      "DeviceType": "Desktop"
    }
  }
}

Použití ukázkové webové aplikace

Ukázková webová aplikace založená na prohlížeči (veškerý kód je k dispozici) vyžaduje, aby následující aplikace byly nainstalovány ke spuštění aplikace.

Nainstalujte následující software:

• .NET core 2,1 – ukázkový back-end Server používá .NET Core
• Node.js – klient/front-end závisí na této aplikaci.
• Visual Studio 2019nebo .NET Core CLI – pro sestavení a spuštění aplikace použijte vývojové prostředí Visual Studio 2019 nebo .NET Core CLI.

Nastavení ukázky

1. Naklonujte úložiště ukázek pro Azure pro přizpůsobení.

   git clone https://github.com/Azure-Samples/cognitive-services-personalizer-samples.git
   

2. Přejděte na Samples/HttpRequestFeatures a otevřete řešení HttpRequestFeaturesExample.sln .

   pokud je požadováno, umožněte Visual Studio aktualizovat balíček .net pro přizpůsobování.

Nastavení služby přizpůsobování Azure

1. Vytvořte prostředek přizpůsobeného v Azure Portal.

2. V Azure Portal vyhledejte na Endpoint Key1 Key2 kartě klíče a koncové body a buď nebo (jak budou fungovat). Jsou to vaše PersonalizerServiceEndpoint a vaše PersonalizerApiKey .

3. Vyplňte PersonalizerServiceEndpoint appsettings.js v části.

4. Nakonfigurujte PersonalizerApiKey jako tajné klíče aplikace jedním z následujících způsobů:

   • Pokud používáte .NET Core CLI, můžete použít dotnet user-secrets set "PersonalizerApiKey" "<API Key>" příkaz.
   • pokud používáte Visual Studio, můžete kliknout pravým tlačítkem na projekt a vybrat možnost správa tajných klíčů uživatelů a nakonfigurovat klíče přizpůsobeného uživatele. tím se Visual Studio otevře secrets.json soubor, ve kterém můžete klíče přidat následujícím způsobem:

   {
     "PersonalizerApiKey": "<your personalizer key here>",
   }
   

Spuštění ukázky

Sestavte a spusťte HttpRequestFeaturesExample pomocí jedné z následujících metod:

• Visual Studio 2019: stiskněte klávesu F5
• .NET Core CLI: dotnet build pak dotnet run

Přes webový prohlížeč můžete odeslat žádost o zařazení a žádost o odměnu, zobrazit jejich odpovědi a také funkce žádosti HTTP extrahované z vašeho prostředí.

Ukázka smyčky přizpůsobeného přizpůsobování

1. Kliknutím na tlačítko Generovat novou žádost o zařazení vytvořte nový objekt JSON pro volání rozhraní API řazení. Tím se vytvoří akce (s funkcemi) a kontextové funkce a zobrazí se hodnoty, abyste viděli, jak JSON vypadá.

   Pro vaši vlastní budoucí aplikaci může generování akcí a funkcí probíhat na klientovi, na serveru, v kombinaci obou nebo s voláními jiných služeb.

2. Vyberte Odeslat požadavek na řazení pro odeslání objektu JSON na server. Server volá rozhraní API pro řazení pro přizpůsobení. Server obdrží odpověď a vrátí nejvyšší seřazenou akci, kterou má klient zobrazit.

3. Nastavte hodnotu odměňování a pak vyberte tlačítko pro odeslání žádosti o Nemotivaci . Pokud hodnotu neměníte, klientská aplikace vždy pošle hodnotu do přizpůsobeného 1 .

   

   Pro vaši vlastní budoucí aplikaci může generování skóre odměňování nastat po shromáždění informací z chování uživatele v klientovi, spolu s obchodní logikou na serveru.

Pochopení ukázkové webové aplikace

Ukázková webová aplikace má server C# .NET , který spravuje shromažďování funkcí a posílání a přijímání volání http do koncového bodu přizpůsobeného rozhraní.

Ukázková webová aplikace používá front-endovou klientskou aplikaci knockout k zachycení funkcí a zpracování akcí uživatelského rozhraní, jako je kliknutí na tlačítka a odesílání dat na server .NET.

V následujících částech jsou vysvětlené části serveru a klienta, které vývojář musí pochopit, aby mohl používat personalizér.

Rozhraní API pro pořadí: Klientská aplikace odesílá kontext serveru

Klientská aplikace shromažďuje uživatelského agenta prohlížeče uživatele.

Rozhraní API pro hodnocení: Služba Personalizační volání serverové aplikace

Jedná se o typickou webovou aplikaci .NET s klientskou aplikací. Velká část kódu standardní desky je k dispozici pro vás. Jakýkoli kód, který není specifický pro personalizér, se odebere z následujících fragmentů kódu, abyste se mohli soustředit na kód specifický pro personalizér.

Vytvoření klienta Služby personalizátoru

V souboru Startup.cs serveru se k vytvoření klienta Personalizační služby používá koncový bod a klíč personalizátoru. Klientská aplikace nemusí v této aplikaci komunikovat s personalizérem a místo toho, aby při volání sady SDK spoléhá na server.

Počáteční kód .NET webového serveru je:

using Microsoft.Azure.CognitiveServices.Personalizer;
// ... other using statements removed for brevity

namespace HttpRequestFeaturesExample
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            string personalizerApiKey = Configuration.GetSection("PersonalizerApiKey").Value;
            string personalizerEndpoint = Configuration.GetSection("PersonalizerConfiguration:ServiceEndpoint").Value;
            if (string.IsNullOrEmpty(personalizerEndpoint) || string.IsNullOrEmpty(personalizerApiKey))
            {
                throw new ArgumentException("Missing Azure Personalizer endpoint and/or api key.");
            }
            services.AddSingleton(client =>
            {
                return new PersonalizerClient(new ApiKeyServiceClientCredentials(personalizerApiKey))
                {
                    Endpoint = personalizerEndpoint
                };
            });

            services.AddMvc();
        }

        // ... code removed for brevity
    }
}

Výběr nejlepší akce

V souboru PersonalizerController.cs serveru GenerateRank shrnuje rozhraní API serveru GenerateRank přípravu na volání rozhraní API pro pořadí.

• Vytvoření nové eventId pro volání Rank
• Získání seznamu akcí
• Získání seznamu funkcí od uživatele a vytvoření kontextových funkcí
• Volitelně můžete nastavit všechny vyloučené akce.
• Volání rozhraní API pořadí, vrácení výsledků klientovi

/// <summary>
/// Creates a RankRequest with user time of day, HTTP request features,
/// and taste as the context and several different foods as the actions
/// </summary>
/// <returns>RankRequest with user info</returns>
[HttpGet("GenerateRank")]
public RankRequest GenerateRank()
{
    string eventId = Guid.NewGuid().ToString();

    // Get the actions list to choose from personalizer with their features.
    IList<RankableAction> actions = GetActions();

    // Get context information from the user.
    HttpRequestFeatures httpRequestFeatures = GetHttpRequestFeaturesFromRequest(Request);
    string timeOfDayFeature = GetUsersTimeOfDay();
    string tasteFeature = GetUsersTastePreference();

    // Create current context from user specified data.
    IList<object> currentContext = new List<object>() {
            new { time = timeOfDayFeature },
            new { taste = tasteFeature },
            new { httpRequestFeatures }
    };

    // Exclude an action for personalizer ranking. This action will be held at its current position.
    IList<string> excludeActions = new List<string> { "juice" };

    // Rank the actions
    return new RankRequest(actions, currentContext, excludeActions, eventId);
}

Kód JSON odeslaný do služby Personalizér, který obsahuje jak akce (s funkcemi), tak aktuální kontextové funkce, vypadá jako:

{
    "contextFeatures": [
        {
            "time": "morning"
        },
        {
            "taste": "savory"
        },
        {
            "httpRequestFeatures": {
                "_synthetic": false,
                "MRefer": {
                    "referer": "http://localhost:51840/"
                },
                "OUserAgent": {
                    "_ua": "",
                    "_DeviceBrand": "",
                    "_DeviceFamily": "Other",
                    "_DeviceIsSpider": false,
                    "_DeviceModel": "",
                    "_OSFamily": "Windows",
                    "_OSMajor": "10",
                    "DeviceType": "Desktop"
                }
            }
        }
    ],
    "actions": [
        {
            "id": "pasta",
            "features": [
                {
                    "taste": "savory",
                    "spiceLevel": "medium"
                },
                {
                    "nutritionLevel": 5,
                    "cuisine": "italian"
                }
            ]
        },
        {
            "id": "ice cream",
            "features": [
                {
                    "taste": "sweet",
                    "spiceLevel": "none"
                },
                {
                    "nutritionalLevel": 2
                }
            ]
        },
        {
            "id": "juice",
            "features": [
                {
                    "taste": "sweet",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 5
                },
                {
                    "drink": true
                }
            ]
        },
        {
            "id": "salad",
            "features": [
                {
                    "taste": "sour",
                    "spiceLevel": "low"
                },
                {
                    "nutritionLevel": 8
                }
            ]
        },
        {
            "id": "popcorn",
            "features": [
                {
                    "taste": "salty",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                }
            ]
        },
        {
            "id": "coffee",
            "features": [
                {
                    "taste": "bitter",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                },
                {
                    "drink": true
                }
            ]
        },
        {
            "id": "soup",
            "features": [
                {
                    "taste": "sour",
                    "spiceLevel": "high"
                },
                {
                    "nutritionLevel": 7
                }
            ]
        }
    ],
    "excludedActions": [
        "juice"
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "deferActivation": null
}

Vrácení Personaliz rewardActionId klientovi

Rozhraní API rank na server vrátí vybranou nejlepší akci rewardActionId.

Zobrazí se akce vrácená v rewardActionId.

{
    "ranking": [
        {
            "id": "popcorn",
            "probability": 0.833333254
        },
        {
            "id": "salad",
            "probability": 0.03333333
        },
        {
            "id": "juice",
            "probability": 0
        },
        {
            "id": "soup",
            "probability": 0.03333333
        },
        {
            "id": "coffee",
            "probability": 0.03333333
        },
        {
            "id": "pasta",
            "probability": 0.03333333
        },
        {
            "id": "ice cream",
            "probability": 0.03333333
        }
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "rewardActionId": "popcorn"
}

Klient zobrazí akci rewardActionId.

V tomto kurzu se rewardActionId zobrazí hodnota .

Ve vlastní budoucí aplikaci to může být přesný text, tlačítko nebo zvýrazněná část webové stránky. Seznam se vrátí pro jakoukoli post-analýzu skóre, nikoli řazení obsahu. Měl by rewardActionId se zobrazit pouze obsah.

Rozhraní REWARD API: Shromažďování informací o odměně

Skóre odměny by se mělo pečlivě naplánovat, stejně jako se plánují funkce. Skóre odměny by obvykle mělo být hodnota od 0 do 1. Hodnotu lze vypočítat částečně v klientské aplikaci na základě chování uživatelů a částečně na serveru na základě obchodní logiky a cílů.

Pokud server nevolá rozhraní Reward API v rámci doby čekání Reward nakonfigurované v Azure Portal pro váš prostředek Personalizéru, použije se pro Azure Portal událost výchozí odměna (nakonfigurovaná také v Azure Portal).

V této ukázkové aplikaci můžete vybrat hodnotu a podívat se, jak má odměna vliv na výběry.

Další způsoby výuky z této ukázky

Ukázka používá několik událostí založených na čase nakonfigurovaných v Azure Portal pro váš prostředek služby Personalizér. Pohrajte si s těmito hodnotami a pak se vraťte do této ukázkové webové aplikace, abyste viděli, jak změny mají vliv na volání Rank a Reward:

• Doba čekání na odměnu
• Frekvence aktualizace modelu

Mezi další nastavení, se která si můžete přehrát, patří:

• Výchozí odměna
• Procento průzkumu

Vyčištění prostředků

Až budete s tímto kurzem hotovi, vyčistěte následující prostředky:

• Odstraňte adresář ukázkového projektu.
• Odstraňte prostředek služby Personalizér – prostředek služby Personalizér si představte jako vyhrazený pro akce a kontext – tento prostředek znovu použijte, pouze pokud stále používáte jídlo jako doménu předmětu akcí.

Další kroky

• Jak služba Personalizace funguje
• Funkce:Seznamte se s koncepty funkcí s využitím akcí a kontextu.
• Rewards:informace o výpočtu odměn