Azure Mobile Engagement - Integrazione di APIAzure Mobile Engagement - API integration

In un sistema marketing automatizzato, vengono eseguite automaticamente anche la creazione e l'attivazione delle campagne di marketing.In an automated marketing system, creating and activating the marketing campaigns also occur automatically. A questo scopo, Azure Mobile Engagement permette la creazione di tali campagne marketing automatizzate anche mediante le API.For this purpose - Azure Mobile Engagement enables creating such automated marketing campaigns using APIs as well.

In genere i clienti usano l'interfaccia del front-end di Mobile Engagement per creare annunci/sondaggi e così via come parte delle campagne di marketing.Typically customers use the Mobile Engagement front end interface to create announcements/polls etc as part of their marketing campaigns. Nel corso della maturazione delle campagne di marketing, tuttavia, diventa necessario sfruttare i dati bloccati nei sistemi back-end (ad esempio qualsiasi sistema CRM o un sistema CMS come SharePoint), in modo che sia possibile creare una pipeline automatizzata completa, che crea a sua volta in modo dinamico campagne in Mobile Engagement in base ai dati provenienti dai sistemi back-end.However as the marketing campaigns become mature, there is a need to leverage the data locked in the backend systems (like any CRM system or CMS system like SharePoint) so that a fully automated pipeline can be created which creates campaigns in Mobile Engagement dynamically based on the data flowing in from the backend systems.

Questa esercitazione illustra uno scenario di questo tipo, in cui un utente aziendale di SharePoint popola un elenco di SharePoint con dati di marketing e un processo automatizzato sceglie elementi dall'elenco e li connette al sistema Mobile Engagement usando le API REST disponibili per creare una campagna di marketing dai dati di SharePoint.This tutorial goes through such a scenario where a SharePoint business user populates a SharePoint list with marketing data and an automated process picks up items from the list and connects with the Mobile Engagement system using the available REST APIs to create a marketing campaign from the SharePoint data.

Importante

In generale, è possibile usare questo esempio come punto di partenza per capire come chiamare qualsiasi API REST di Mobile Engagement, poiché illustra nel dettaglio i due aspetti chiave della chiamata delle API, ovvero l'autenticazione e il passaggio di parametri.In general, you can use this sample as a starting point for understanding how to call any Mobile Engagement REST API as it details the two key aspects of calling the APIs - authenticating and passing parameters.

Integrazione con SharePointSharePoint integration

  1. L'elenco di SharePoint di esempio ha un aspetto analogo al seguente.Here is what the sample SharePoint list looks like. I valori di Title, Category, NotificationTitle, Message e URL vengono usati per la creazione dell'annuncio.Title, Category, NotificationTitle, Message and URL are used for creating the announcement. La colonna IsProcessed viene usata dal processo di automazione di esempio sotto forma di programma console.There is a column called IsProcessed which is used by the sample automation process in the form of a console program. È possibile eseguire questo programma console come processo Web di Azure, in modo che sia possibile pianificarlo, oppure si può usare direttamente il flusso di lavoro di SharePoint per programmare la creazione e l'attivazione dell'annuncio quando un elemento viene inserito nell'elenco di SharePoint.You can either run this console program as an Azure WebJob so that you can schedule it or you can directly use the SharePoint workflow to program creating and activating the announcement when an item is inserted into the SharePoint list. In questo esempio viene usato il programma console, che esamina gli elementi dell'elenco di SharePoint, crea annunci in Azure Mobile Engagement per ogni elemento e infine contrassegna il flag IsProcessed come true in caso di creazione riuscita dell'annuncio.In this sample we use the console program which goes through the items in the SharePoint list and create announcement in Azure Mobile Engagement for each of them and then finally marks the IsProcessed flag to be true on successful announcement creation.

  2. Per l'autenticazione nell'elenco di SharePoint viene usato il codice dell'esempio di Autenticazione remota in SharePoint Online mediante il modello a oggetti client qui .We are using the code from the sample Remote Authentication in SharePoint Online Using the Client Object Model here to authenticate with the SharePoint list.
  3. Dopo l'autenticazione, gli elementi dell'elenco verranno esaminati in ciclo per individuare eventuali elementi appena creati, il cui valore IsProcessed sarà false.Once authenticated, we loop through the list items to find out any newly created items (which will have IsProcessed = false).

      static async void CreateCampaignFromSharepoint()
     {
         using (ClientContext clientContext = ClaimClientContext.GetAuthenticatedContext(targetSharepointSite))
         {
             // Using https://code.msdn.microsoft.com/Remote-Authentication-in-b7b6f43c for authentication     
             Web site = clientContext.Web;
             List list = site.Lists.GetByTitle("VideoContent");
             CamlQuery query = new CamlQuery();
             query.ViewXml = "<View/>";
             ListItemCollection items = list.GetItems(query);
    
             // Load the SharePoint list
             clientContext.Load(list);
             clientContext.Load(items);
             clientContext.ExecuteQuery();
    
             // Loop through the list to go through all the items which are newly added
             foreach (ListItem item in items)
                 if (item["IsProcessed"].ToString() != "Yes")
                 {
                     string name = item["Title"].ToString();
                     string notificationTitle = item["NotificationTitle"].ToString();
                     string notificationMessage = item["Message"].ToString();
                     string category = item["Category"].ToString();
                     string actionURL = ((FieldUrlValue)item["URL"]).Url;
    
                     // Send an HTTP request to create AzME campaign
                     int campaignId = CreateAzMECampaign
                         (name, notificationTitle, notificationMessage, category, actionURL).Result;
    
                     if (campaignId != -1)
                     {
                         // If creating campaign is successful then set this to true
                         item["IsProcessed"] = "Yes";
    
                         // Now try to activate the campaign also
                         await ActivateAzMECampaign(campaignId);
                     }
                     else
                     {
                         item["IsProcessed"] = "Error";
                     }
                     item.Update();
                 }
             clientContext.ExecuteQuery();
         }
     }
    

Integrazione con Mobile EngagementMobile Engagement integration

  1. Quando viene rilevato un elemento che richiede l'elaborazione, vengono estratte le informazioni necessarie per creare un annuncio dall'elemento dell'elenco, viene chiamato CreateAzMECampaign per creare l'annuncio e infine ActivateAzMECampaign per attivarlo.Once we find an item which requires processing - we extract the information required to create an announcement from the list item and call CreateAzMECampaign to create it and subsequently ActivateAzMECampaign to activate it. Si tratta essenzialmente di chiamate all'API REST per il back-end di Mobile Engagement.These are essentially REST API calls calling to the Mobile Engagement backend.
  2. Le API REST di Mobile Engagement necessitano di un'intestazione HTTP dell'autorizzazione dello schema di autorizzazione di base, costituita da ApplicationId e ApiKey, disponibili nel portale di Azure.The Mobile Engagement REST APIs require a Basic auth scheme authorization HTTP header which is composed of the ApplicationId and the ApiKey which you get from the Azure portal. Assicurarsi di usare la chiave della sezione Chiavi API e non della sezione Chiavi SDK.Make sure that you are using the Key from the api keys section and not from the sdk keys section.

    static string CreateAuthZHeader()
    {
        string BasicAuthzHeaderString = "Basic " + EncodeTo64(ApplicationId + ":" + ApiKey);
        return BasicAuthzHeaderString;
    }
    
    static public string EncodeTo64(string toEncode)
    {
        byte[] toEncodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(toEncode);
        string returnValue = System.Convert.ToBase64String(toEncodeAsBytes);
        return returnValue;
    }  
    
  3. Per la creazione di una campagna di tipo annuncio, fare riferimento alla documentazione.For creating the announcement type campaign - refer to the documentation. È necessario assicurarsi di specificare l'elemento kind della campagna come announcement e il payload e infine di passarlo come FormUrlEncodedContent.You need to make sure that you are specifying the campaign kind as announcement and the payload and passing it as FormUrlEncodedContent.

     static async Task<int> CreateAzMECampaign(string campaignName, string notificationTitle, 
         string notificationMessage, string notificationCategory, string actionURL)
     {
         string createURIFragment = "/reach/1/create";
    
         using (var client = new HttpClient())
         {
             // Add Authorization Header
             client.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", CreateAuthZHeader());
    
             // Create the payload to send the content
             // Reference -> https://msdn.microsoft.com/library/dn913749.aspx
             string data =
                 @"{""name"":""" + campaignName + @"""," + 
                 @"""type"":""only_notif""," + 
                 @"""deliveryTime"":""any"","" + 
                 @""notificationTitle"":""" + notificationTitle + 
                 @""",""notificationMessage"":""" + notificationMessage + 
                 @""",""actionUrl"":""" + actionURL + @"""}";
    
             var content = new FormUrlEncodedContent(new[] 
             {
                 new KeyValuePair<string, string>("kind", "announcement"),
                 new KeyValuePair<string, string>("data", data),
             });
    
             // Send the POST request
             var response = await client.PostAsync(url + createURIFragment, content);
             var responseString = response.Content.ReadAsStringAsync().Result;
             int campaignId = -1;
             if (response.StatusCode.ToString() == "OK")
             {
                 // This is the campaign id
                 campaignId = Convert.ToInt32(responseString);
                 Console.WriteLine("Campaign successfully created with id {0}", campaignId);
             }
             else
             {
                 Console.WriteLine("Campaign creation failed with error - '{0}'", responseString);
             }
             return campaignId;
         }
     }
    
  4. Al termine della creazione dell'annuncio, il portale di Mobile Engagement avrà un aspetto analogo al seguente. Si noti che Stato=Bozza e Attivato = N/D.Once you have the announcement created, you will see something like the following on the Mobile Engagement portal (note that the State=Draft and Activated = N/A)

  5. CreateAzMECampaign crea una campagna di tipo annuncio e restituisce il rispettivo ID al chiamante.CreateAzMECampaign creates an announcement campaign and returns its Id to the caller. ActivateAzMECampaign richiede questo ID come parametro per l'attivazione della campagna.ActivateAzMECampaign requires this Id as the parameter to activate the campaign.

     static async Task<bool> ActivateAzMECampaign(int campaignId)
     {
         string activateUriFragment = "/reach/1/activate";
         using (var client = new HttpClient())
         {
             // Add Authorization Header
             client.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", CreateAuthZHeader());
    
             var content = new FormUrlEncodedContent(new[] 
             {
                 new KeyValuePair<string, string>("kind", "announcement"),
                 new KeyValuePair<string, string>("id", campaignId.ToString()),
             });
    
             // Send the POST request
             var response = await client.PostAsync(url + activateUriFragment, content);
             var responseString = response.Content.ReadAsStringAsync().Result;
             if (response.StatusCode.ToString() == "OK")
             {
                 Console.WriteLine("Campaign successfully activated");
                 return true;
             }
             else
             {
                 Console.WriteLine("Campaign activation failed with error - '{0}'", responseString);
                 return false;
             }
         }
     }
    
  6. Dopo l'attivazione dell'annuncio, il portale di Mobile Engagement avrà un aspetto analogo al seguente:Once you have the announcement activated, you will see something like the following on the Mobile Engagement portal:

  7. Non appena viene attivata la campagna, tutti i dispositivi che soddisfano i criteri della campagna inizieranno a visualizzare notifiche.As soon as the campaign gets activated, any devices which satisfy the criterion on the campaign will start seeing notifications.
  8. Si potrà anche notare che l'elemento dell'elenco contrassegnato come IsProcessed = false è stato impostato su True dopo la creazione della campagna.You will also notice that the list item marked with IsProcessed = false has been set to True once the announcement campaign is created.

Questo esempio ha creato una semplice campagna di tipo annuncio, specificando principalmente le proprietà necessarie.This sample created a simple announcement campaign specifying mostly the required properties. È possibile personalizzare come si desidera l'esempio nel portale, usando le informazioni disponibili qui.You can customize this as much as you can from the portal by using the information here.