> ## 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.

# 使用共享组数据

> 将 PlayFab 共享组数据与 CloudScript 结合使用，以存储回合制游戏状态、小型队伍数据，并为组成员管理读/写权限。

共享组数据（Shared Group Data）是一种便捷方式，可让玩家与一小组严格受限的其他玩家共享部分信息。

<Note>
  共享组数据最初被设计为在大多数情况下由服务器权威驱动，之前的建议是*不要*将玩家直接添加到共享组数据中，因为这会赋予他们读/写权限（从而允许作弊）。然而，我们新的 [API 访问策略](/services/playfab/api-references/api-access-policy)相比原始设计，在功能和安全性方面允许更大的差异。更多详细信息可在本文档的高级部分中找到。
</Note>

<Warning>
  共享组数据最多不应用于超过十几个左右玩家的组。一个问题是，过多玩家同时尝试读取相同的数据会导致读取延迟（与专为许多玩家同时读取而设计的数据（如游戏数据）不同，共享组数据不会*分片*或*缓存*）。此外，应特别注意防止玩家覆盖彼此的数据。如果多个玩家同时尝试写入同一 Key，只有其中一次写入会“获胜”，从而导致其他用户数据丢失。
</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({});
}
```

从宏观上讲，您可以使用共享组数据来实现队伍/团队副本或其他半永久的玩家分组，只要组的规模相对较小，如前所述。

尽管目前没有严格强制的限制，但不支持在包含许多玩家的情况下使用，在极端情况下，可能会对该游戏功能进行限流，以防止影响到服务中的其他人。

### 关键限制

* **共享组数据**：
  * 仅包含简单的键/值对数据（字符串）。若要作为任何其他数据类型（例如库存物品、统计信息、虚拟货币等）使用，游戏必须提供任何必要的转换。
  * 既不*分片*也不*缓存*，因此当多个玩家同时访问时无法及时响应。使用它的功能应针对少量玩家组进行设计，并且不允许同时写入。

### 客户端权限相关注意事项

组内没有角色/等级系统，这意味着组中的任何成员在组内都拥有绝对的权威（没有定义的领导者）。

坦率地说，这意味着除非您通过我们的 [API 访问策略](/services/playfab/api-references/api-access-policy)禁用客户端的共享组数据方法，否则客户端将拥有*对数据的完全控制*，这可能会导致数据被利用。

最佳做法是*不*将共享组数据用于影响游戏玩法的数据，或者在客户端 API 中禁用共享组数据方法。


## Related topics

- [配置文件写入计量 API 说明](/zh-CN/services/playfab/pricing/meters/profile-writes.md)
- [配置文件读取计量 API 说明](/zh-CN/services/playfab/pricing/meters/profile-reads.md)
- [chat_user_local::set_microphone_muted](/zh-CN/reference/chat/gamechat2/classes/chat_user/chat_user_local/methods/chat_user_local_set_microphone_muted.md)
- [PlayFab Party 发行说明](/zh-CN/services/playfab/multiplayer/networking/release-notes.md)
- [使用 Azure Functions 的 PlayFab CloudScript 上下文模型](/zh-CN/services/playfab/live-service-management/service-gateway/automation/cloudscript-af/CloudScript-af-context.md)