Specifying attributes with your tickets

규칙은 플레이어가 지정한 특성을 기반으로 어떤 티켓이 매치될지 결정합니다. 이러한 특성은 두 가지 방법 중 하나로 지정할 수 있습니다.

티켓 생성 요청 내에서
플레이어의 엔터티 내에서

이 자습서는 해당 특성을 지정하는 방법을 설명합니다.

티켓 생성 요청 내에서 지정

특성 유형이 “User”로 구성된 규칙의 경우, 특성은 CreateMatchmakingTicket 요청 내에서 플레이어 엔터티와 함께 attributes DataObject 내부에 지정됩니다.

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을 가져올 attribute 경로와 소스가 포함되어 있습니다.

"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
        }
    ]
}

규칙은 JSON Path를 사용하여 DataObject 내부를 탐색할 수 있습니다. Path 필드를 “nestExample.exp”로 바꾸면 위에서 생성된 티켓에 대해 규칙이 값 1500을 사용하게 됩니다.

플레이어 엔터티를 통해 지정

특성 유형이 “Player Entity”인 규칙의 경우, 특성은 SetObjects API에 대한 별도 호출을 통해 지정됩니다. 이렇게 하면 타이틀이 각 티켓 생성 호출에서 특성을 지정할 필요 없이 사용자별로 데이터를 저장할 수 있습니다. 이는 사용자에 대해 지속되는 값이나 사용자가 제출하는 것을 신뢰할 수 없는 값에 더 적합할 수 있습니다. SetObjects 호출의 예는 아래에 나와 있습니다.

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"
    }
}

다음 구성을 가진 큐는 이 플레이어로 티켓이 생성될 때 DifferenceRule 규칙에서 사용할 값 16.0을 검색합니다.

Path 필드에서 루트 다음의 첫 번째 항목은 ObjectName이며, 이를 통해 참조할 저장된 객체를 선택할 수 있습니다.

"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 규칙은 지정된 스키마를 가진 지연 시간(latency) 측정값 배열을 필요로 합니다. 다음 예시는 region selection 규칙에 대해 예상되는 특성 형식이며, 비교를 위해 CreateMatchmakingTicket 요청 예시에서 사용된 두 가지 특성과 함께 표시됩니다.

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 필드를 사용하는 규칙의 예가 아래 큐에 포함되어 있습니다.

"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
        }
    ]
}

서버 할당이 활성화된 큐에 대해 region selection 규칙을 사용할 때, 해당 지역은 유효한 Azure Region이어야 합니다. 유효한 Azure Region 목록은 여기에서 확인할 수 있습니다.

XBOX Services

PlayFab

티켓 생성 요청 내에서 지정

플레이어 엔터티를 통해 지정

특수 형식

Region Selection 규칙

​티켓 생성 요청 내에서 지정

​플레이어 엔터티를 통해 지정

​특수 형식

​Region Selection 규칙

티켓 생성 요청 내에서 지정

플레이어 엔터티를 통해 지정

특수 형식

Region Selection 규칙