本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 與串流 URLs 共用串流工作階段
<a name="stream-urls"></a>

串流 URLs 可讓您快速與任何人共用串流工作階段。收件人在支援的 Web 瀏覽器中存取串流工作階段，不需要 AWS 帳戶 或 用戶端整合，而且您可以控制過期、用量和撤銷。建立串流 URL 之後，任何存取此 URL 的人都會啟動自己的串流工作階段，而不需要任何登入資料。串流 URLs非常適合快速輕鬆地設定示範、播放測試、利益相關者檢閱和訪客存取。

**重要**  
擁有完整 URL 的任何人都可以啟動串流工作階段，直到串流 URL 過期、達到其用量限制或遭到撤銷為止。將串流 URL 視為登入資料：僅透過信任的管道共用、偏好最短的可用過期和用量限制，並在發生洩漏時立即撤銷。

## 串流 URLs的運作方式
<a name="stream-urls-how"></a>

串流 URL 會將串流群組 （執行串流的容量） 與該串流群組中的一個應用程式 （要執行的內容） 連結在一起。當您建立串流 URL 時，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) 以取得串流群組和應用程式，設定串流 URL 保持有效 (`UrlExpiresAfterMinutes`) 的時間，以及可以使用多少次 ()`UsageLimit`。串流工作階段組態 – 啟動引數、環境變數、工作階段長度、顯示解析度等 – 會在建立時凍結至串流 URL。
+ **共用。**您可以透過自己的管道分發串流 URL，例如電子郵件、聊天或事件頁面。
+ **啟用。**每次使用者開啟串流 URL 並開始串流時，Amazon GameLift Streams 都會使用串流 URL 的一次使用，並使用凍結組態啟動全新的串流工作階段。每次啟用都是獨立的工作階段；使用相同串流 URL 的人員之間沒有共用狀態。
+ **結束。**從串流 URL 啟動的工作階段是短期的，不支援重新連線。當工作階段結束時，已計算其使用量；重新開啟串流 URL 會啟動新的工作階段並取用另一個使用量。

由於串流 URL 未經驗證，最終使用者永遠不會看到或需要您的 AWS 登入資料。服務會根據您在建立時設定的串流位置偏好設定，將每位最終使用者路由到附近的位置。Amazon GameLift Streams 會依鄰近程度重新排序您偏好的串流位置，但絕不會新增您未包含的位置。

## 最終使用者體驗
<a name="stream-urls-end-user"></a>

與 共用串流 URL 的使用者不需要安裝 AWS 帳戶 或任何軟體。他們會在支援的 Web 瀏覽器中開啟 URL，並從 Amazon GameLift Streams 為您託管的網頁串流。串流使用 WebRTC，並且具有與 Amazon GameLift Streams Web SDK 用戶端相同的瀏覽器和裝置需求。如需支援的瀏覽器和最低版本，請參閱 [Amazon GameLift Streams 相容裝置和瀏覽器](compatible-devices-browsers.md)。如果串流群組在最終使用者開啟 URL 時沒有可用的容量，頁面會顯示串流暫時處於容量的訊息，而最終使用者可以重試。如果最終使用者嘗試關閉或重新載入標籤，頁面會提示他們確認，因為離開頁面會結束工作階段。

**注意**  
從串流 URL 開始的工作階段會針對簡短的單一檢視者播放進行調校。如果最終使用者失去連線或重新載入頁面，工作階段會結束，然後重新開啟串流 URL 會啟動耗用其他用途的新工作階段。請參閱 [與從 StartStreamSession 開始的工作階段的差異](#stream-urls-differences)。

## 先決條件
<a name="stream-urls-prerequisites"></a>

建立串流 URL 之前，您需要下列項目：
+ 作用中且具有執行工作階段容量的串流群組。
+ 連結至該串流群組的應用程式。
+ 串流 URL 動作的 IAM 許可。建立串流 URL 也需要其指向之應用程式的`gameliftstreams:StartStreamSession`許可，因為啟用串流 URL 會啟動執行該應用程式的串流工作階段。請參閱[建立和管理串流 URLs](security_iam_id-based-policy-examples.md#create-and-manage-streamurls-iam)政策範例。
+ 如果您在 中傳遞 IAM 角色`RoleArn`，您也需要該角色的`iam:PassRole`許可。

## 建立串流 URL
<a name="stream-urls-creating"></a>

**注意**  
您可以在 Amazon GameLift Streams 主控台、 AWS CLI或 API 中建立串流 URL。下列範例使用 AWS CLI。

下列 AWS CLI 範例會為串流群組中的應用程式建立串流 URL。串流 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"
```

成功呼叫會傳回串流 URL 資源，包括其 `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 | 串流 URL 從建立起的有效期限，以分鐘為單位。下限為 1；上限為 1，440 (24 小時）。在此視窗之後，串流 URL 會變成 EXPIRED。 | 
| Locations | 您偏好的位置，例如 等 AWS 區域 代碼us-west-2，依優先順序排列。Amazon GameLift Streams 會依最終使用者鄰近性重新排序這些項目，但絕不會新增您未列出的位置。 | 

下列是選用參數。您提供的任何工作階段設定都會在建立時凍結至串流 URL，並套用至從串流 URL 啟動的每個工作階段。


| 參數 | 說明 | 
| --- | --- | 
| UsageLimit | 串流 URL 可以啟動工作階段的次數。預設 1；最多 50 個。 | 
| Description | 串流 URL 的標籤，1-80 個字元。 | 
| SessionLengthSeconds | 從串流 URL 啟動的每個工作階段的長度上限。 | 
| AdditionalLaunchArgs | 啟動時傳遞給應用程式的命令列引數。 | 
| AdditionalEnvironmentVariables | 啟動時為應用程式設定的環境變數。 | 
| DisplayConfiguration (Resolution) | 串流顯示解析度，以Resolution必要的 Width 和像素Height表示。每個維度必須介於 320 到 4096 之間。省略時，服務會使用預設解析度。 | 
| RoleArn | IAM 角色，其登入資料可供應用程式在每個工作階段期間使用。角色會凍結到串流 URL 開始的每個工作階段中。傳遞角色需要其iam:PassRole許可。 | 
| ClientToken | 唯一且區分大小寫的識別符，可讓建立請求具有等冪性，因此具有相同字符的重試不會建立重複的串流 URL。 | 

## 監控您的串流 URLs
<a name="stream-urls-monitoring"></a>

使用 [GetStreamUrl](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamUrl.html) 擷取單一串流 URL。使用 指定串流群組，`--identifier`並使用 指定串流 URL `--stream-url-identifier`（串流 URL ID 或 ARN)。除了串流 URL 的組態、目前 `Status`和 `RemainingUses`之外，回應還包含從中啟動的工作階段`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) 列舉您帳戶中URLs。您可以依串流群組`Status`和 進行篩選，並使用 `MaxResults`(1–100，預設 25) 和 分頁結果`NextToken`。

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

您也可以在 CloudTrail 中稽核串流 URL 管理活動。CloudTrail 會將對 `CreateStreamUrl`、`ListStreamUrls`、 `GetStreamUrl`和 的呼叫記錄`RevokeStreamUrl`為資料事件。開啟串流 URL 並啟動工作階段的最終使用者不是您的 API 呼叫之一，也不會記錄為客戶 CloudTrail 活動。如需詳細資訊，請參閱[使用 記錄 Amazon GameLift Streams API 呼叫 AWS CloudTrail](logging-using-cloudtrail.md)。

## 撤銷串流 URL
<a name="stream-urls-revoking"></a>

當您想要停止串流 URL 以啟動任何其他工作階段時，例如預覽期間結束或可能無意間共用。

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


| RevocationMode | Effect | 
| --- | --- | 
| REVOKE\_URL (default) | 串流 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
```

撤銷的串流 URL 會轉換為 `REVOKED` 狀態，且無法重新啟用。如果您需要繼續共用，請建立新的串流 URL。

刪除相依的資源時，Amazon GameLift Streams 也會自動撤銷串流 URL。刪除串流群組會撤銷該串流群組上的所有串流 URLs，而刪除應用程式會撤銷參考該應用程式的所有串流 URLs。在這兩種情況下，串流 URL 會移至 ，`REVOKED`並具有識別已刪除資源的狀態原因。

**注意**  
移除串流 URL 所依賴的資源與刪除資源不同，而且不會自動撤銷串流 URL。串流 URL 會保留 `ACTIVE`，但每次嘗試從中啟動工作階段都會失敗。如果您將串流 URL 的應用程式從串流群組取消連結，或是移除建立串流 URL 的所有串流群組位置，就會發生這種情況。僅刪除串流群組或應用程式會觸發自動撤銷。

## 串流 URL 生命週期和狀態
<a name="stream-urls-lifecycle"></a>

串流 URL 會在建立`ACTIVE`時以這種方式保留，直到過期、用盡或遭到撤銷為止。離開該狀態`ACTIVE`後，它永遠不會返回 。


| 狀態 | 意義 | 
| --- | --- | 
| ACTIVE | 串流 URL 可以啟動新的工作階段。 | 
| EXPIRED | UrlExpiresAfterMinutes 視窗已過。 | 
| REVOKED | 串流 URL 已遭撤銷，可能是使用 明確撤銷，RevokeStreamUrl或在刪除其串流群組或應用程式時自動撤銷。 | 
| LIMIT\_REACHED | 串流 URL 已使用其所有 UsageLimit。 | 

當串流 URL 為 `GetStreamUrl`時`REVOKED`， `ListStreamUrls` 也會傳回說明原因的狀態原因。


| 狀態原因 | 原因 | 
| --- | --- | 
| userRevoked | RevokeStreamUrl 使用 以 撤銷REVOKE\_URL。 | 
| revokedAndTerminatingSessions | 使用 撤銷REVOKE\_AND\_TERMINATE\_SESSIONS；正在終止執行的工作階段。 | 
| revokedAndSessionsTerminated | 使用 撤銷REVOKE\_AND\_TERMINATE\_SESSIONS；執行中的工作階段已終止。 | 
| streamGroupDeleted | 串流群組已刪除。 | 
| applicationDeleted | 已刪除參考的應用程式。 | 

## 與從 StartStreamSession 開始的工作階段的差異
<a name="stream-urls-differences"></a>

從串流 URL 開始的工作階段會與您開始的工作階段在相同的基礎設施上執行，但會針對簡短的切換、單一檢視器播放進行調校。請謹記這些差異：
+ **不重新連線。**如果最終使用者失去連線或重新載入頁面，工作階段會結束。
+ **重新瀏覽 會使用其他用途。**由於沒有重新連線，再次開啟串流 URL 會啟動全新的工作階段，並從其 取用另一個用途`UsageLimit`。
+ **沒有資料通道。**從串流 URL 啟動的串流不會公開應用程式資料通道。如果需要，請使用 Amazon GameLift Streams Web SDK 建置自己的用戶端。

## 疑難排解
<a name="stream-urls-troubleshooting"></a>

Amazon GameLift Streams 刻意從最終使用者隱藏串流 URL 啟用失敗的特定原因。開啟無法啟動串流的串流 URL 的最終使用者一律會看到一般「找不到」頁面或「容量」訊息，無論根本原因為何。若要診斷實際原因，請使用 `GetStreamUrl`和 從建立者端檢查串流 URL`ListStreamUrls`、檢查 `Status`和 狀態原因，並在 CloudTrail 中檢閱串流 URL API 活動。
+ **串流 URL 會顯示「找不到」或一般錯誤頁面。**`Status` 使用 檢查 `GetStreamUrl`。`EXPIRED`、 `REVOKED`或 `LIMIT_REACHED` 會說明不可啟動的串流 URL。如果狀態為 `ACTIVE`，但啟用仍然失敗，則串流 URL 所依賴的資源很可能已移除 （未刪除）：應用程式已從串流群組取消連結，或使用 建立串流 URL 的所有串流群組位置都已移除。重新連結應用程式或還原位置，或針對有效的資源建立新的串流 URL。
+ **最終使用者會看到「容量不足」訊息。**串流群組沒有可用的容量，可將新的工作階段放置在最終使用者最近的位置。每次啟用都會啟動新的工作階段，並使用 之類的容量`StartStreamSession`。增加最小 （一律開啟） 或最大容量，或使用目標閒置 （預先暖機） 容量，讓容量在需求之前保持就緒狀態，特別是針對有時間限制的事件。
+ **工作階段會在最終使用者重新整理或離開時結束。**這是預期的行為。URL 啟用的工作階段不會重新連線，而且每次造訪都會啟動使用的新工作階段。建議最終使用者不要重新整理，並設定`UsageLimit`高到足以容忍偶爾重新載入。
+ **最終使用者在工作階段中中斷連線，並看到「不再提供此體驗」。**每當工作階段結束於伺服器端時，最終使用者都會看到此一般訊息。串流 URL 最常見的原因是使用 將其撤銷`REVOKE_AND_TERMINATE_SESSIONS`，這會立即結束執行中的工作階段，但如果工作階段達到其設定的長度限制或由服務終止，則會顯示相同的訊息。這是預期的行為。建立新的串流 URL 以繼續共用。
+ **串流不會載入或無法為最終使用者啟動。**最終使用者的瀏覽器可能不符合串流需求。串流需要支援 WebRTC 和 H.264 (AVC) 的瀏覽器；如需支援的瀏覽器和最低版本[Amazon GameLift Streams 相容裝置和瀏覽器](compatible-devices-browsers.md)，請參閱 。常見的原因是在應用程式內瀏覽器檢視中開啟串流 URL，例如在行動裝置上的聊天、電子郵件或社交應用程式中點選的連結，這會停用 WebRTC。建議收件人在 Chrome、Edge 或 Safari 等獨立瀏覽器中開啟串流 URL。
+ **`CreateStreamUrl` 傳回 `ServiceQuotaExceededException`。**請求將超過作用中計數限制 （每個帳戶 20 個作用中串流 URLs 或每個串流群組 5 個）。撤銷不再需要釋放空間URLs，並使用依 `Status` 設定為 `ListStreamUrls`篩選的 `ACTIVE` 來查看目前的計數。
+ **`CreateStreamUrl` 傳回 `ValidationException`。**輸入值超出範圍。`UsageLimit` 設定為 1 到 50，`UrlExpiresAfterMinutes`設定為 1 到 1，440。