本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用直播 URL 共享直播会话
<a name="stream-urls"></a>

直播网址可让您快速与任何人共享直播会话。收件人在支持的 Web 浏览器中访问您的直播会话，无需集成 AWS 账户 或客户端，并且您可以控制到期、使用和撤销。创建直播网址后，任何访问该网址的人都无需任何凭证即可启动自己的直播会话。直播网址非常适合快速轻松地设置演示、游戏测试、利益相关者评论和访客访问权限。

**重要**  
拥有完整 URL 的任何人都可以启动直播会话，直到直播 URL 过期、达到其使用限制或被撤销。将直播网址视为凭证：仅通过可信渠道共享，选择最短的可行到期时间和使用限制，并在泄露时立即撤销。

## 直播网址的工作原理
<a name="stream-urls-how"></a>

直播网址将直播组（运行直播的容量）和该直播组中的一个应用程序（要运行的内容）联系在一起。当您创建直播网址时，Amazon GameLift Streams 会返回以下格式的直播 URL：

```
https://gameliftstreams.aws.com/su-1AB2C3De4/stream?token=EXAMPLETOKEN
```

该工作流程有四个步骤：
+ **创建。**你需要[CreateStreamUrl](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamUrl.html)一个直播群组和应用程序，设置直播网址的有效时间 (`UrlExpiresAfterMinutes`) 以及可以使用多少次 (`UsageLimit`)。直播会话配置（启动参数、环境变量、会话长度、显示分辨率等）在创建时被冻结到直播 URL 中。
+ **分享。**您可以通过自己的渠道（例如电子邮件、聊天或活动页面）分发直播网址。
+ **激活。**每当用户打开直播网址并开始直播时，Amazon Stre GameLift ams 都会使用一次直播 URL，并使用冻结配置启动全新的直播会话。每次激活都是一个独立的会话；使用相同直播网址的人之间没有共享状态。
+ **结束。**从直播网址启动的会话持续时间很短，不支持重新连接。当会话结束时，其使用量已经计算在内；重新打开直播网址会启动一个新的会话并消耗另一次使用量。

由于直播网址未经身份验证，因此最终用户永远不会看到或需要您的 AWS 证书。该服务根据您在创建时设置的直播位置偏好将每个最终用户路由到附近的位置。Amazon GameLift Streams 会按距离对您的首选直播位置进行重新排序，但不会添加您未包括的地点。

## 终端用户体验
<a name="stream-urls-end-user"></a>

与您共享直播网址的用户无需安装 AWS 账户 任何软件。他们在支持的网络浏览器中打开网址，然后从 Amazon Streams 为您托管的网页进行 GameLift 流式传输。直播使用 WebRTC，其浏览器和设备要求与 Amazon GameLift Streams Web SDK 客户端相同。有关支持的浏览器和最低版本，请参阅[兼容 Amazon GameLift Streams 的设备和浏览器](compatible-devices-browsers.md)。如果最终用户打开 URL 时直播组没有可用容量，则该页面会显示一条消息，提示该直播暂时已满负荷，最终用户可以重试。如果最终用户尝试关闭或重新加载选项卡，则该页面会提示他们进行确认，因为离开该页面会结束会话。

**注意**  
从直播 URL 开始的会话经过调整，可实现简短的单人观看。如果最终用户断开连接或重新加载页面，则会话结束，重新打开直播网址会启动一个新的会话，该会话消耗其他用途。请参阅[与您一开始使用的会话的区别 StartStreamSession](#stream-urls-differences)。

## 先决条件
<a name="stream-urls-prerequisites"></a>

在创建直播网址之前，需要满足以下条件：
+ 处于活动状态且有能力运行会话的直播组。
+ 链接到该直播组的应用程序。
+ 直播网址操作的 IAM 权限。创建直播网址还需要其指向的应用程序的`gameliftstreams:StartStreamSession`权限，因为激活直播网址会启动运行该应用程序的直播会话。参见[创建和管理直播网址](security_iam_id-based-policy-examples.md#create-and-manage-streamurls-iam)策略示例。
+ 如果您传入 IAM 角色`RoleArn`，则还需要该角色的`iam:PassRole`权限。

## 创建直播网址
<a name="stream-urls-creating"></a>

**注意**  
您可以在 Amazon Stre GameLift ams 控制台中 AWS CLI使用或 API 创建直播网址。以下示例使用 AWS CLI.

以下 AWS CLI 示例为直播组中的应用程序创建了直播 URL。直播网址的有效期为两小时，最多可使用五次，它更喜欢`us-west-2`和`us-east-1`位置。

```
aws gameliftstreams create-stream-url \
    --identifier sg-1AB2C3De4 \
    --application-identifier a-9ZY8X7Wv6 \
    --protocol WebRTC \
    --url-expires-after-minutes 120 \
    --usage-limit 5 \
    --locations us-west-2 us-east-1 \
    --description "Preview build - reviewer invites"
```

成功调用将返回直播网址资源，包括其`StreamUrlId`（前缀`su-`）、其 ARN、完全可共享`StreamUrl`资源、计算出的到期时间和初始剩余用量。

```
{
    "StreamUrlId": "su-1AB2C3De4",
    "Arn": "arn:aws:gameliftstreams:us-west-2:111122223333:streamurl/sg-1AB2C3De4/su-1AB2C3De4",
    "StreamUrl": "https://gameliftstreams.aws.com/su-1AB2C3De4/stream?token=EXAMPLETOKEN",
    "Status": "ACTIVE",
    "UsageLimit": 5,
    "RemainingUses": 5,
    "ExpiresAt": "2026-07-31T20:00:00+00:00"
}
```

以下参数为必需参数：


| 参数 | 说明 | 
| --- | --- | 
| Identifier（直播组） | 以容量运行会话的直播组。提供直播群组 ID 或 ARN。 | 
| ApplicationIdentifier | 该流组中要流式传输的应用程序。提供应用程序 ID 或 ARN。 | 
| Protocol | 流协议。WebRTC是唯一支持的值。 | 
| UrlExpiresAfterMinutes | 直播网址自创建之日起的有效时间（以分钟为单位）。最低 1；最大 1,440（24 小时）。在此窗口之后，直播网址变成EXPIRED。 | 
| Locations | 您的首选位置，例如 AWS 区域 代码us-west-2，按优先顺序排列。Amazon GameLift Streams 按最终用户距离对这些地址进行重新排序，但从不添加您未列出的地点。 | 

以下参数为可选参数。您提供的任何会话设置都会在创建时冻结到直播 URL 中，并应用于从该直播 URL 启动的每个会话。


| 参数 | 说明 | 
| --- | --- | 
| UsageLimit | 直播网址可以启动会话多少次。默认 1；最大 50。 | 
| Description | 直播网址的标签，1—80 个字符。 | 
| SessionLengthSeconds | 每个会话的最大时长从直播网址开始。 | 
| AdditionalLaunchArgs | Command-line 启动时传递给应用程序的参数。 | 
| AdditionalEnvironmentVariables | 启动时为应用程序设置的环境变量。 | 
| DisplayConfiguration (Resolution) | 直播显示分辨率，以所需的Width像素Resolution为单位给出。Height每个维度必须介于 320 到 4096 之间。省略时，该服务使用默认分辨率。 | 
| RoleArn | 一个 IAM 角色，应用程序可以在每次会话期间使用其证书。该角色会被冻结到直播网址启动的每个会话中。传递角色需要iam:PassRole权限。 | 
| ClientToken | 一个区分大小写的唯一标识符，它使创建请求呈指数性，因此使用相同的令牌重试不会创建重复的直播网址。 | 

## 监控您的直播网址
<a name="stream-urls-monitoring"></a>

[GetStreamUrl](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamUrl.html)用于检索单个直播网址。使用指定直播群组`--identifier`和直播网址`--stream-url-identifier`（直播网址 ID 或 ARN）。除了直播网址的配置、当前和`RemainingUses`以外`Status`，响应还包括从该网址启动的会话`StreamSessions`列表，因此您可以查看谁在进行流式传输。

```
aws gameliftstreams get-stream-url \
    --identifier sg-1AB2C3De4 \
    --stream-url-identifier su-1AB2C3De4
```

[ListStreamUrls](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_ListStreamUrls.html)用于枚举您账户中的直播网址。您可以按直播群组进行`Status`筛选，并使用`MaxResults`（1—100，默认为 25）和`NextToken`对结果进行分页。

```
aws gameliftstreams list-stream-urls \
    --status ACTIVE \
    --stream-group-identifier sg-1AB2C3De4
```

您还可以在中审核直播网址管理活动 CloudTrail。 CloudTrail 将对`CreateStreamUrl``GetStreamUrl``ListStreamUrls`、和的调用记录`RevokeStreamUrl`为数据事件。最终用户打开直播网址并启动会话不是您的 API 调用之一，也不会被记录为客户 CloudTrail 活动。有关更多信息，请参阅 [使用记录 Amazon GameLift Streams API 调用 AWS CloudTrail](logging-using-cloudtrail.md)。

## 撤销直播网址
<a name="stream-urls-revoking"></a>

当你想阻止某个直播开始任何会话时，例如当预览期结束或可能被无意中共享时，可以撤消该直播网址。

[RevokeStreamUrl](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_RevokeStreamUrl.html)需要`RevocationMode`：


| RevocationMode | 效果 | 
| --- | --- | 
| REVOKE\_URL（默认值） | 直播网址无法再启动新的会话。已经在进行的会话将持续到自行结束为止。 | 
| REVOKE\_AND\_TERMINATE\_SESSIONS | 该直播 URL 无法再启动新的会话，并且当前从其运行的所有会话都将终止。当以这种方式终止正在运行的会话时，最终用户将断开连接并看到一条消息，表明该直播不再可用。 | 

```
aws gameliftstreams revoke-stream-url \
    --identifier sg-1AB2C3De4 \
    --stream-url-identifier su-1AB2C3De4 \
    --revocation-mode REVOKE_AND_TERMINATE_SESSIONS
```

已撤销的直播网址将转换为该`REVOKED`状态，无法重新激活。如果您需要恢复共享，请创建新的直播网址。

当 GameLift 直播所依赖的资源被删除时，Amazon Streams 还会自动撤销该直播网址。删除直播组将撤消该直播组上的所有直播网址，删除该应用程序将撤消引用该应用程序的所有直播网址。在这两种情况下，直播 URL 都会移至`REVOKED`，其状态原因可标识已删除的资源。

**注意**  
移除直播网址所依赖的资源与删除该资源并不相同，也不会自动撤消直播网址。直播网址会保留`ACTIVE`，但每次尝试从中启动会话都会失败。如果您取消了直播网址的应用程序与直播组的链接，或者删除了创建直播网址时使用的所有直播组位置，就会发生这种情况。只有删除直播组或应用程序才会触发自动撤销。

## 直播网址生命周期和状态
<a name="stream-urls-lifecycle"></a>

直播网址是在创建`ACTIVE`时保持这种状态，直到过期、用完或被撤销。离开该状态`ACTIVE`后，它永远不会恢复到原来的状态。


| Status | 含义 | 
| --- | --- | 
| ACTIVE | 直播网址可以启动新的会话。 | 
| EXPIRED | UrlExpiresAfterMinutes窗户已经过去了。 | 
| REVOKED | 直播网址已被显式撤销，RevokeStreamUrl或在删除直播组或应用程序时自动撤销。 | 
| LIMIT\_REACHED | 直播网址已经用完了所有内容UsageLimit。 | 

当直播网址为`REVOKED`，`GetStreamUrl`并且`ListStreamUrls`还会返回一个解释原因的状态原因。


| 状态原因 | 原因 | 
| --- | --- | 
| userRevoked | RevokeStreamUrl使用REVOKE\_URL后已撤销。 | 
| revokedAndTerminatingSessions | 已撤销REVOKE\_AND\_TERMINATE\_SESSIONS；正在运行的会话正在终止。 | 
| revokedAndSessionsTerminated | 已撤销REVOKE\_AND\_TERMINATE\_SESSIONS；正在运行的会话已终止。 | 
| streamGroupDeleted | 直播群组已删除。 | 
| applicationDeleted | 引用的应用程序已删除。 | 

## 与您一开始使用的会话的区别 StartStreamSession
<a name="stream-urls-differences"></a>

会话从与您自己启动的会话相同的基础设施上运行的直播网址开始，但它们经过调整以实现简短、无需动手的单人观看。请记住以下区别：
+ **无需重新连接。**如果最终用户断开连接或重新加载页面，则会话结束。
+ **Re-visiting 消耗另一种用途。**因为没有重新连接，所以再次打开直播网址会启动一个全新的会话，并消耗其中的其他用途。`UsageLimit`
+ **没有数据通道。**从直播网址启动的直播不会暴露应用程序数据频道。如果需要，可以使用 Amazon GameLift Streams Web 开发工具包构建自己的客户端。

## 问题排查
<a name="stream-urls-troubleshooting"></a>

Amazon GameLift Streams 故意向最终用户隐瞒直播网址激活失败的具体原因。无论根本原因如何，打开无法启动直播的直播网址的最终用户始终会看到通用的 “未找到” 页面或 “已满负荷” 消息。要诊断真正的原因，请使用`GetStreamUrl`和检查创作者端的直播网址`ListStreamUrls`，检查`Status`和状态原因，并在中查看直播网址 API 活动 CloudTrail。
+ **直播网址显示 “未找到” 或通用错误页面。**`Status`与... 核对`GetStreamUrl`。`EXPIRED``REVOKED`，或者`LIMIT_REACHED`各自解释一个不可启动的直播网址。如果状态为，`ACTIVE`但激活仍然失败，则该直播 URL 所依赖的资源很可能已被删除（未删除）：应用程序已取消与直播组的链接，或者创建直播 URL 时使用的所有直播组位置都已删除。 Re-link 应用程序或恢复位置，或针对有效资源创建新的直播 URL。
+ **最终用户会看到 “满负荷” 消息。**直播组没有足够的能力在最终用户最近的位置放置新会话。每次激活都会启动一个新的会话并消耗容量，例如`StartStreamSession`。增加最小（永不停机）或最大容量，或使用目标空闲（预热）容量使容量在需求之前就绪，尤其是在限时活动中。
+ **当最终用户刷新或离开时，会话结束。**这是预料之中的。 URL-activated会话不会重新连接，每次访问都会启动一个消耗一次使用量的新会话。建议最终用户不要刷新，并将刷新设置得足够`UsageLimit`高，以容忍偶尔重新加载。
+ **最终用户在会话中断开连接并看到 “此体验不再可用”。**每当会话在服务器端结束时，最终用户都会看到此通用消息。串流 URL 的最常见原因是使用撤销它`REVOKE_AND_TERMINATE_SESSIONS`，这会立即结束正在运行的会话，但是如果会话达到其配置的长度限制或以其他方式被服务终止，则会出现相同的消息。这是预期行为。创建新的直播网址以恢复共享。
+ **最终用户无法加载直播或无法启动。**最终用户的浏览器可能不符合流媒体要求。串流需要支持 WebRTC 和 H.264 (AVC) 的浏览器；有关支持的浏览器和最低版本，[兼容 Amazon GameLift Streams 的设备和浏览器](compatible-devices-browsers.md)请参见。常见原因是在应用程序内浏览器视图中打开直播网址，例如在移动设备上的聊天、电子邮件或社交应用程序中点击的链接，这可能会禁用 WebRTC。建议收件人在 Chrome、Edge 或 Safari 等独立浏览器中打开直播网址。
+ **`CreateStreamUrl`退货`ServiceQuotaExceededException`。**该请求将超过活跃数量限制（每个账户 20 个活跃直播网址或每个直播组 5 个）。撤销您不再需要腾出空间的直播网址，并使用按`Status`设置`ListStreamUrls`筛选`ACTIVE`来查看当前的数量。
+ **`CreateStreamUrl`退货`ValidationException`。**输入值超出范围。设置为 1 `UsageLimit` 到 50，设置为 1 `UrlExpiresAfterMinutes` 到 1,440。