您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

APIAPI

Azure 自定义 AI 决策服务提供两种可以根据每种决策进行调用的 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 自定义 AI 决策服务的操作。In addition, you provide an Action Set API to specify the actions to Azure Custom Decision Service. 本文介绍以下三个 API。This article covers these three APIs. 下面使用了一个典型的方案来演示自定义 AI 决策服务何时优化文章的排名。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 供自定义 AI 决策服务在内部使用,这样此排名就会与相应的点击数相匹配。eventId is used internally by Custom Decision Service to match this ranking with the corresponding clicks.
  • 回调函数可以通过 appId 在同一网页的多个正在运行的自定义 AI 决策服务应用程序之间进行区分。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. 自定义 AI 决策服务定期刷新操作集源。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=20(默认)。The 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 元素插入每篇文章的 guid,前提是该文章通过操作集 API 提供。The 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 元素添加更多详细信息,自定义 AI 决策服务可以从文章的 SEO 元标记特征化代码中提取这些详细信息:The details=2 element adds more details that Custom Decision Service might extract from articles' SEO metatags featurization code:

  • title 来自 <meta property="og:title" content="..." /><meta property="twitter:title" content="..." /><title>...</title>title from <meta property="og:title" content="..." /> or <meta property="twitter:title" content="..." /> or <title>...</title>
  • description 来自 <meta property="og:description" ... /><meta property="twitter:description" content="..." /><meta property="description" content="..." />description from <meta property="og:description" ... /> or <meta property="twitter:description" content="..." /> or <meta property="description" content="..." />
  • image 来自 <meta property="og:image" content="..." />image from <meta property="og:image" content="..." />
  • ds_id 来自 <meta name=”microsoft:ds_id” content="..." />ds_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

自定义 AI 决策服务仅在榜首使用点击数。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 调用所生成的事件 ID 与相应的排名匹配。Clicks are matched with the corresponding rankings by using event IDs, which are generated by the Ranking API call. 事件 ID 可以根据需要通过会话 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> 是必需的,用作操作 ID。<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:
      • RFC 822 适用于 RSS:例如 "Fri, 28 Apr 2017 18:02:06 GMT"RFC 822 for RSS: for example, "Fri, 28 Apr 2017 18:02:06 GMT"
      • RFC 3339 适用于 Atom:例如 "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.

提示

如果系统使用其自己的文章 ID,则可通过 <guid> 将其传递到回调函数中。If your system uses its own article IDs, they can be passed into the callback function by using <guid>.