向内容添加分级

项目
07/13/2023

重要

Economy v2 现已正式发布。有关支持和反馈，请转到 PlayFab 论坛。

本指南将介绍可用于向游戏添加评分和评价系统的 API 调用。

评价某个项目

可以通过从客户端调用 ReviewItem API 将评分或评价附加到一个项目上。要评价某个项目，它必须在所有玩家的公共目录中可见。评分和评价将被附加到调用 API 的玩家，并且每个玩家只有一条评价可以和项目关联。项目的创作者无法为自己的项目提交评价。每次调用 ReviewItem 时都会更新评价。调用需要以下数据：

Id：要评价的项目的唯一 ID。
Rating：1和5之间的数字评分。

此外，还可以添加可选参数：

Title：评价的标题。
ReviewText：评价的自由文本字段。
IsInstalled：指示评价者是否拥有该项目的标记。
ItemVersion：所评价项目的版本号。

{
  "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。

{
    "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 将返回值为零的评价对象：

{
    "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。

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

针对评价提交有用性投票

玩家可以通过调用 SubmitItemReviewVote API 针对评论提交有用性投票。提交新的有用性投票将递增 HelpfulPositive 或 HelpfulNegative，具体取决于 Vote 参数的布尔值。

{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "Vote": "Helpful/UnHelpful"
}

报告评价

玩家可以通过从客户端调用 ReportItemReview API 来报告评价。必须提供 ReviewId。可以添加可选ConcernCategory参数。

{
  "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 中的数据资源管理器进行查询。可在下面看到示例查询：

以下查询返回过去 3 天内每个 ItemId 的 ConcernCategory 报告总数

['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 只能由游戏实体调用。该调用将接受一组要撤销的评价。

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

注意

由于请求处理过程，撤销评价最多可能会延迟 24 小时

评分设计和缓存

我们有两种获取评分的方法。这两种路径之间的区别是，是直接与评价还是与目录项交互。

我们直接提供评分(通过 GetItemReviews 等)
我们提供目录项中的评分聚合(通过 SearchItems 等)

这两条路线都为异步操作，且具有需要了解的计时延迟。

直接评分(GetItemReviews 等)

所有这些评分和评价都直接提供。此处有两种类别的延迟。

单个评价 - 近实时
单个评价不会立即提供，但应在几秒钟内显示。我们预计，使用回退进行重试足以读取全新评价。
聚合分级 - 不到 15 分钟有聚合缓存

目录项评分(SearchItems 等)

所有这些评分都作为已发布目录的目录项的一部分提供。

聚合评分 - 8 小时内
系统会聚合评分并将更新推送到目录中。更新可能需要 4 到 8 小时。

通过