websocket.md

# WebSocket

> 仅支付宝云云端支持

很多情况下需要实时进行网络互动，例如游戏、通信、金融交易和其他高吞吐量活动。

WebSocket 是一种协议，可通过单个 TCP 连接在网络客户端与网络服务器之间提供全双工通信通道。WebSocket 协议使用 HTTP 协议在客户端与服务器之间建立连。

云函数WebSocket运行原理为客户端请求WebSocket网关，由WebSocket网关处理连接后转发给指定的云函数，调用云函数内不同的WebSocket事件完成事件触发与执行。

## WebSocket 事件
>
> WebSocket 支持在云函数与云对象中使用。

### connection
>
> 当有客户端进行连接时触发

**云函数实现**

```javascript
exports.onWebsocketConnection = function (event, context) {
    console.log("onWebsocketConnection", event, context)
}
```

**云对象实现**

```javascript
module.exports = {
    _onWebsocketConnection: function (event) {
        console.log("onWebsocketConnection", event)
    }
}
```

**入参参数**

**event**

|参数|类型|说明|
|---|---|---|
|connectionId|`String`|连接ID|
|query|`Object`|请求时的query参数|

**context**

云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)

### message
>
> 接收到客户端消息时触发

**云函数实现**

```javascript
exports.onWebsocketMessage = function (event, context) {
    console.log("onWebsocketMessage", event, context)
}
```

**云对象实现**

```javascript
module.exports = {
    _onWebsocketMessage: function (event) {
        console.log("onWebsocketMessage", event)
    }
}
```

**入参参数**

**event**

|参数|类型|说明|
|---|---|---|
|connectionId|`String`|连接ID|
|payload|`String` `Buffer`|消息内容|

**context**

云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)

### disConnection
>
> 连接断开时触发

**云函数实现**

```javascript
exports.onWebsocketDisConnection = function (event, context) {
    console.log("onWebsocketDisConnection", event, context)
}
```

**云对象实现**

```javascript
module.exports = {
    _onWebsocketDisConnection: function (event) {
        console.log("onWebsocketDisConnection", event)
    }
}
```

**入参参数**

**event**

|参数|类型|说明|
|---|---|---|
|connectionId|`String`|连接ID|

**context**

云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)

### error
>
> 触发其他事件时失败后触发

**云函数实现**

```javascript
exports.onWebsocketError = function (event, context) {
    console.log("onWebsocketError", event, context)
}
```

**云对象实现**

```javascript
module.exports = {
    _onWebsocketError: function (event) {
        console.log("onWebsocketError", event)
    }
}
```

**入参参数**

**event**

|参数|类型|说明|
|---|---|---|
|connectionId|`String`|连接ID|
|errorMessage|`String`|错误信息|

**context**

云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)

## 云函数 uniCloud API

用法：`const ws = uniCloud.webSocketServer()`

返回值: `WebSocketServer`

### WebSocketServer.send@uniCloud.ws.send
>
> 从云函数/云对象中向客户端发送消息

```javascript
const ws = uniCloud.webSocketServer()

await ws.send(connectionId, sendData)
```

**参数说明**

|参数|类型|说明|
|---|---|---|
|connectionId|`String` `Array`|客户端连接ID, 支持批量向客户端发送消息|
|sendData|`String` `Buffer`|发送给客户端的消息内容|

**示例**

```javascript
// 以云函数为例

exports.onWebsocketMessage = async function (event) {
    const { connectionId, payload } = event
    const ws = uniCloud.webSocketServer()

    // 发送给单个客户端
    await ws.send(connectionId, `receive:${payload}`)

    // 发送给多个客户端
    await ws.send([connectionId1, connectionId2, ...], `receive:${payload}`)

    // 发送给客户端对象数据，发送时会自动JSON.stringify为字符串
    await ws.send(connectionId, {
        receive: payload
    })

    // 发送给客户端二进制数据
    await ws.send(connectionId, Buffer.from(`receive:${payload}`))
}

```

### WebSocketServer.close@uniCloud.ws.close
>
> 在云函数/云对象中关闭连接

```javascript
const ws = uniCloud.webSocketServer()

await ws.close(connectionId)
```

**参数说明**

|参数|类型|说明|
|---|---|---|
|connectionId|`String` `Array`|客户端连接ID, 支持批量关闭客户端连接|

**示例**

```javascript
// 以云函数为例

exports.onWebsocketMessage = async function (event) {
    const { connectionId, payload } = event
    const ws = uniCloud.webSocketServer()

    // 关闭单个客户端连接
    await ws.close(connectionId)

    // 批量关闭客户端连接
    await ws.close([connectionId1, connectionId2, ...])
}

```

### WebSocketServer.signedURL@uniCloud.ws.signedURL
>
> 在云函数/云对象中生成WebSocket连接地址

在客户端没有使用 uniCloud SDK 时，可以通过 URL 化在云端生成 WebSocket 连接地址。

```javascript
const ws = uniCloud.webSocketServer()

await ws.signedURL(name, query)
```

**参数说明**

|参数|类型|说明|
|---|---|---|
|name|`String`|WebSocket云函数/云对象名称|
|query|`Object`|建立连接时需要传递的参数, 仅在 `connection` 事件中接收到|

**返回值**

WebSocket 连接地址

**示例**

```javascript
const ws = uniCloud.webSocketServer()

await ws.signedURL("exampleWebSocket", {
    key: "val"
})
```

## 客户端 uniCloud API

> uni-app-x 尚未支持

### uniCloud.connectWebSocket

快速连接 WebSocket 服务

```javascript
uniCloud.connectWebSocket({
    name: "exampleWebSocket",
    query: {}
})
```

**参数说明**

|参数|类型|说明|
|---|---|---|
|name|`String`|WebSocket云函数/云对象名称|
|query|`Object`|建立连接时需要传递的参数, 仅在 `connection` 事件中接收到|

**返回值**

[SocketTask](https://uniapp.dcloud.net.cn/api/request/socket-task.html)

**示例**

```javascript
const exampleWebSocket = uniCloud.connectWebSocket({
    name: "exampleWebSocket",
    query: {
        key: "val"
    }
})

// 连接成功时触发
exampleWebSocket.onOpen(event => {
    console.log("WebSocket:open", event)
})

// 收到数据时触发
exampleWebSocket.onMessage(event => {
    console.log("WebSocket:message", event.data)
})

// 连接被关闭时触发
exampleWebSocket.onClose(event) => {
    console.log("WebSocket:close", event)
})

// 连接因错误而关闭时触发
exampleWebSocket.onError(event => {
    console.log("WebSocket:error", event)
})

```