> ## 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 匹配工单,以便队列规则可以评估技能、延迟和其他条件。

规则根据玩家指定的属性决定哪些工单被匹配。这些属性可以通过两种方式指定:

1. 在创建工单请求中
2. 在玩家的实体中

本教程介绍如何指定这些属性。

## 在创建工单请求中指定

对于配置了属性类型 "User" 的规则,属性在 `CreateMatchmakingTicket` 请求中指定,与玩家实体一起位于属性 `DataObject` 内。

```json theme={null}
POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "nestExample": {
                    "exp": 1500
                }
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "SkillRuleQueue"
}
```

以下是一个带有 `DifferenceRule` 的队列配置示例。此规则包含一个属性路径和来源,将拾取上面 `CreateMatchmakingTicket` 请求指定的值 16.0。

```json theme={null}
"MatchmakingQueue": {
    "Name": "SkillRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 3,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "mu",
                "Source": "User"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}
```

<Note>
  规则可以通过 JSON Path 在 `DataObject` 中进行导航。将 Path 字段替换为 "nestExample.exp" 会使规则对上面创建的工单使用值 1500。
</Note>

## 通过玩家实体指定

对于属性类型为 "Player Entity" 的规则,属性通过对 `SetObjects` API 的单独调用来指定。

这允许为用户存储数据,而不需要游戏在每次创建工单调用时都指定。这对于持久保存的用户值或不能信任用户提交的值可能更有意义。以下是此 `SetObjects` 调用的示例。

```json theme={null}
POST https://{{TitleID}}.playfabapi.com/Object/SetObjects
{
    "Objects": [
        {
            "ObjectName": "playerSkill",
            "DataObject": {
                "skillDetail": {
                    "mu": 16.0,
                    "sigma": 2.0
                }
            }
        }
    ],
    "Entity": {
        "Id": "A8140AB9109712B",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
```

当为该玩家创建工单时,具有以下配置的队列将检索值 16.0 以在其 `DifferenceRule` 规则中使用。

<Note>
  在 `Path` 字段中,根之后的第一项是 `ObjectName`,允许你选择要引用的已存储对象。
</Note>

```json theme={null}
"MatchmakingQueue": {
    "Name": "PlayerEntityRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 1,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "$.playerSkill.skillDetail.mu",
                "Source": "PlayerEntity"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}
```

## 特殊格式

大多数规则使用的属性为字符串或数值,并且只是这些值的 JSON 格式。需要传入更复杂属性的规则如下所示。

### Region Selection 规则

Region Selection 规则要求使用指定架构的延迟测量数组。以下示例是 region selection 规则预期的属性格式,并与 `CreateMatchmakingTicket` 请求示例中使用的两个属性一起显示以作比较。

```json theme={null}
POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "Latencies": [
                    {
                        "region": "EastUs",
                        "latency": 150
                    },
                    {
                        "region": "WestUs",
                        "latency": 400
                    }
                ]
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "ServerEnabledQueue"
}
```

在此示例中,`Latencies` 必须匹配规则中 `Path` 字段引用的字段。使用 `Latencies` 字段的规则示例包含在下面的队列中。

```json theme={null}
"MatchmakingQueue": {
    "Name": "ServerEnabledQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": true,
    "BuildId": "88b3e315-829c-4b6d-9872-74f427ad5331",
    "Rules": [
        {
            "Type": "RegionSelectionRule",
            "MaxLatency": 1000,
            "Path": "Latencies",
            "Weight": 1,
            "Name": "RegionRule",
            "SecondsUntilOptional": 60
        }
    ]
}
```

<Note>
  为启用了服务器分配的队列使用 region selection 规则时,区域必须是有效的 Azure Regions。你可以在[此处](/services/playfab/api-references/events/data-types/azureregion)找到有效 Azure Regions 的列表。
</Note>


## Related topics

- [点对点连接的变通方法](/zh-CN/services/playfab/multiplayer/matchmaking/peer-to-peer.md)
- [了解匹配中的规则权重](/zh-CN/services/playfab/multiplayer/matchmaking/rule-weights.md)
- [匹配](/zh-CN/services/playfab/multiplayer/matchmaking/index.md)
- [PlayFabMultiplayer.JoinMatchmakingTicketFromId](/zh-CN/services/playfab/multiplayer/lobby/unity-multiplayer-api-reference/PlayFab.Multiplayer/PlayFabMultiplayer/JoinMatchmakingTicketFromId.md)
- [使用服务器回填工单 - REST API](/zh-CN/services/playfab/multiplayer/matchmaking/backfill-tickets.md)