APIAPI

Azure 自訂決策服務提供每個決策所需的兩個 API:排名 API 可輸入動作的排名,以及獎勵 API 可輸出獎勵。Azure Custom Decision Service provides two APIs that are called for each decision: the Ranking API to input the ranking of actions and the Reward API to output the reward. 此外,您可以將指定動作的動作集 API 提供給 Azure 自訂決策服務。In addition, you provide an Action Set API to specify the actions to Azure Custom Decision Service. 本文說明這三種 API。This article covers these three APIs. 以下使用一個典型的案例來示範自訂決策服務何時最佳化發行項的排名。A typical scenario is used below to show when Custom Decision Service optimizes the ranking of articles.

排名 APIRanking API

排名 API 使用標準 JSONP 樣式通訊模式來最佳化延遲,並略過相同來源原則The ranking API uses a standard JSONP-style communication pattern to optimize latency and bypass the same-origin policy. 後者禁止 JavaScript 擷取頁面來源以外的資料。The latter prohibits JavaScript from fetching data from outside the page's origin.

將此程式碼片段插入您首頁的 HTML 標頭 (發行項的個人化清單顯示位置):Insert this snippet into the HTML head of your front page (where a personalized list of articles are displayed):

// define the "callback function" to render UI
<script> function callback(data) { … } </script>
// "data" provides the ranking of URLs, see example below.

// call to Ranking API
<script src="https://ds.microsoft.com/api/v2/<appId>/rank/<actionSetId>?<parameters>" async></script>
// action set id is the name of the corresponding RSS/Atom feed.

// same call with multiple action sets:
// <script src="https://ds.microsoft.com/api/v2/<appId>/rank/<A1>/<A2>/.../<An>?<parameters>" async></script>

重要

必須在排名 API 呼叫前定義回呼函數。The callback function must be defined before the call to the Ranking API.

提示

若要改善延遲,請透過 HTTP 而不是 HTTPS 公開排名 API,如 https://ds.microsoft.com/api/v2/<appId>/rank/* 中所示。To improve latency, the Ranking API is exposed via HTTP rather than HTTPS, as in https://ds.microsoft.com/api/v2/<appId>/rank/*. 不過,若透過 HTTPS 提供首頁,則必須使用 HTTPS 端點。However, an HTTPS endpoint must be used if the front page is served through HTTPS.

不使用參數時,來自排名 API 的 HTTP 回應會是 JSONP 格式字串:When parameters are not used, the HTTP response from the Ranking API is a JSONP-formatted string:

callback({
   "ranking":[{"id":"url1"}, {"id":"url2"}, {"id":"url3"}],
   "eventId":"<opaque event string>",
   "appId":"<your app id>",
   "actionSets":[{"id":"<A1>","lastRefresh":"2017-04-29T22:34:25.3401438Z"},
                 {"id":"<A2>","lastRefresh":"2017-04-30T22:34:25.3401438Z"}]});

瀏覽器會接著執行此字串作為 callback() 函式的呼叫。The browser then executes this string as a call to the callback() function.

上述範例中的回呼函數參數具有下列結構描述:The parameter to the callback function in the preceding example has the following schema:

  • ranking 會提供要顯示的 URL 排名。ranking provides the ranking of URLs to be displayed.
  • 自訂決策服務會在內部使用 eventId 來比對此排名與對應的點選。eventId is used internally by Custom Decision Service to match this ranking with the corresponding clicks.
  • appId 可讓回呼函數區分相同網頁上執行之自訂決策服務的多個應用程式。appId allows the callback function to distinguish between multiple applications of Custom Decision Service running on the same webpage.
  • actionSets 會列出用於排名 API 呼叫中的每個動作集,以及上次成功重新整理的 UTC 時間戳記。actionSets lists each action set used in the Ranking API call, along with the UTC timestamp of the last successful refresh. 自訂決策服務會定期重新整理動作集摘要。Custom Decision Service periodically refreshes the action set feeds. 例如,若某些動作集不是最新的,回呼函數可能需要切換回其預設排名。For example, if some of the action sets are not current, the callback function might need to fall back to their default ranking.

重要

指定的動作集已經過處理並可能剪除,來形成發行項的預設排名。The specified action sets are processed, and possibly pruned, to form the default ranking of articles. 預設排名會接著重新排序並在 HTTP 回應中傳回。The default ranking then gets reordered and returned in the HTTP response. 預設排名的定義如下:The default ranking is defined here:

  • 在每個動作集內,發行項已剪除至 15 個最新的發行項 (若傳回 15 個以上)。Within each action set, the articles are pruned to the 15 most recent articles (if more than 15 are returned).
  • 指定多個動作集時,會依其在 API 呼叫中的相同順序來合併。When multiple action sets are specified, they are merged in the same order as in the API call. 發行項的原始排序會保留在每個動作集內。The original ordering of the articles is preserved within each action set. 重複項目會遭到移除,以改用較早複本。Duplicates are removed in favor of the earlier copies.
  • n 個發行項會與發行項的合併清單分開保留,預設為 n=20The first n articles are kept from the merged list of articles, where n=20 by default.

使用參數的排名 APIRanking API with parameters

排名 API 允許下列參數:The Ranking API allows these parameters:

  • details=1details=2 會插入 ranking 中所列每個發行項的其他詳細資料。details=1 and details=2 inserts additional details about each article listed in ranking.
  • limit=<n> 會指定預設排名中的最大發行項數。limit=<n> specifies the maximal number of articles in the default ranking. n 必須介於 230 之間 (否則會分別截斷至 230)。n must be between 2 and 30 (or else it is truncated to 2 or 30, respectively).
  • dnt=1 會停用使用者 Cookie。dnt=1 disables user cookies.

參數可結合成標準查詢字串語法,例如 details=2&dnt=1Parameters can be combined in standard, query string syntax, for example details=2&dnt=1.

重要

歐洲的預設設定應該是 dnt=1,直到客戶同意 Cookie 橫幅為止。The default setting in Europe should be dnt=1 until the customer agrees to the cookie banner. 它也應該是目標為未成年人之網站的預設設定。It should also be the default setting for websites that target minors. 如需詳細資訊,請參閱使用規定For more information, see the terms of use.

details=1 項目若由動作集 API 提供,則會插入每個發行項的 guidThe details=1 element inserts each article's guid, if it's served by the Action Set API. HTTP 回應:The HTTP response:

callback({
   "ranking":[{"id":"url1","details":[{"guid":"123"}]},
              {"id":"url2","details":[{"guid":"456"}]},
              {"id":"url3","details":[{"guid":"789"}]}],
   "eventId":"<opaque event string>",
   "appId":"<your app id>",
   "actionSets":[{"id":"<A1>","lastRefresh":"timeStamp1"},
                 {"id":"<A2>","lastRefresh":"timeStamp2"}]});

details=2 項目會新增 自訂決策服務可能從發行項的 SEO 中繼標籤功能化程式碼擷取的更多詳細資料:The details=2 element adds more details that Custom Decision Service might extract from articles' SEO metatags featurization code:

  • 來自 <meta property="og:title" content="..." /><meta property="twitter:title" content="..." /><title>...</title>titletitle from <meta property="og:title" content="..." /> or <meta property="twitter:title" content="..." /> or <title>...</title>
  • 來自 <meta property="og:description" ... /><meta property="twitter:description" content="..." /><meta property="description" content="..." />descriptiondescription from <meta property="og:description" ... /> or <meta property="twitter:description" content="..." /> or <meta property="description" content="..." />
  • 來自 <meta property="og:image" content="..." />imageimage from <meta property="og:image" content="..." />
  • 來自 <meta name=”microsoft:ds_id” content="..." />ds_idds_id from <meta name=”microsoft:ds_id” content="..." />

HTTP 回應:The HTTP response:

callback({
   "ranking":[{"id":"url1","details":<details>},
              {"id":"url2","details":<details>},
              {"id":"url3","details":<details>}],
   "eventId":"<opaque event string>",
   "appId":"<your app id>",
   "actionSets":[{"id":"<A1>","lastRefresh":"timeStamp1"},
                 {"id":"<A2>","lastRefresh":"timeStamp2"}]});

<details> 項目:The <details> element:

[{"guid":"123"}, {"description":"some text", "ds_id":"234", "image":"ImageUrl1", "title":"some text"}]

獎勵 APIReward API

自訂決策服務只會使用熱門位置的點選。Custom Decision Service uses clicks only on the top slot. 每個點選會解譯為獎勵 1。Each click is interpreted as a reward of 1. 缺少點選會解譯為獎勵 0。The lack of a click is interpreted as a reward of 0. 點選會使用事件識別碼與對應排名進行比對,這是由排名 API 呼叫所產生。Clicks are matched with the corresponding rankings by using event IDs, which are generated by the Ranking API call. 如有需要,事件識別碼可透過工作階段 Cookie 傳遞。If needed, event IDs can be passed via session cookies.

若要處理熱門位置的點選,請將此程式碼放在您的首頁:To handle a click on the top slot, put this code on your front page:

$.ajax({
    type: "POST",
    url: '//ds.microsoft.com/api/v2/<appId>/reward/' + data.eventId,
    contentType: "application/json" })

在此,datacallback() 函式的引數,如上所述。Here data is the argument to the callback() function, as described previously. 在點選處理程式碼中使用 data 需要稍加注意。Using data in the click handling code requires some care. 教學課程中顯示一個範例。An example is shown in this tutorial.

獎勵 API 僅供測試之用,可透過 cURL 呼叫:For testing only, the Reward API can be called via cURL:

curl -v https://ds.microsoft.com/api/v2/<appId>/reward/<eventId> -X POST -d 1 -H "Content-Type: application/json"

預期的效果為 HTTP 回應 200 (確定)。The expected effect is an HTTP response of 200 (OK). 您可以看到記錄中此事件的獎勵為 1 (若入口網站上已提供 Azure 儲存體帳戶金鑰)。You can see the reward of 1 for this event in the log (if an Azure storage account key was supplied on the portal).

動作集 API (客戶提供)Action Set API (customer provided)

在高層級,動作集 API 會傳回發行項 (動作) 清單。On a high level, the Action Set API returns a list of articles (actions). 每個發行項是由其 URL 及 (選擇性) 發行項標題和發行日期指定。Each article is specified by its URL and (optionally) the article title and the publication date. 您可以在入口網站上指定幾個動作集。You can specify several action sets on the portal. 每個動作集應該使用不同的動作集 API 作為相異 URL。A different Action Set API should be used for each action set, as a distinct URL.

每個動作集 API 可透過兩個方式來實作:作為 RSS 摘要或作為 Atom 摘要。Each Action Set API can be implemented in two ways: as an RSS feed or as an Atom feed. 不論是哪一個都應該符合標準並傳回正確的 XML。Either one should conform to the standard and return a correct XML. 以下是 RSS 範例:For RSS, here's an example:

<rss version="2.0">
<channel>
   <item>
      <title><![CDATA[title (possibly with url) ]]></title>
      <link>url</link>
      <guid>guid (could be a your internal database id)</guid>
      <pubDate>date</pubDate>
    </item>
   <item>
       ....
   </item>
</channel>
</rss>

每個最上層 <item> 項目會描述一個動作:Each top-level <item> element describes an action:

  • <link> 是必要的,可作為動作識別碼。<link> is mandatory and is used as an action ID.
  • <date> 小於或等於 15 個項目,則會予以忽略;否則是必要的。<date> is ignored if it's less than or equal to 15 items; otherwise, it's mandatory.
    • 若有 15 個以上的項目,則會使用 15 個最新的項目。If there are more than 15 items, the 15 most recent ones are used.
    • 它必須是 RSS 或 Atom 的標準格式,分別為:It must be in the standard format for RSS or Atom, respectively:
      • RSS 為 RFC 822:例如,"Fri, 28 Apr 2017 18:02:06 GMT"RFC 822 for RSS: for example, "Fri, 28 Apr 2017 18:02:06 GMT"
      • Atom 為 RFC 3339:例如,"2016-12-19T16:39:57-08:00"RFC 3339 for Atom: for example, "2016-12-19T16:39:57-08:00"
  • <title> 為選擇性,可用來產生描述發行項的功能。<title> is optional and is used to generate features that describe the article.
  • <guid> 為選擇性,可透過系統傳遞至回呼函數 (若在排名 API 呼叫中指定 ?details 參數)。<guid> is optional and passed through the system to the callback function (if the ?details parameter is specified in the Ranking API call).

<item> 內的其他項目則會予以忽略。Other elements inside an <item> are ignored.

Atom 摘要版本使用相同的 XML 語法和慣例。The Atom feed version uses the same XML syntax and conventions.

提示

若您的系統使用其本身的發行項識別碼,則可以使用 <guid> 傳遞至回呼函數。If your system uses its own article IDs, they can be passed into the callback function by using <guid>.