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

从应用调用 APICall API from an app

从智能手机应用调用 Azure 自定义 AI 决策服务 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.

可以通过智能手机应用程序向自定义 AI 决策服务进行两次 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.

有关详细信息,请参阅 API 参考For more information, see the reference API.

首先调用排名 API。Start with the call to the Ranking API. 创建具有操作集 ID 的文件 <request.json>Create the file <request.json>, which has the action set ID. 此 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"}]}]

返回的第一部分包含由其操作 ID 指定的有序操作列表。The first part of the return has a list of ordered actions, specified by their action IDs. 对于文章,操作 ID 是 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 向自定义 AI 决策服务报告对此 <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,这将返回自定义 AI 决策服务考虑的文章(操作)列表。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> 是必需的,由自定义 AI 决策服务用作操作 ID。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.