本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# API 参考
**Topics**
+ [WebSocket 终端节点 APIs](api-endpoint.md)
+ [异步消息接收](async-message-reception-api.md)
# WebSocket 终端节点 APIs
以下是带有 WebRTC 终端节点的 Amazon Kinesis Vide WebSocket o Streams： APIs
**Topics**
+ [ConnectAsMaster](ConnectAsMaster.md)
+ [ConnectAsViewer](ConnectAsViewer.md)
# ConnectAsMaster
以主设备的身份连接到由终端节点指定的信令通道。任何 WebSocket投诉库都可用于连接到从 `GetSignalingChannelEndpoint` API 调用中获得的安全 websocket (WSS) 端点。信令通道的 Amazon 资源名称 (ARN) 必须作为查询字符串参数提供。有单独的终端节点可用于作为主设备和查看器进行连接。如果多个客户端作为主设备连接到特定通道，则最近的请求优先。新的连接元数据将覆盖现有连接元数据。
## 请求
```
"X-Amz-ChannelARN": "string"
```
+ **X-Amz-ChannelARN** - 信令通道的 ARN。
+ 类型：字符串
+ 长度限制：最小长度为 1。长度上限为 1024。
+ 模式：`arn:aws:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+`
+ 是否必需：是
## 响应
200 OK HTTP 状态代码以及一个空正文。
## 错误
+ InvalidArgumentException
指定的参数超出其限制、不受支持或无法使用。有关更多信息，请参阅返回的消息。
HTTP 状态代码：400
+ AccessDeniedException
未授权调用方访问给定的通道或令牌已过期。
HTTP 状态代码：403
+ ResourceNotFoundException
通道不存在。
HTTP 状态代码：404
+ ClientLimitExceededException
当以过高的速率调用 API 时。有关更多信息，请参阅[带有 WebRTC 服务配额的亚马逊 Kinesis Video Streams](kvswebrtc-limits.md)中的[错误重试和指数退缩](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。 AWS
HTTP 状态代码：400
## 局限/限制
如果以过高的速率调用 API，此 API 将在账户级别受到限制。受到限制时返回错误以及 `ClientLimitExceededException`。
## 幂等
如果指定的 clientId 和通道已存在连接，则使用新信息更新连接元数据。
## 重试行为
这被视为新的 API 调用。
## 并发调用
允许并发调用，对于每个调用都会更新连接元数据。
# ConnectAsViewer
以查看器身份连接到由终端节点指定的信令通道。任何 WebSocket兼容的库都可用于连接到从 `GetSignalingChannelEndpoint` API 调用中获得的安全 websocket (WSS) 端点。信令通道的 Amazon 资源名称 (ARN) 和客户端 ID 必须作为查询字符串参数提供。有单独的终端节点可用于作为主设备和查看器进行连接。如果存在与请求指定的 `ClientId` 相同的现有连接，则新连接优先。新信息将覆盖连接元数据。
## 请求
```
"X-Amz-ChannelARN": "string",
"X-Amz-ClientId": "string"
```
+ **X-Amz-ChannelARN** - 信令通道的 ARN。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 1024
+ 模式：`arn:aws:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+`
+ 是否必需：是
+ **X-Amz-ClientId**-客户端的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`^(?!(?i)AWS_.*)[a-zA-Z0-9_.-]`
**注意**
`X-Amz-ClientId`一开始不行`AWS_`。
+ 是否必需：是
## 响应
200 OK HTTP 状态代码以及一个空正文。
## 错误
+ InvalidArgumentException
指定的参数超出其限制、不受支持或无法使用。有关更多信息，请参阅返回的消息。
HTTP 状态代码：400
+ AccessDeniedException
未授权调用方访问给定的通道或令牌已过期。
HTTP 状态代码：403
+ ResourceNotFoundException
通道不存在。
HTTP 状态代码：404
+ ClientLimitExceededException
当以过高的速率调用 API 时，或者连接到通道的查看器数量超过支持的最大数量时。有关更多信息，请参阅[带有 WebRTC 服务配额的亚马逊 Kinesis Video Streams](kvswebrtc-limits.md)中的[错误重试和指数退缩](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。 AWS
HTTP 状态代码：400
## 局限/限制
如果以过高的速率调用该 API，或当连接到该通道的查看器数量超过支持的最大数量时，会在账户级别限制该 API。受到限制时返回错误以及 `ClientLimitExceededException`。
## 幂等
如果指定的 `ClientId` 和通道已存在连接，则使用新信息更新连接元数据。
## 重试行为
这被视为新的 API 调用。
## 并发调用
允许并发调用，对于每个调用都会更新连接元数据。
# 异步消息接收
所有响应消息都作为事件异步传递给接收方（例如，SDP 提议或 SDP 应答传递）。以下是事件消息结构。
## 事件
```
{
"senderClientId": "string",
"messageType": "string",
"messagePayload": "string",
"statusResponse": {
"correlationId": "string",
"errorType": "string",
"statusCode": "string",
"description": "string"
}
}
```
+ **senderClientId**-发件人客户端的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
+ **messageType** - -事件的类型。
+ 类型：ENUM
+ 有效类型：`SDP_OFFER`、`SDP_ANSWER`、`ICE_CANDIDATE`、`GO_AWAY`、`RECONNECT_ICE_SERVER`、`STATUS_RESPONSE`
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **messagePayload** - 以 base-64 编码的消息内容。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 10K。
+ 必需：否
+ **correlationId** - 状态所指的消息的唯一标识符。这是客户端消息（例如，SDP 提议、SDP 应答或 ICE 候选项）中提供的相同 correlationId。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **errorType** - 用于唯一标识错误的名称。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
+ **statusCode** - 与响应的性质相对应的 HTTP 状态代码。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
+ **description** - 解释状态的字符串描述。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 1K。
+ 必需：否
# SendSdpOffer
将提议发送给目标接收方。前提条件是客户端必须已经连接到从 `GetSignalingChannelEndpoint` API 获取的 WebSocket 端点。
如果发送方类型是查看器，则它会将提议发送给主设备。此外，没有必要指定 `RecipientClientId`，并将忽略为 `RecipientClientId` 指定的任何值。如果发送方类型为主设备，提议将发送到由 `RecipientClientId` 指定的目标查看器。在这种情况下，`RecipientClientId` 是必需的输入。
允许主设备客户端应用程序向任何查看器发送提议，而只允许查看器客户端应用程序将提议发送到主设备客户端应用程序。如果查看器客户端应用程序尝试向其他查看器客户端应用程序发送提议，则不会接受该请求。如果同一客户端的未完成提议尚未交付，则该提议将被新提议覆盖。
## 请求
```
{
"action": "SDP_OFFER",
"recipientClientId": "string",
"messagePayload": "string",
"correlationId": "string"
}
```
+ **action** - 正在发送的消息的类型。
+ 类型：ENUM
+ 有效值：`SDP_OFFER`、`SDP_ANSWER`、`ICE_CANDIDATE`
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **recipientClientId**-收件人的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **messagePayload** - 以 base-64 编码的消息内容。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 10K。
+ 是否必需：是
+ **correlationId** - 消息的唯一标识符。此参数为可选参数。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
## 响应
如果信令后端成功接收消息，则不会返回任何响应。如果服务遇到错误，并且在请求中指定了 `correlationId`，则错误详细信息将作为 `STATUS_RESPONSE` 消息返回。有关更多信息，请参阅 [异步消息接收](async-message-reception-api.md)。
## 错误
+ InvalidArgumentException
指定的参数超出其限制、不受支持或无法使用。有关更多信息，请参阅返回的消息。
HTTP 状态代码：400
+ ClientLimitExceededException
当以过高的速率调用 API 时。有关更多信息，请参阅[带有 WebRTC 服务配额的亚马逊 Kinesis Video Streams](kvswebrtc-limits.md)中的[错误重试和指数退缩](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。 AWS
HTTP 状态代码：400
## 局限/限制
如果以过高的速率调用 API，此 API 将在账户级别受到限制。受到限制时返回错误以及 `ClientLimitExceededException`。
## 幂等
此 API 不是幂等的。
## 重试行为
这被视为新的 API 调用。
## 并发调用
允许并发调用。每次调用发送一次提议。
# SendSdpAnswer
将应答发送给目标接收方。前提条件是客户端必须已经连接到从 `GetSignalingChannelEndpoint` API 获取的 WebSocket 端点。
如果发送方类型是查看器，则它会将应答发送给主设备。此外，没有必要指定 `RecipientClientId`，并将忽略为 `RecipientClientId` 指定的任何值。如果发送方类型为主设备，应答将发送到由 `RecipientClientId` 指定的目标查看器。在这种情况下，`RecipientClientId` 是必需的输入。
允许主设备客户端应用程序向任何查看器发送应答，而只允许查看器客户端应用程序将应答发送到主设备客户端应用程序。如果查看器客户端应用程序尝试向其他查看器客户端应用程序发送应答，则不会接受该请求。如果同一客户端的未完成应答尚未交付，则该应答将被新应答覆盖。
## 请求
```
{
"action": "SDP_ANSWER",
"recipientClientId": "string",
"messagePayload": "string",
"correlationId": "string"
}
```
+ **action** - 正在发送的消息的类型。
+ 类型：ENUM
+ 有效值：`SDP_OFFER`、`SDP_ANSWER`、`ICE_CANDIDATE`
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **recipientClientId**-收件人的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **messagePayload** - 以 base-64 编码的消息内容。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 10K。
+ 是否必需：是
+ **correlationId** - 消息的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
## 响应
如果信令后端成功接收消息，则不会返回任何响应。如果服务遇到错误，并且在请求中指定了 `correlationId`，则错误详细信息将作为 `STATUS_RESPONSE` 消息返回。有关更多信息，请参阅 [异步消息接收](async-message-reception-api.md)。
## 错误
+ InvalidArgumentException
指定的参数超出其限制、不受支持或无法使用。有关更多信息，请参阅返回的消息。
HTTP 状态代码：400
+ ClientLimitExceededException
当以过高的速率调用 API 时返回。有关更多信息，请参阅[带有 WebRTC 服务配额的亚马逊 Kinesis Video Streams](kvswebrtc-limits.md)中的[错误重试和指数退缩](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。 AWS
HTTP 状态代码：400
## 局限/限制
如果以过高的速率调用 API，此 API 将在账户级别受到限制。使用 `ClientLimitExceededException` 进行限制时返回错误。
## 幂等
此 API 不是幂等的。
## 重试行为
这被视为新的 API 调用。
## 并发调用
允许并发调用。每次调用发送一次提议。
# SendIceCandidate
将 ICE 候选项发送给目标接收方。前提条件是客户端必须已经连接到从 `GetSignalingChannelEndpoint` API 获取的 WebSocket 端点。
如果发送者类型是查看器，则它会将 ICE 候选项发送给主设备。此外，没有必要指定 `RecipientClientId`，并将忽略为 `RecipientClientId` 指定的任何值。如果发送方类型为主设备， ICE 候选项将发送到由 `RecipientClientId` 指定的目标。在这种情况下， `RecipientClientId` 是必需的输入。
允许主设备客户端应用程序向任何查看器发送 ICE 候选项，而只允许查看器客户端应用程序将 ICE 候选项发送到主设备客户端应用程序。如果查看器客户端应用程序尝试向其他查看器客户端应用程序发送 ICE 候选项，则不会接受该请求。
## 请求
```
{
"action": "ICE_CANDIDATE",
"recipientClientId": "string",
"messagePayload": "string",
"correlationId": "string"
}
```
+ **action** - 正在发送的消息的类型。
+ 类型：ENUM
+ 有效值：`SDP_OFFER`、`SDP_ANSWER`、`ICE_CANDIDATE`
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 是否必需：是
+ **recipientClientId**-收件人的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
+ **messagePayload** - 以 base-64 编码的消息内容。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 10K。
+ 是否必需：是
+ **correlationId** - 消息的唯一标识符。
+ 类型：字符串
+ 长度限制：最小长度为 1。最大长度为 256。
+ 模式：`[a-zA-Z0-9_.-]+`
+ 必需：否
## 响应
如果信令后端成功接收消息，则不会返回任何响应。如果服务遇到错误，并且在请求中指定了 `correlationId`，则错误详细信息将作为 `STATUS_RESPONSE` 消息返回。有关更多信息，请参阅 [异步消息接收](async-message-reception-api.md)。
## 错误
+ InvalidArgumentException
指定的参数超出其限制、不受支持或无法使用。有关更多信息，请参阅返回的消息。
HTTP 状态代码：400
+ ClientLimitExceededException
当以过高的速率调用 API 时。有关更多信息，请参阅[带有 WebRTC 服务配额的亚马逊 Kinesis Video Streams](kvswebrtc-limits.md)中的[错误重试和指数退缩](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。 AWS
HTTP 状态代码：400
## 局限/限制
如果以过高的速率调用 API，此 API 将在账户级别受到限制。受到限制时返回错误以及 `ClientLimitExceededException`。
## 幂等
此 API 不是幂等的。
## 重试行为
这被视为新的 API 调用。
## 并发调用
允许并发调用。每次调用发送一次提议。
# Disconnect
客户端可以随时关闭连接。 WebSocket兼容的库支持关闭功能。关闭连接后，服务会将客户端标记为针对特定信令通道处于脱机状态，并且不会尝试传递任何消息。同样的行为也适用于空闲连接超时的情况。
该服务还会向客户端发送断开连接指示，例如，在部署或服务器维护期间。以下是定义的指示消息：
+ **GO\$1AWAY**：此消息用于发起连接关闭。它使客户端能够正常处理之前的消息、断开连接，并根据需要重新连接到信令通道。
+ **RECONNECT\$1ICE\$1SERVER**：此消息用于发起中继连接关闭，并使客户端能够正常断开连接，获取新的 ICE 服务器配置，并在需要时重新连接到中继服务器。