> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用共用群組資料

> 搭配 CloudScript 使用 PlayFab 共用群組資料來儲存回合制遊戲狀態、小型隊伍資料，並管理群組成員的讀取/寫入權限。

共用群組資料是一種簡單的方式，可讓玩家與受到嚴格限制的其他玩家清單共用部分資訊。

<Note>
  共用群組資料最初的設計是在大多數情況下由伺服器權威驅動，先前的建議是*不要*將玩家直接新增至共用群組資料，因為這會授予他們讀取/寫入權限 (可能導致作弊)。不過，我們新的 [API 存取原則](/zh-TW/services/playfab/api-references/api-access-policy)相較於原始設計，在功能和安全性方面提供了更大的彈性。如需更多詳細資料，請參閱本文件的進階章節。
</Note>

<Warning>
  共用群組資料最多只應由約十幾位玩家以內的群組使用。其中一個問題是，太多玩家同時嘗試讀取相同資料會導致讀取資料時發生延遲 (共用群組資料不像遊戲資料這類設計為供許多玩家同時讀取的資料那樣經過*分區*或*快取*)。此外，應特別小心防止玩家覆寫彼此的資料。當多位玩家同時嘗試寫入相同的索引鍵時，只有其中一個寫入會「勝出」，導致其他使用者的資料遺失。
</Warning>

## 範例：回合制多人非同步遊戲

共用群組資料最初、也仍是最佳的使用案例，最適合描述為儲存線上桌遊的狀態。玩家依照明確的回合順序，輪流透過 CloudScript 修改資料。

玩家可以登出並稍後繼續遊戲，其遊戲狀態會儲存在雲端。

下列 CloudScript 範例是任何常見桌遊的回合制結構。桌遊本身以虛擬程式碼作為虛設常式。

### 假設

代表遊戲的共用群組資料已經啟動，且其成員資格已經定義。

```javascript theme={null}
// CloudScript/Javascript
const MY_GAME_GROUP_KEYS: Array<string> = ["gameState", "currentPlayerTurn"];
interface PlayerTurnArgs {
    sharedGroupId: string;
    nextPlayerTurn: string;
    turnData: any;
}
handlers.TakePlayerTurn = function (args: PlayerTurnArgs) {
    var getRequest: PlayFabServerModels.GetSharedGroupDataRequest = { SharedGroupId: args.sharedGroupId, GetMembers: true, Keys: MY_GAME_GROUP_KEYS };
    var gameData: PlayFabServerModels.GetSharedGroupDataResult = server.GetSharedGroupData(getRequest);
    CheckValidPlayer(currentPlayerId, args.sharedGroupId, gameData.Members, gameData.Data["currentPlayerTurn"].Value, args.nextPlayerTurn);
    var newGameStateJson = UpdateGameState(args.turnData, gameData.Data["gameState"].Value);
    var updateRequest: PlayFabServerModels.UpdateSharedGroupDataRequest = {
        SharedGroupId: args.sharedGroupId,
        Data: {
            "gameState": newGameStateJson,
            "currentPlayerTurn": args.nextPlayerTurn
        }
    };
    server.UpdateSharedGroupData(updateRequest);
}
function CheckValidPlayer(playFabId: string, sharedGroupId: string, members: Array<string>, currentPlayerTurn: string, nextPlayerTurn: string): void {
    var validCurPlayer = false;
    var validNextPlayer = false;
    for (var m = 0; m < members.length; m++) {
        if (members[m] === playFabId)
            validCurPlayer = true;
        if (members[m] === nextPlayerTurn)
            validNextPlayer = true;
    }
    if (!validCurPlayer || !validNextPlayer) // Take extreme action against a player trying to cheat
    {
        server.BanUsers({ Bans: [{ PlayFabId: playFabId, Reason: "Trying to play a game you don't belong to: " + sharedGroupId }] });
        throw "You have been banned";
    }

    if (playFabId !== currentPlayerTurn)
        // May wish to additionally implement a spam-counter here and potentially take more extreme action for high-spam count
        throw "Not your turn";
}
function UpdateGameState(turnData: any, currentState: string): string {
    // PSEUDO-CODE-STUB: Update the turn-based game state according to the rules of this game
    return JSON.stringify({});
}
```

概括來說，只要群組規模如上所述相對較小，您就可以使用共用群組資料來實作隊伍/突襲，或其他半永久性的玩家群組。

雖然目前沒有嚴格強制的限制，但不支援大量玩家使用，在極端情況下，可能會對遊戲功能進行節流，以避免影響服務中的其他使用者。

### 主要限制

* **共用群組資料**：
  * 僅包含簡單的索引鍵/值組資料 (字串)。若要作為任何其他資料類型使用 (例如詳細目錄項目、Statistics、虛擬貨幣等)，遊戲必須提供任何必要的轉換。
  * 既未經過*分區*也未經過*快取*，因此在多位玩家同時存取時不會有良好的回應。使用它的功能應以小型玩家群組為考量來設計，且不應允許同時寫入。

### 用戶端權限考量

群組內沒有角色/等級系統，這表示群組中的任何成員在群組內都擁有絕對權限 (沒有定義的領導者)。

坦白說，這表示除非您使用我們的 [API 存取原則](/zh-TW/services/playfab/api-references/api-access-policy)停用用戶端共用群組資料方法，否則用戶端將*完全控制資料*，這可能導致資料遭到濫用。

最佳做法是*不要*將共用群組資料用於會影響遊戲玩法的資料，或是在用戶端 API 中停用共用群組資料方法。


## Related topics

- [設定檔寫入計量 API 描述](/zh-TW/services/playfab/pricing/meters/profile-writes.md)
- [設定檔讀取計量 API 描述](/zh-TW/services/playfab/pricing/meters/profile-reads.md)
- [取得共用群組資料](/zh-TW/services/playfab/api-references/rest/server/shared-group-data/get-shared-group-data.md)
- [更新共用群組資料](/zh-TW/services/playfab/api-references/rest/client/shared-group-data/update-shared-group-data.md)
- [PlayFab Server API](/zh-TW/services/playfab/api-references/rest/server/overview.md)