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

# POST (/handles/query?include=relatedInfo)

> POST (/handles/query?include=relatedInfo)

# POST (/handles/query?include=relatedInfo)

관련 세션 정보를 포함하는 세션 핸들에 대한 쿼리를 만듭니다.

> **중요:**\
> 이 메서드는 2015 멀티플레이어에서 사용되며 해당 멀티플레이어 버전 이상에만 적용됩니다. 템플릿 계약 104/105 이상과 함께 사용하도록 설계되었으며, 모든 요청에 X-Xbl-Contract-Version: 104/105 이상의 헤더 요소가 필요합니다.

* [설명](#ID4ET)
* [URI 매개 변수](#ID4ECB)
* [쿼리 문자열 매개 변수](#ID4EPB)
* [HTTP 상태 코드](#ID4EAF)
* [요청 본문](#ID4EHF)
* [응답 본문](#ID4EZF)

## 설명

이 HTTP/REST 메서드는 "include" 쿼리 문자열에 지정된 세션 정보와 함께 핸들 데이터에 대한 쿼리를 만듭니다. 쿼리 문자열 값은 향후 쿼리 옵션을 지원하도록 확장 가능하게 설계되었으며, 예를 들어 "?include=relatedInfo,session"과 같은 쉼표로 구분된 목록을 지원합니다. POST 메서드는 **Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync**로 래핑될 수 있습니다.

이 메서드의 요청 본문에 있는 type 필드는 "activity"로 설정해야 합니다. 응답 본문의 항목은 **Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails**의 속성과 직접 매핑됩니다.

## URI 매개 변수

## 쿼리 문자열 매개 변수

쿼리는 다음 표의 쿼리 문자열 매개 변수를 사용하여 수정할 수 있습니다.

\| **매개 변수**| **형식**| **설명**|
\| --- | --- | --- | --- |
\| keyword| string| 세션 또는 템플릿을 검색할 때 검색 대상에 포함되어야 하는 키워드(예: "foo")입니다. |
\| xuid| 64비트 부호 없는 정수| 쿼리에 포함할 세션에 대한 XBOX 사용자 ID(예: "123")입니다. 기본적으로 사용자는 세션에 포함되기 위해 활성 상태여야 합니다. |
\| reservations| boolean| 사용자가 예약된 플레이어로 설정되었지만 활성 플레이어가 되기 위해 조인하지 않은 세션을 포함하려면 True입니다. 이 매개 변수는 자신의 세션을 쿼리하거나 서버 대 서버로 특정 사용자의 세션을 쿼리할 때만 사용됩니다. |
\| inactive| boolean| 사용자가 수락했지만 활발히 플레이하지 않은 세션을 포함하려면 True입니다. 사용자가 "ready" 상태이지만 "active" 상태가 아닌 세션은 비활성으로 간주됩니다. |
\| private| boolean| 프라이빗 세션을 포함하려면 True입니다. 이 매개 변수는 자신의 세션을 쿼리하거나 서버 대 서버로 특정 사용자의 세션을 쿼리할 때만 사용됩니다. |
\| visibility| string| 세션의 표시 상태입니다. 가능한 값은 **Microsoft.Xbox.Services.Multiplayer.MultiplayerSessionVisibility**에 정의되어 있습니다. 이 매개 변수가 "open"으로 설정된 경우 쿼리에는 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 상태 코드를 반환합니다.

## 요청 본문

### 샘플 요청

사용자의 "favorites" 소셜 그래프에 대한 모든 활동을 가져오려면 POST 본문은 다음과 같습니다.

```cpp theme={null}
{
  "type": "activity",
  "scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92"  // optional filter on scid
  "owners": {
     "people": {
       "moniker": "favorites",
       "monikerXuid": "3210"
     }
  }
}

```

## 응답 본문

결과는 각 핸들에 고유한 ID가 포함된 핸들 구조의 배열로 반환됩니다. 특정 세션 정보는 **relatedInfo** 개체에 반환됩니다. 이 정보는 이 URI에 대한 일반 POST 메서드에서는 반환되지 않습니다.

### 샘플 응답

```cpp theme={null}
{
	"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,
		}
	}]
}

```

## 함께 보기

##### 상위

[/handles/query](https://docs.xbox.com/ko/reference/live/rest/uri/sessiondirectory/uri-handlesquery.md)


## Related topics

- [/handles/query](https://docs.xbox.com/ko/reference/live/rest/uri/sessiondirectory/uri-handlesquery.md)
- [POST (/handles/query)](https://docs.xbox.com/ko/reference/live/rest/uri/sessiondirectory/uri-handlesquerypost.md)
- [Query](https://docs.xbox.com/ko/reference/system/dstorage/interfaces/IDStorageQueueX/methods/idstoragequeuex_query.md)
- [Session Directory URI](https://docs.xbox.com/ko/reference/live/rest/uri/sessiondirectory/atoc-reference-sessiondirectory.md)
- [POST (/handles)](https://docs.xbox.com/ko/reference/live/rest/uri/sessiondirectory/uri-handlespost.md)