從應用程式呼叫 APICall API from an app

從智慧型手機應用程式呼叫 Azure 自訂決策服務 API。Make calls to the Azure Custom Decision Service APIs from a smartphone app. 本文說明如何開始使用一些基本選項。This article explains how to get started with some basic options.

請務必先註冊應用程式Be sure to Register your application, first.

您會從智慧型手機應用程式對自訂決策服務進行兩次 API 呼叫:呼叫排名 API 以取得您內容的排名清單,以及呼叫獎勵 API 以報告獎勵。There are two API calls you make from your smartphone app to Custom Decision Service: a call to the Ranking API to obtain a ranked list of your content and a call to the Reward API to report a reward. 以下是 cURL 中的範例呼叫。Here are the sample calls in cURL.

如需詳細資訊,請參閱參考 APIFor more information, see the reference API.

從排名 API 呼叫開始。Start with the call to the Ranking API. 建立 <request.json> 檔案,其中包含動作集識別碼。Create the file <request.json>, which has the action set ID. 此識別碼是您在入口網站上輸入之對應 RSS 或 Atom 摘要的名稱:This ID is the name of the corresponding RSS or Atom feed that you entered on the portal:

{"decisions":
     [{ "actionSets":[{"id":{"id":"<actionSetId>"}}] }]}

許多動作集可以指定如下:Many action sets can be specified as follows:

{"decisions":
    [{ "actionSets":[{"id":{"id":"<actionSetId1>"}},
                     {"id":{"id":"<actionSetId2>"}}] }]}

此 JSON 檔案接著會傳送為排名要求的一部分:This JSON file is then sent as part of the ranking request:

curl -d @<request.json> -X POST https://ds.microsoft.com/api/v2/<appId>/rank --header "Content-Type: application/json"

在這裡,<appId> 是入口網站上註冊的應用程式名稱。Here, <appId> is the name of your application registered on the portal. 您應該會收到可在應用程式中轉譯的一組排序過內容項目。You should receive an ordered set of content items, which you can render in your application. 範例傳回如下:A sample return looks like:

[{ "ranking":[{"id":"actionId3"}, {"id":"actionId1"}, {"id":"actionId2"}],
   "eventId":"<opaque event string>",
   "appId":"<your app id>",
   "rewardAction":"actionId3",
   "actionSets":[{"id":"<actionSetId1>","lastRefresh":"2017-04-29T22:34:25.3401438Z"},
                 {"id":"<actionSetId2>","lastRefresh":"2017-04-30T22:34:25.3401438Z"}]}]

傳回的第一個部分包含以其動作識別碼所指定的已排序動作清單。The first part of the return has a list of ordered actions, specified by their action IDs. 針對發行項,動作識別碼是 URL。For an article, the action ID is a URL. 整體要求也會有系統建立的唯一 <eventId>The overall request also has a unique <eventId>, created by the system.

稍後,您可以指定是否從此事件觀察到按一下第一個內容項目,即 <actionId3>Later, you can specify if you observed a click on the first content item from this event, which is <actionId3>. 您接著可以使用與下列類似的另一個要求,透過獎勵 API 將此 <eventId> 上的獎勵回報給自訂決策服務:You can then report a reward on this <eventId> to Custom Decision Service via the Reward API, with another request such as:

curl -v https://ds.microsoft.com/api/v2/<appId>/reward/<eventId> -X POST

最後,您需要提供動作集 API,以傳回自訂決策服務要考量的發行項 (動作) 清單。Finally, you need to provide the Action Set API, which returns the list of articles (actions) to be considered by Custom Decision Service. 實作此 API 作為 RSS 摘要,如這裡所示:Implement this API as an RSS feed, as shown here:

<rss version="2.0">
<channel>
   <item>
      <title><![CDATA[title (possibly with url) ]]></title>
      <link>url</link>
      <pubDate>Thu, 27 Apr 2017 16:30:52 GMT</pubDate>
    </item>
   <item>
       ....
   </item>
</channel>
</rss>

在這裡,每個最上層 <item> 項目都會描述一篇文章。Here, each top-level <item> element describes an article. <link> 是必要項目,而且自訂決策服務用來作為動作識別碼。The <link> is mandatory and is used as an action ID by Custom Decision Service. 若您的發行項超過 15 個,則請指定 <date> (標準 RSS 格式)。Specify <date> (in a standard RSS format) if you've more than 15 articles. 會使用 15 個最新發行項。The 15 most recent articles are used. <title> 為選擇性且用來建立發行項的文字相關功能。The <title> is optional and is used to create text-related features for the article.

後續步驟Next steps

  • 完成教學課程以了解更深入的範例。Work through a tutorial for a more in-depth example.
  • 請參閱參考 API 以深入了解提供的功能。Consult the reference API to learn more about the provided functionality.