> ## 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 现已正式发布。如需支持和反馈，请访问 [PlayFab 论坛](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` 会返回一个值为零的 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 小时。