使用 Amazon AppSync Events 的 WebSocket 发布功能构建实时应用程序

实时功能已成为现代应用程序中必不可少的功能。无论你是在构建协作工具、实时仪表板还是互动游戏，用户在与应用程序交互时都会期待即时和无缝的更新。Amazon AppSync Events 是一项针对无服务器 WebSocket API 的完全托管服务，一直在帮助开发者为其应用添加实时功能，使他们能够大规模构建响应式和引人入胜的体验。

今天，我很高兴地宣布对 Amazon AppSync Events 进行了增强：除了通过 API 的 HTTP 终端节点发布消息外，还能够直接通过 WebSocket 连接发布消息。此更新允许开发人员使用单个 WebSocket 连接来发布和接收事件，从而简化了实时功能的开发并降低了实现复杂性。这对于以前面临为每个消息发布建立新的 HTTP 连接的开销的聊天应用程序尤其有利。开发人员现在拥有更大的灵活性：他们可以通过 HTTP 端点进行发布，例如：用于从后端发布，或者通过 WebSocket 发布，这可能是 Web 和移动应用程序客户端的首选。在这篇文章中，我将介绍新的增强功能，并向你展示如何开始将通过 WebSocket 发布功能集成到应用程序中。

入门

正如我在宣布 Amazon AppSync Events 的帖子中提到的那样，AppSync Events 的入门很简单，现在你可以直接从控制台通过 WebSocket 或 HTTP 进行发布。在 AppSync 控制台中，您可以创建 API 并自动获取default频道命名空间和 API 密钥。在 Pub/Sub 编辑器上，您可以立即试用 API。如下图所示，选择 "发布" 按钮，然后在下拉列表中选择 "WebSocket"。你的活动是通过 WebSocket 发布的。您会收到publish_success一条确认请求的消息。

在 AppSync 的控制台 Pub/Sub 编辑器中通过 WebSocket 发布

消息格式

AppSync 现在支持新的 "发布" WebSocket 操作来发布事件。连接到 WebSocket 后，您的客户端可以开始将事件发布到已配置的频道命名空间中的频道。请注意，在发布频道之前，您无需订阅该频道。要发布事件，您只需创建数据消息，指定唯一标识消息的 ID、发送消息的频道、发送事件的列表（最多 5 个）以及允许请求的授权标头即可。您可以在文档中找到有关授权标头格式的更多信息。事件数组中的每个事件都必须是有效的 JSON 字符串。这是一个例子。

{
  "type": "publish",
  "id": "an-identifier-for-this-request",
  "channel": "/namespace/my/path",
  "events": [ "{ \"msg\": \"Hello World!\" }" ],
  "authorization": {
    "x-api-key": "da2-12345678901234567890123456-example",
   }
}

发布后，您将收到 "publish_success" 响应，其中包含发送的每个事件的详细信息，如果操作不成功，则会收到 "publish_error" 响应。

与您的应用程序集成

在上一篇文章中，我向你展示了如何实现一个使用浏览器的 Web API WebSocket 的简单客户端。我将再次这样做，以便在事件 API WebSocket 端点上进行连接和发布。在此示例中，我将构建一个实时演示聊天应用程序，在该应用程序中，客户端可以通过 WebSocket 即时发送和接收消息。消息发布到/default/messages频道，客户端订阅/default/*以接收默认命名空间中的所有消息。

演示聊天应用程序

我将使用适用于 AppSync Events 的新的亚马逊云科技云开发套件 (CDK) L2 结构来配置和部署 AppSync Events API，其中包含一个名为 "默认" 的单一频道命名空间和一个 API 密钥。了解有关亚马逊云科技 CDK 入门的更多信息。如果需要，使用节点包管理器安装 CDK CLI。

$ npm install -g aws-cdk

我首先初始化一个新的文件夹结构并创建我的 CDK 应用程序。

$ mkdir -p events-app/cdk-events-publish
$ cd events-app/cdk-events-publish
$ cdk init app --language javascript

接下来，我用这个代码更新lib/cdk-events-publish-stack.js文件：

const { Stack, CfnOutput } = require('aws-cdk-lib');
const { EventApi, AppSyncAuthorizationType } = require('aws-cdk-lib/aws-appsync');

class CdkEventsPublishStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);
    const apiKeyProvider = { authorizationType: AppSyncAuthorizationType.API_KEY };

    // create an API called `my-event-api` that uses API Key authorization
    const api = new EventApi(this, 'api', {
      apiName: 'my-event-api',
      authorizationConfig: { authProviders: [apiKeyProvider] }
    });

    // add a channel namespace called `default`
    api.addChannelNamespace('default');

    // output configuration properties
    new CfnOutput(this, 'apiKey', { value: api.apiKeys['Default'].attrApiKey });
    new CfnOutput(this, 'httpDomain', { value: api.httpDns });
    new CfnOutput(this, 'realtimeDomain', { value: api.realtimeDns });
  }
}

module.exports = { CdkEventsPublishStack }

然后我部署堆栈并将输出保存到 JSON 文件中。

$ npm run cdk deploy -- -O output.json

我得到的输出如下所示：

Outputs:
CdkStack.apiKey = da2-12345678901234567890123456-example
CdkStack.httpDomain = a12345678901234567890123456.appsync-api.us-east-2.amazonaws.com
CdkStack.realtimeDomain = a12345678901234567890123456.appsync-realtime-api.us-east-2.amazonaws.com

接下来，我使用 vite（前端构建工具）和 vite 的原始 JavaScript 模板创建 Web 应用程序。在events-app文件夹中，我运行：

$ npm create vite@latest app -- --template vanilla
$ cd app
$ npm install
$ ln -s ../../cdk-events-publish/output.json src

这会创建指向该output.json文件的链接，我可以在应用程序中引用。在新app文件夹中，我src/main.js用下面的代码替换。请注意，该代码使用中的 CDK 输出。output.json

import './style.css'
import output from './output.json'

// use the output from the CDK stack deployment
const HTTP_DOMAIN = output.CdkEventsPublishStack.httpDomain
const REALTIME_DOMAIN = output.CdkEventsPublishStack.realtimeDomain
const API_KEY = output.CdkEventsPublishStack.apiKey 
     
const authorization = { 'x-api-key': API_KEY, host: HTTP_DOMAIN }

document.querySelector('#app').innerHTML = `
    <style>
      #top{width: calc(100vw - 8rem); max-width: 1280px; background: oklch(0.977 0.013 236.62); margin: 2rem 0; height: calc(100vh - 8rem); box-shadow: inset 0 0 20px rgba(0,0,0,0.1); position: relative; margin-inline: auto;}
      #container{display: flex;flex-direction: column;height: calc(100% - 6.5rem);}
      h2{color: oklch(0.3 0.013 236.62); margin-bottom: 1.5em; font-size: 1.8rem;}
      #messages{display: flex; flex-direction: column-reverse; gap: 1em; max-height: calc(100vh - 200px); flex: 1; min-height: 0; overflow-y: auto; text-align: left;}
      form{position: absolute; bottom: 2rem; left: 2rem; right: 2rem; padding: 1rem 0;}
      input{width: 90%; padding: 0.8em 1.2em; border: 1px solid oklch(0.8 0.013 236.62); border-radius: 25px; font-size: 1rem; outline: none; transition: all 0.2s ease; box-shadow: 0 2px 5px rgba(0,0,0,0.05);}
      .msg{padding: 0 1rem; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;}
    </style>
    <div id="top">
      <div id="container"><h2>Messages</h2><div id="messages"></div></div>
      <form id="form"> <input id="messageInput" name="message" type="text" autocomplete="off" /></form>
    </div>`

// construct the protocol header for the connection
function getAuthProtocol() {
  const header = btoa(JSON.stringify(authorization))
    .replace(/\+/g, '-') // Convert '+' to '-'
    .replace(/\//g, '_') // Convert '/' to '_'
    .replace(/=+$/, '') // Remove padding `=`
  return `header-${header}`
}

const socket = await new Promise((resolve, reject) => {
  const socket = new WebSocket(`wss://${REALTIME_DOMAIN}/event/realtime`, [
    'aws-appsync-event-ws',
    getAuthProtocol(),
  ])
  socket.onopen = () => resolve(socket)
  socket.onclose = (event) => reject(new Error(event.reason))
  socket.onmessage = (_evt) => {
    const data = JSON.parse(_evt.data)
    // if this is a `data` event, add the content to the list of messages
    if (data.type === 'data') {
      const event = JSON.parse(data.event)
      const div = document.createElement('div')
      div.className = 'msg'
      div.innerHTML = `↑ ${event.time} | ↓ ${new Date().toISOString().split('T')[1]} | ${event.message}`
      messages.prepend(div)
    }
  }
})

// subscribe to `/default/*`
socket.send(
  JSON.stringify({
    type: 'subscribe',
    id: crypto.randomUUID(),
    channel: '/default/*',
    authorization,
  }),
)

const form = document.querySelector('#form')
const messageInput = document.querySelector('#messageInput')
const messages = document.querySelector('#messages')

// when the form is submitted, send an event to `/default/messages`
form.addEventListener('submit', (e) => {
  e.preventDefault()
  const message = new FormData(e.currentTarget).get('message')
  messageInput.value = ''
  socket.send(
    JSON.stringify({
      type: 'publish',
      id: crypto.randomUUID(),
      channel: '/default/messages',
      events: [JSON.stringify({ message, time: new Date().toISOString().split('T')[1] })],
      authorization,
    }),
  )
})

现在在app目录中，我启动网络服务器：

$ npm run dev

我可以在多个浏览器上使用提供的地址打开网站来发送和接收消息。

正在清理

完成示例后，我可以删除使用 CDK 部署的资源。

$ cd ../cdk-events-publish
$ npm run cdk destroy

结论

在这篇文章中，我介绍了 Amazon AppSync Events 的新的 "通过 WebSocket 发布" 功能，并展示了如何开始使用该功能。此增强功能提供了多项好处：

使用用于发布和订阅的单一连接简化了实施
减少了聊天应用程序的连接开销
根据您的用例，可以灵活地在 WebSocket 和 HTTP 发布之间进行选择

现在，所有提供 AppSync 的地区都支持通过 WebSocket 进行发布。客户端可以以每个客户端 WebSocket 连接每秒 25 个请求的速度发布请求。您可以继续使用 API 的 HTTP 终端节点以更高的速率进行发布（可调整的默认值为每秒 10,000 个事件）。访问 AppSync 的终端节点和配额页面，了解更多详情。我们很高兴看到你用这项新功能创造了什么。今天就开始试试这篇文章中的示例，或者在现有的 AppSync Events 应用程序中添加 WebSocket 发布功能。要了解有关 AppSync Events 的更多信息，请访问文档。

免费试用 Amazon EC2 T4g 实例