查看原文
其他

发布 Actions on Google 的 Java 和 Kotlin 客户端库

Google 谷歌开发者 2019-11-02

自平台首次推出以来,我们一直为 Actions on Google 的 Node.js 客户端库提供支持。我们从使用此客户端库的开发者那里了解了很多情况。我们还确切了解到,大家希望我们更好地支持使用 Java™ 编程语言构建适合消费者和企业用例的 Actions。我们非常高兴地发布了 Actions on Google 的 Java 客户端库。



了解 Actions 的运行原理

Actions on Google 支持 Google 助理与您的 Fulfillment 之间基于 JSON 的协议。为参与与 Actions on Google 的对话,您的 Action 会执行一个 Fulfillment Webhook,此 Webhook 能够响应 Actions on Google 发出的 HTTP 请求。


图 1:流程图所示为多个子系统之间的交互,这些子系统都参与了与 Google 助理的对话。底色为橙色的部分是托管在 Google Cloud Platform 上的 Action Fulfillment Webhook


图 1 所示为最终用户、Google 助理、Dialogflow 和 Action Fulfillment 之间的交互示例。简而言之,就是 Google 助理将用户的语音输入转换成文本。接下来,系统必须理解语音输入的内容。Dialogflow 使用机器学习将文本准确映射至用户意图并提取实体(例如地点、物品、日期 / 时间等)。Dialogflow 使用 JSON 负载调用 Action Fulfillment Webhook,此负载包含其从文本中提取的全部信息。Action Fulfillment(图中橙色高亮部分)处理 JSON 请求,然后实现逻辑以回应 Google 助理(或 Dialogflow)。设备上的 Google 助理将响应转换成语音并(在屏幕设备上)播放。



Java/Kotlin 客户端库简介

正如前一部分中所述,Action 需要执行一个 Fulfillment Webhook,该 Webhook 可以通过 Google 助理发出的 HTTP POST 请求接收 JSON,然后按照 Actions on Google 的 JSON 规范使用 JSON 进行响应。要使用 Java 编程语言执行 Webhook,开发者可以按照以下步骤进行操作:

  • 实现一个可公开访问的云端点:实现一个 Google Cloud Platform 的 Servlet 或类似的云解决方案,以通过 HTTP POST 接收 JSON 负载

  • 解析请求:将 JSON 正文中的信息解析为 Java 对象

  • 传递请求:从请求的 JSON 中提取匹配的意图,然后执行相应的业务逻辑

  • 为用户汇集响应

  • 将响应序列化为 JSON,并将其作为对从 Google 收到的 HTTP POST 的响应发送


上述任务适用于所有 Action。我们希望通过支持客户端库中的大多数常用 Action 来让 Action 构建工作变得更轻松,这样您就可以集中精力完成最重要的任务 — Action 的逻辑。Java/Kotlin 客户端库可以实现上述全部功能,提供优质的 API,同时让您从 JSON 协议的内部工作中抽身。我们来看看这是如何做到的。



云端点的样板代码

云平台要求您实现特定的类以处理 HTTP 请求。如果是 Google App Engine 和 AWS Lambda 的 RequestStreamHandler,示例会添加 HttpServlet。如果您使用 Spring 框架,则可能需要在处理程序类中实现相应的注解。


为了帮助您快速上手,我们提供了实现此管道的样板代码。建议您在开始项目时先克隆此样板代码。样板代码是最简单快速的方式,通过读取 HTTP 请求中的 JSON 并将其委派给 App 对象来为您的 Action 实现 Webhook。


我们的样板代码目前以入口点的形式支持 Google Cloud Platform 和 AWS Lambda。如果您的 Webhook 托管在不同的云平台中,您应该能够根据自己的需求轻松调整样板代码。类似地,修改 Spring 和 / 或 Kotlin 的样板代码应该也很简单。



请求处理

此客户端库提供有一个顶级接口 App.handleRequest(),用于处理来自 Google 助理的请求。DefaultApp 是 App 的一个子类,通过先将 JSON 解析到 Java 类来实现请求处理逻辑。为了让这个流程更加简单并且不易出错,我们提供了 Java 类 (POJO),它们可以 1:1 映射至 JSON 协议中定义的概念。我们称其为 “绑定类”。通过这些绑定类提供的强大输入功能让 IntelliJ 和 Visual Studio Code 等 IDE 可以在代码编辑器中自动建议类和方法名称。


将请求成功解析到绑定类后,DefaultApp 会从请求中提取意图名称,然后使用此名称将请求传递给特定方法。客户端库通过 @ForIntent Java 注解简练地执行传递。作为开发者,您只需在意图处理程序中实现 Action 的逻辑,具体内容我们将在下一部分中介绍。



意图处理程序

意图是用户想要实现的目标或进行的操作,例如听歌或点咖啡。Actions on Google 用一个唯一标识符来表示意图。您的 Action Webhook 为其想要动态处理的意图提供处理程序。在 Java 客户端库中,此 Webhook 作为扩展 DialogflowApp 或 ActionsSdkApp 的 Java 类实现。在这个用特殊注解 @ForIntent(如下图所示)标记的类中,意图处理程序是公共方法。意图处理程序接受 ActionRequest 对象作为参数,并返回 ActionResponse 对象。

public class MyActionsApp extends DialogflowApp {
   @ForIntent(“Default Welcome Intent”)
   public ActionResponse welcome(ActionRequest request) {
      // Intent handler implementation.
   }
}


在上图的代码中,该方法响应 “Default Welcome Intent”,这是在 Dialogflow 中定义的意图名称(区分大小写)。此客户端库从 JSON 请求中提取意图名称,并将该请求传递给基于 @ForIntent 注解值的特定处理程序。


图 2:Dialogflow 中的意图页面。在本例中,意图名称为 “Default Welcome Intent”



汇集响应

意图处理程序会返回发送回 Google 助理的相关 Fulfillment 响应,Google 助理最终会将其以语音和 / 或视觉响应的形式传达给用户。最简单的说法是,Google 助理将文本响应读给用户。Actions on Google 还支持许多其他响应格式,包括带有图像的沉浸式卡片、轮播界面、列表、媒体和 SSML。您的 Action 也可能会以 Google 助理支持的一种帮助意图进行响应。示例包含了请求用户确认或获得用户权限以获取其位置的内容。


ResponseBuilder 类可以提供各种汇集响应的辅助工具方法。在最简单的情况下,您的 Action 会以文本作为响应:

@ForIntent(“welcome”)
public ActionResponse welcome(ActionRequest request) {
   ResponseBuilder responseBuilder = getResponseBuilder(request);
   responseBuilder.add(“Welcome to my app”);
   return responseBuilder.build();
}


下面的响应使用 BasicCard 来呈现视觉响应:

responseBuilder
   .add(“This is the first simple response for a basic card.”)
   .add(new BasicCard()
       .setTitle(“Title: This is a title”)
       .setSubtitle(“This is a subtitle”)
       .setFormattedText(text)
       .setImage(new Image()
       .setUrl(IMG_URL)
       .setAccessibilityText(“Image alt text”))
       .setButtons(buttons))
   .addSuggestions(SUGGESTIONS);


客户端库在从意图处理程序返回的 ActionResponse 对象中生成 JSON 响应(见下图)。最后由 Google 助理来处理 JSON,将听觉 / 视觉响应呈现给最终用户。


图 3:对 Basic 卡片的 JSON 和 Google 助理响应


{
"payload": {
 "google": {
  "expectUserResponse": true,
  "richResponse": {
   "items": [{
     "simpleResponse": {
      "textToSpeech": "This is a basic card."
     }
    },
    {
     "basicCard": {
      "title": "Title: this is a title",
      "subtitle": "This is a subtitle",
      "formattedText": "This is a basic card",
      "image": {
       "url": "https://example.com/image.png",
       "accessibilityText": "This is an image"
      },
      "buttons": [{
       "title": "This is a button",
       "openUrlAction": {
        "url": "https://assistant.google.com/"
       }
      }]
     }
    }
   ]
  }
 }
}
}


下图中的响应使用帮助意图请求 Google 助理从用户处获取相关信息:

@ForIntent(“askForPermissions”)
public ActionResponse askForPermission(ActionRequest request) {
   ResponseBuilder responseBuilder = getResponseBuilder(request);
   responseBuilder
       .add(“Placeholder for permissions text”)
       .add(new Permission()
       .setPermissions(new String[]{
           ConstantsKt.PERMISSION_NAME,
           ConstantsKt.PERMISSION_DEVICE_PRECISE_LOCATION
       })
       .setContext(“To provide a better experience”));
   return responseBuilder.build());
}


您可以在 ResponseBuilder 的 API 参考和示例中查看辅助工具方法的更多用例。

注:ResponseBuilder 链接

https://actions-on-google.github.io/actions-on-google-java/com/google/actions/api/response/ResponseBuilder.html)



序列化对 JSON 的响应

客户端库还会按照 JSON 规范处理从 Java 对象到 JSON 的响应序列化,并将其作为 HTTP POST 请求的响应发送。



Kotlin

我们使用 Kotlin 完整构建了此客户端库。我们发现 Kotlin 是一种表达力很强的语言,它有很多功能,让您能够以更安全、更易于维护的代码来实现您的 Action。使用 Spring boot 创建 RESTful 网络服务是一个非常好的资源,可以帮助您完成 Kotlin 和 Spring 入门。



后续步骤

从上述示例可以看出,Java 客户端库提供了一个可以从 Action 汇集响应的直观 API。它在 JSON 协议的基础上提供了一个符合习惯的抽象概念,可以非常轻松地从您的 Action 汇集所有受支持的响应。


非常期待看到您使用 Actions on Google 的 Java 客户端库构建的作品。


下面是详细探索和了解此客户端库的实用链接:

  • GitHub 上的客户端库

    (https://github.com/actions-on-google/actions-on-google-java)

  • 参考文档

    (https://actions-on-google.github.io/actions-on-google-java/)

  • 样板文件

    (https://github.com/actions-on-google/dialogflow-webhook-boilerplate-java)


Java 示例:

  • 对话组件

    (https://github.com/actions-on-google/dialogflow-conversation-components-java)

  • 帮助意图

    (https://github.com/actions-on-google/dialogflow-helper-intents-java)

  • 更新

    (https://github.com/actions-on-google/dialogflow-updates-java)

  • 事务

    (https://github.com/actions-on-google/dialogflow-transactions-java)


如果您在此客户端库中遇到了问题,或者想要请求功能,请在我们的 GitHub 页面提交问题,或在 Stack Overflow 上告知我们。


更多 AI 相关阅读:



    您可能也对以下帖子感兴趣

    文章有问题?点此查看未经处理的缓存