POST (/handles/query?include=relatedInfo)
관련 세션 정보가 포함된 세션 핸들용 쿼리를 생성합니다.
중요:
이 메서드는 2015 멀티 플레이어에서 사용되며 해당 멀티 플레이어 버전 및 그 이상에서만 적용됩니다. 이는 템플릿 계약 104/105 이상에서 사용하기 위한 것이며 모든 요청마다 X-Xbl-Contract-Version: 104/105 이상의 헤더 요소가 필요합니다.
설명
이 HTTP/REST 메서드는 "include" 쿼리 문자열에 지정된 세션 정보로 핸들 데이터용 쿼리를 생성합니다. 이 쿼리 문자열 값은 향후의 쿼리 옵션들, 예를 들어 "?include=relatedInfo,session"과 같이 쉼표로 구분되는 목록을 지원하기 위해 확장이 가능하도록 설계되어 있습니다. 이 POST 메서드는 Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync로 래핑될 수 있습니다.
이 메서드에서는 요청 본문에 있는 유형 필드를 "activity"로 설정해야 합니다. 응답 본문의 항목들은 Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails의 속성에 직접 매핑됩니다.
URI 매개 변수
쿼리 문자열 매개 변수
다음 표의 쿼리 문자열 매개 변수를 사용하여 쿼리를 수정할 수 있습니다.
| 매개 변수 | Type | Description |
|---|---|---|
| keyword | 문자열 | 키워드(예: "foo")는 세션 또는 템플릿에서 검색되는 경우 검색되어야 합니다. |
| xuid | 64비트 부호 없는 정수 | 세션에 대한 Xbox 사용자 ID(예: "123")입니다. 기본적으로 사용자는 세션에 포함될 때 활성화되어 있어야 합니다. |
| reservations | 부울 값 | 사용자가 예약된 플레이어로 설정되었지만 활성 플레이어로 참가하지 않은 세션을 포함하려면 True입니다. 이 매개 변수는 고유한 세션을 조회하거나 특정 사용자의 세션을 서버 간에 조회할 때만 사용됩니다. |
| inactive | 부울 값 | 사용자가 수락했지만 현재 플레이하지 않는 세션을 포함하려면 True입니다. 사용자가 "준비"되었지만 "활성화"되지 않은 세션을 비활성으로 할 수 있습니다. |
| private | 부울 값 | 개인 세션을 포함하려면 True입니다. 이 매개 변수는 고유한 세션을 조회하거나 특정 사용자의 세션을 서버 간에 조회할 때만 사용됩니다. |
| visibility | 문자열 | 세션의 가시성 상태입니다. 가능한 값은 Microsoft.Xbox.Services.Multiplayer.MultiplayerSessionVisibility에 의해 정의됩니다. 이 매개 변수가 "open"으로 설정된 경우 쿼리는 공개된 세션만 포함해야 합니다. "private"으로 설정된 경우 private 매개 변수를 true로 설정해야 합니다. |
| version | 32비트 부호 있는 정수 | 포함되어야 하는 최대 세션 버전입니다. 예를 들어 값 2는 주요 세션 버전이 2 이하인 세션만 포함되도록 지정합니다. 버전 번호는 요청의 계약 버전인 mod 100 이하여야 합니다. |
| take | 32비트 부호 있는 정수 | 검색할 세션의 최대 수입니다. 이 수는 0~100 사이여야 합니다. |
private 또는 reservations를 true로 설정하려면 세션에 서버 수준 액세스가 필요합니다. 또는 이러한 설정을 사용하려면 호출자의 XUID 클레임이 URI의 XUID 필터와 일치해야 합니다. 그렇지 않으면 이러한 세션이 실제로 존재하는지 여부에 관계없이 HTTP/403 상태 코드가 반환됩니다.
HTTP 상태 코드
이 서비스는 MPSD에 적용할 때 HTTP 상태 코드를 반환합니다.
요청 본문
샘플 요청
사용자의 "즐겨찾기" 소셜 그래프 활동을 모두 가져오려면 POST 본문은 다음과 같은 모습이 됩니다.
{
"type": "activity",
"scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92" // optional filter on scid
"owners": {
"people": {
"moniker": "favorites",
"monikerXuid": "3210"
}
}
}
응답 본문
결과는 각 핸들마다 고유 ID가 임베딩된 여러 핸들 구조들의 배열로 반환됩니다. 구체적인 세션 정보는 relatedInfo 개체에 반환됩니다. 이 URI의 일반 POST 메서드의 경우에는 이 정보가 반환되지 않는다는 점에 유의하세요.
샘플 응답
{
"results": [{
"id": "11111111-ebe0-42da-885f-033860a818f6",
"type": "activity",
"version": 1,
"sessionRef": {
"scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
"templateName": "party",
"name": "e3a836aeac6f4cbe9bcab985494d3175"
},
"titleId": "1234567",
"ownerXuid": "3212",
// Only if ?include=relatedInfo
"relatedInfo": {
"visibility": "open",
"joinRestriction": "followed",
"closed": true,
"maxMembersCount": 8,
"membersCount": 4,
}
},
{
"id": "11111111-ebe0-42da-885f-033860a818f7",
"type": "activity",
"version": 1,
"sessionRef": {
"scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
"templateName": "TitleStorageTestDefault",
"name": "795fcaa7-8377-4281-bd7e-e86c12843632"
},
"titleId": "1234567",
"ownerXuid": "3212",
// Only if ?include=relatedInfo
"relatedInfo": {
"visibility": "open",
"joinRestriction": "followed",
"closed": false,
"maxMembersCount": 8,
"membersCount": 4,
}
}]
}