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

# 콘텐츠에 평점 추가

> ReviewItem, GetEntityItemReview 및 관련 리뷰 관리 API를 사용하여 PlayFab Economy v2 카탈로그 아이템에 플레이어 평점과 리뷰를 추가합니다.

<Info>
  Economy v2는 이제 정식으로 사용할 수 있습니다(GA). 지원 및 피드백은 [PlayFab Forum](https://community.playfab.com)을 방문하세요.
</Info>

이 가이드에서는 게임에 평점 및 리뷰 시스템을 추가하는 데 사용할 수 있는 API 호출을 살펴봅니다.

## 아이템 리뷰

클라이언트에서 `ReviewItem` API를 호출하여 아이템에 평점 또는 리뷰를 첨부할 수 있습니다. 아이템을 리뷰하려면 모든 플레이어의 공용 카탈로그에 표시되어야 합니다. 평점과 리뷰는 API를 호출하는 플레이어에게 첨부되며 플레이어당 하나의 리뷰만 아이템에 연결될 수 있습니다. 아이템 작성자는 자신의 아이템에 대해 리뷰를 제출할 수 없습니다. 리뷰는 `ReviewItem`이 호출될 때마다 업데이트됩니다. 호출에 **필수**로 필요한 데이터는 다음과 같습니다.

* `Id`: 리뷰할 아이템의 고유 ID.
* `Rating`: `1`\~`5` 등급 형태의 숫자 평점.

또한 **선택적** 매개 변수도 추가할 수 있습니다.

* `Title`: 리뷰의 제목.
* `ReviewText`: 리뷰용 자유 텍스트 필드.
* `IsInstalled`: 리뷰어가 아이템을 가지고 있는지 나타내는 플래그.
* `ItemVersion`: 리뷰되는 아이템의 버전 번호.

```json theme={null}
{
  "Review": {
    "ItemVersion": "2.4.1",
    "Rating": 5,
    "Title": "Best Game Ever",
    "ReviewText": "I play this game every day. It's my favorite game yet.",
    "IsInstalled": true
  },
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9"
}
```

리뷰가 제출되면 `Submitted` 타임스탬프가 자동으로 채워지고 업데이트됩니다.

## 아이템에 대한 플레이어의 리뷰 가져오기

클라이언트에서 `GetEntityItemReview` API를 호출하여 아이템에 대한 플레이어의 리뷰를 가져올 수 있습니다. 아이템 `Id` 또는 `AlternateId`를 제공해야 합니다. 리뷰와 관련된 특정 `ReviewId`가 반환됩니다.

```json theme={null}
{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
            "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
            "ReviewerId": "title_player_account!218870DE55036998",
            "ItemVersion": "2.4.1",
            "Title": "Best Game Ever",
            "ReviewText": "I play this game every day. It's my favorite game yet.",
            "Rating": 5,
            "IsInstalled": true,
            "Locale": "NEUTRAL",
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "2021-08-09T06:44:22.569Z"
        }
    }
}
```

리뷰를 하지 않은 플레이어에 대해 `GetEntityItemReview`를 호출하면 0으로 초기화된 값의 Review 개체가 반환됩니다.

```json theme={null}
{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "00000000-0000-0000-0000-000000000000",
            "Rating": 0,
            "IsInstalled": false,
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "0001-01-01T00:00:00Z"
        }
    }
}
```

## 아이템에 대한 리뷰 가져오기

`GetItemReviews` API를 호출하여 아이템의 **텍스트가 포함된** 모든 리뷰에 액세스할 수 있습니다. 아이템 `Id` 또는 `AlternateId`를 제공해야 합니다. **선택적** 매개 변수를 추가할 수 있습니다.

* `ContinuationToken`: 사용 가능한 경우 다음 아이템 페이지를 검색하는 데 사용되는 불투명 토큰.
* `Count`: 검색할 아이템 수. 최대 페이지 크기는 200. 지정되지 않으면 기본값은 10.
* `OrderBy`: 쿼리 결과를 정렬하는 데 사용되는 OData orderBy. 가능한 값은 `Helpfulness`, `Rating`, `Submitted`.

```json theme={null}
{
  "Count": 2,
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
  "OrderBy": "Submitted desc"
}
```

## 리뷰에 도움됨 투표 제출

플레이어는 `SubmitItemReviewVote` API를 호출하여 리뷰에 대한 도움됨 투표를 제출할 수 있습니다. 새 도움됨 투표를 제출하면 `Vote` 매개 변수의 부울 값에 따라 `HelpfulPositive` 또는 `HelpfulNegative`가 증가합니다.

```json theme={null}
{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "Vote": "Helpful/UnHelpful"
}
```

## 리뷰 신고

플레이어는 클라이언트에서 `ReportItemReview` API를 호출하여 리뷰를 신고할 수 있습니다. `ReviewId`를 제공해야 합니다. **선택적** `ConcernCategory` 매개 변수를 추가할 수 있습니다.

```json theme={null}
{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "ConcernCategory": "OffensiveContent"
}
```

지정되지 않으면 `ConcernCategory`의 기본값은 `None`입니다. 유효한 `ConcernCategory` 값은 다음과 같습니다.

* `None`
* `OffensiveContent`
* `ChildExploitation`
* `MalwareOrVirus`
* `PrivacyConcerns`
* `MisleadingApp`
* `PoorPerformance`
* `ReviewResponse`
* `SpamAdvertising`
* `Profanity`

`ReportItemReview`를 호출하면 이벤트 이름 `item_reported` 아래에서 PlayStream 이벤트만 발생합니다. Game Manager의 Data Explorer를 사용하여 쿼리하세요. 예제 쿼리는 아래에서 볼 수 있습니다.

다음 쿼리는 **지난 3일 동안 ItemId별 ConcernCategory별 총 신고 수**를 반환합니다.

```kusto theme={null}
['events.all']
| where Timestamp > ago (3d)
| where FullName_Name == "review_reported"
| project ReviewId = tostring(EventData.Payload.ReviewId), ConcernCategory = tostring(EventData.Payload.ConcernCategory)
| summarize TotalReportCount = count() by ReviewId, ConcernCategory
| sort by TotalReportCount desc
| render columnchart kind=stacked
```

## 리뷰 삭제

`TakedownItemReviews` API를 사용하여 하나 이상의 리뷰를 삭제하는 요청을 제출할 수 있습니다. 이 API는 **title entity**만 호출할 수 있습니다. 호출은 삭제할 리뷰 집합을 받습니다.

```json theme={null}
{
  "Reviews": [
    {
      "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
      "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef"
    }
  ]
}
```

<Note>
  요청 처리로 인해 리뷰가 삭제되기까지 최대 24시간의 지연이 있을 수 있습니다.
</Note>

## 평점 설계 및 캐싱

평점을 가져오는 두 가지 방법이 있습니다. 두 경로의 차이점은 리뷰와 직접 상호 작용하는지 카탈로그 아이템과 상호 작용하는지에 있습니다.

1. 평점을 직접 제공(예: `GetItemReviews` 등)
2. 카탈로그 아이템의 평점 집계 제공(예: `SearchItems` 등)

두 경로 모두 비동기적이며 이해해야 하는 시간 지연이 있습니다.

### 직접 평점(GetItemReviews 등)

이러한 모든 평점 및 리뷰는 직접 제공됩니다. 여기에는 두 가지 지연 시간 범주가 있습니다.

1. 개별 리뷰 - *거의 실시간*\
   개별 리뷰는 즉시 사용할 수 없지만 몇 초 이내에 표시되어야 합니다. 백오프를 사용하여 다시 시도하는 것으로 새로 만든 리뷰를 읽는 데 충분할 것으로 예상됩니다.
2. 집계 평점 - *15분 미만*
   집계용 캐시가 있습니다.

### 카탈로그 아이템 평점(SearchItems 등)

이러한 모든 평점은 게시된 카탈로그의 카탈로그 아이템의 일부로 제공됩니다.

1. 집계 평점 - *8시간 미만*\
   시스템은 평점을 집계하고 카탈로그에 업데이트를 푸시합니다. 업데이트는 4\~8시간이 걸릴 수 있습니다.


## Related topics

- [플레이어에게 추가 기능 콘텐츠 액세스 부여](/ko/publishing/xstore-commerce/xstore-granting-access.md)
- [제품 변경 및 콘텐츠 업데이트](/ko/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
- [XStoreProduct](/ko/reference/system/xstore/structs/xstoreproduct.md)
- [XStoreQueryProductsResult](/ko/reference/system/xstore/functions/xstorequeryproductsresult.md)
- [XStoreQueryAssociatedProductsResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsresult.md)