Öğretici: bir .NET Web uygulamasına kişiselleştirici ekleme

Eylemler (özelliklerle birlikte) ve bağlam özellikleriyle bir kullanıcıya doğru içerik sağlamak için bir kişiselleştirme döngüsüyle bir C# .NET Web uygulamasını özelleştirin.

Bu öğreticide şunların nasıl yapıldığını öğreneceksiniz:

Bir Web uygulaması için en iyi içeriği seçin

Web sayfasında, görüntülenecek tek bir üst öğeye (Rewarterctionıd) kişiselleştirilmesi gereken eylemlerin (bazı içerik türleri) bir listesi olduğunda, kişiselleştirici kullanılmalıdır. Eylem listesi örnekleri arasında haber makaleleri, düğme yerleştirme konumları ve ürün adları için Word seçenekleri bulunur.

Eylem listesini, bağlam özellikleriyle birlikte, kişiselleştirici döngüsüne gönderirsiniz. Kişiselleştirici tek en iyi eylemi seçerse, Web uygulamanız bu eylemi görüntüler.

Bu öğreticide, eylemler yiyecek türleridir:

• pasta
• dondurma
• Juice
• Salad
• popcorn
• ünüzü
• çorba

Kişiselleştiriciye, eylemleriniz hakkında bilgi edinin ve her bir derecelendirme API isteği ile özellik ve bağlam özellikleriyle eylemleri gönderin.

Modelin bir özelliği , Web uygulaması Kullanıcı tabanınızın üyeleri genelinde toplanabilecek eylem veya içerikle ilgili bilgiler. Bir özellik ayrı ayrı (Kullanıcı KIMLIĞI gibi) veya yüksek oranda özel (günün tam saati gibi) değildir .

Özelliklerle ilgili eylemler

Her eylem (içerik öğesi), yiyecek öğesini ayırt etmenize yardımcı olan özelliklere sahiptir.

Özellikler, Azure portal döngü yapılandırmasının bir parçası olarak yapılandırılmamıştır. Bunun yerine, her derecelendirme API çağrısıyla bir JSON nesnesi olarak gönderilirler. Bu, eylemlerin ve özelliklerinin zaman içinde büyümesini, değiştirilmesini ve daralmasına olanak tanır. bu sayede, Kişiselleştiriciye eğilimleri takip edebilirsiniz.

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

Bağlam özellikleri

Bağlam özellikleri, kişiselleştirici eylemlerin bağlamını anlamalarına yardımcı olur. Bu örnek uygulamanın bağlamı şunları içerir:

• Günün saati-sabah, öğleden sonra akşam, gece
• Kullanıcı, tatlı, SWE, Bitter, Sour veya savun tercihi
• tarayıcının bağlamı-Kullanıcı Aracısı, coğrafi konum, başvuran

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

Web uygulaması kişiselleştirici nasıl kullanır?

Web uygulaması, yemek seçimleri listesinden en iyi eylemi seçmek için kişiselleştirici kullanır. Bu, her bir derecelendirme API çağrısıyla aşağıdaki bilgileri göndererek bunu yapar:

• ve gibi özelliklerine sahip Eylemler taste``spiceLevel
• time gün, kullanıcının taste tercihi ve tarayıcının Kullanıcı Aracısı bilgileri ve bağlam özellikleri gibi bağlam özellikleri
• Bu gibi tutulacak eylemler
• Her derecelendirme API çağrısı için farklı olan EventID.

Web uygulamasındaki kişiselleştirici model özellikleri

Kişiselleştirici, eylemler (içerik) ve geçerli bağlam (Kullanıcı ve ortam) için özelliklere ihtiyaç duyuyor. Özellikler, işlemleri modeldeki geçerli içeriğe hizalamak için kullanılır. Model, kişisel kararlar alma kararı veren eylemler, bağlam ve özellikleri hakkında Kişiselleştiriciye ait geçmiş bilgisinin bir gösterimidir.

Özellikler dahil olmak üzere model, Azure portal model güncelleştirme sıklığı ayarı temelinde bir zamanlamaya göre güncelleştirilir.

Özellikleri ve değerlerini planlayın

Özellikler, teknik mimarinizdeki herhangi bir şema veya modele uygulayabileceğiniz planlama ve tasarıma sahip olacak şekilde seçilmelidir. Özellik değerleri, iş mantığı veya üçüncü taraf sistemlerle ayarlanabilir. Özellik değerleri, bir grup veya özellik sınıfında uygulanmadığından yüksek oranda özel olmamalıdır.

Genelleştirme özellik değerleri

Kategorilere Genelleştirme

Bu uygulama time bir özellik olarak kullanır, ancak saat,, ve gibi kategoriler halinde gruplar morning afternoon evening night . Bu, zaman bilgilerinin kullanılmasına bir örnektir, ancak gibi yüksek ölçüde belirli bir şekilde değil 10:05:01 UTC+2 .

Parçalar halinde Genelleştirme

Bu uygulama, tarayıcıdan gelen HTTP Isteği özelliklerini kullanır. Bu, tüm verileri içeren çok özel bir dizeyle başlar, örneğin:

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

Httprequestfeatures sınıf kitaplığı, bu dizeyi ayrı değerlerle bir useragentınfo nesnesine genelleştirir. Çok özgü olan tüm değerler boş bir dizeye ayarlanır. İstek için içerik özellikleri gönderildiğinde, aşağıdaki JSON biçimine sahiptir:

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

Örnek Web uygulaması kullanma

Örnek tarayıcı tabanlı Web uygulaması (tüm kod sağlanır) uygulamayı çalıştırmak için aşağıdaki uygulamaların yüklü olması gerekir.

Aşağıdaki yazılımları yükleyin:

• .Net core 2,1 -örnek arka uç sunucusu .NET Core kullanır
• Node.js -istemci/ön uç bu uygulamaya bağlıdır
• Visual Studio 2019veya .NET Core CLI -uygulamayı derlemek ve çalıştırmak için Visual Studio 2019 ya da .NET Core CLI geliştirici ortamını kullanın

Örneği ayarlama

1. Azure kişiselleştirici örnek deposu ' nu kopyalayın.

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

2. Çözümü açmak için Samples/HttpRequestFeatures öğesine gidin HttpRequestFeaturesExample.sln .

   isteniyorsa Visual Studio, kişiselleştirici için .net paketini güncelleştirmesine izin verin.

Azure kişiselleştirici hizmetini ayarlama

1. Azure portal bir kişiselleştirici kaynağı oluşturun .

2. Azure portal, Endpoint Key1 Key2 anahtarlar ve uç noktalar sekmesinde ve ya da (çalışır) öğesini bulun. Bunlar PersonalizerServiceEndpoint ve sizin PersonalizerApiKey .

3. PersonalizerServiceEndpoint Üzerindeappsettings.js' ın üzerine girin.

4. PersonalizerApiKeyAşağıdaki yollarla bir uygulama gizli dizileri olarak yapılandırın:

   • .NET Core CLI kullanıyorsanız dotnet user-secrets set "PersonalizerApiKey" "<API Key>" komutunu kullanabilirsiniz.
   • Visual Studio kullanıyorsanız, projeyi sağ tıklayıp kullanıcı gizli dizilerini yönet menü seçeneğini seçerek kişiselleştirici anahtarlarını yapılandırabilirsiniz. bunu yaptığınızda, Visual Studio secrets.json anahtarları aşağıdaki gibi ekleyebileceğiniz bir dosya açılır:

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

Örneği çalıştırma

Aşağıdaki yöntemlerden biriyle Httprequestfeaturesexörnek oluşturun ve çalıştırın:

• Visual Studio 2019: F5 tuşuna basın
• .NET Core CLI: dotnet build``dotnet run

Bir Web tarayıcısı aracılığıyla, bir derecelendirme isteği ve bir istek isteği gönderebilir ve bu isteklerin yanı sıra ortamınızdan ayıklanan http istek özelliklerini görebilirsiniz.

Kişiselleştirici döngüsünü gösterir

1. Derece API çağrısı için yeni bir JSON nesnesi oluşturmak üzere Yeni bir derecelendirme Isteği oluştur düğmesini seçin. Bu işlem eylemleri (özelliklerle birlikte) ve bağlam özelliklerini oluşturur ve bu sayede JSON 'ın nasıl göründüğünü görebilmeniz için değerleri görüntüler.

   Kendi kendinize ait uygulamanız için, istemci, sunucuda, iki karışımı veya diğer hizmetlere yapılan çağrılarla birlikte eylemler ve özellikler oluşturma işlemi meydana gelebilir.

2. JSON nesnesini sunucuya göndermek için Derecelendirme Isteği gönder ' i seçin. Sunucu, kişiselleştirici derecelendirme API 'sini çağırır. Sunucu yanıtı alır ve istemciye görüntülenecek üst dereceli eylemi döndürür.

3. Ödül değerini ayarlayın ve ardından yeniden istek gönder düğmesini seçin. Yeniden değer değerini değiştirmezseniz, istemci uygulaması her zaman değerini 1 Kişiselleştiriciye gönderir.

   

   Gelecekteki uygulamanız için, kullanıcının istemci davranışından, sunucuda iş mantığı ile ilgili bilgiler toplandıktan sonra yeniden Puanlama oluşturma işlemi meydana gelebilir.

Örnek Web uygulamasını anlama

Örnek Web uygulaması, özelliklerin toplanmasını ve kişiselleştirici uç noktanıza HTTP çağrıları göndermeyi ve almayı yöneten bir C# .net sunucusuna sahiptir.

Örnek web uygulaması, düğmelere tıklama ve .NET sunucusuna veri gönderme gibi özellikleri yakalamak ve kullanıcı arabirimi eylemlerini işlemek için bir giriş ön uç istemci uygulaması kullanır.

Aşağıdaki bölümlerde, bir geliştiricinin Kişiselleştirme'i kullanmak için anlaması gereken sunucu ve istemci bölümleri açıklanmaktadır.

Sıralama API'si: İstemci uygulaması sunucuya bağlam gönderir

İstemci uygulaması, kullanıcının tarayıcı kullanıcı aracısını toplar.

Sıralama API'si: Sunucu uygulaması Kişiselleştirme'yi çağırıyor

Bu, istemci uygulamasına sahip tipik bir .NET web uygulamasıdır. Bunun için ortak kod kodunun büyük bölümü sağlanır. Kişiselleştirme'ye özgü olmayan tüm kodlar aşağıdaki kod parçacıklarından kaldırılır, bu nedenle Kişiselleştirme'ye özgü koda odaklanabilirsiniz.

Kişiselleştirme istemcisi oluşturma

Sunucunun Startup.cs içinde Kişiselleştirme istemcisini oluşturmak için Kişiselleştirme uç noktası ve anahtarı kullanılır. İstemci uygulamasının bu uygulamada Kişiselleştirme ile iletişim kurması değil, bu SDK çağrılarını yapmak için sunucuya güvenmesi gerekir.

Web sunucusunun .NET başlangıç kodu şöyledir:

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

En iyi eylemi seçme

Sunucunun KişiselleştirmeController.cs'sinde GenerateRank sunucu API'si Sıralama API'sini çağırma hazırlığı özetler

• Derece çağrısı eventId için yeni oluştur
• Eylemlerin listesini al
• Kullanıcıdan özelliklerin listesini almak ve bağlam özellikleri oluşturmak
• İsteğe bağlı olarak, hariç tutulacak eylemleri ayarlayın
• Sıralama API'sini çağırma, sonuçları istemciye geri çağırma

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

Kişiselleştirme'ye gönderilen ve hem eylemleri (özelliklerle birlikte) hem de geçerli bağlam özelliklerini içeren JSON şu şekildedir:

{
    "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
}

İstemciye Kişiselleştirme ödülüActionId iade

Sıralama API'si seçilen en iyi eylem olan rewardActionId'yi sunucuya döndürür.

rewardActionId içinde döndürülen eylemi görüntüler.

{
    "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"
}

İstemci rewardActionId eylemlerini görüntüler

Bu öğreticide rewardActionId değer görüntülenir.

Kendi gelecekteki uygulamanıza tam metin, düğme veya web sayfasının bir bölümü vurgulanmış olabilir. Liste, içeriğin sıralaması için değil puan analizi sonrası için döndürülür. Yalnızca rewardActionId içerik görüntüleniyor.

Ödül API'si: Ödül için bilgi toplama

Özelliklerin planlandığı gibi ödül puanı da dikkatli bir şekilde planlanmaktadır. Ödül puanı genellikle 0 ile 1 arasında bir değerdir. Değer, istemci uygulamasında kullanıcı davranışlarına ve kısmen de iş mantığına ve hedeflerine göre sunucu üzerinde kısmen hesaplanabilir.

Sunucu, Kişiselleştirme kaynağınız için Azure portal'de yapılandırılan Ödül bekleme süresi içinde Ödül API'sini çağırmazsanız, bu etkinlik için Varsayılan ödül (Azure portal'de yapılandırılır) kullanılır.

Bu örnek uygulamada, ödülün seçimleri nasıl etkileyeni görmek için bir değer seçebilirsiniz.

Bu örnekten öğrenmenin ek yolları

Örnek, Kişiselleştirme kaynağınız için Azure portal zaman tabanlı olayları kullanır. Bu değerlerle oynayın ve ardından değişikliklerin Derece ve Ödül çağrılarını nasıl etkileyeni görmek için bu örnek web uygulamasına geri dönebilirsiniz:

• Ödül bekleme süresi
• Model güncelleştirme sıklığı

Oynatacak ek ayarlar şunlardır:

• Varsayılan ödül
• Keşif yüzdesi

Kaynakları temizleme

Bu öğreticiyi tamamlasanız aşağıdaki kaynakları temizleyin:

• Örnek proje dizininizi silin.
• Kişiselleştirme kaynağınızı silin ( kişiselleştirme kaynağını eylemlere ve bağlama ayrılmış olarak düşünebilirsiniz) yalnızca besinleri eylem konusu etki alanı olarak kullanıyorsanız kaynağı yeniden kullanın.

Sonraki adımlar

• Kişiselleştirme nasıl çalışır?
• Özellikler:Eylemler ve bağlam ile kullanan özelliklerle ilgili kavramları öğrenin
• Rewards:Ödül hesaplama hakkında bilgi alın