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

# 將評分新增至您的內容

> 使用 ReviewItem、GetEntityItemReview 及相關評論管理 API，將玩家評分與評論新增至 PlayFab Economy v2 目錄項目。

> [!NOTE]
>
> Economy v2 現已正式推出。如需支援與意見反應，請前往 [PlayFab 論壇](https://community.playfab.com)。

本指南將介紹可用來為您的遊戲新增評分與評論系統的 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 中的資料總管進行查詢。範例查詢如下：

下列查詢會傳回**過去 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 只能由**遊戲實體**呼叫。此呼叫會接受一組要下架的評論。

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

> [!NOTE]
>
> 由於要求處理的關係，評論可能最多需要 24 小時才會下架

## 評分設計與快取

我們提供兩種取得評分的方法。兩種途徑的差異在於您是直接與評論互動，還是與目錄項目互動。

1. 我們直接提供評分 (透過 `GetItemReviews` 等)
2. 我們在目錄項目中提供評分彙總 (透過 `SearchItems` 等)

這兩種途徑都是非同步的，且具有必須了解的時間延遲。

### 直接評分 (GetItemReviews 等)

所有這些評分與評論都會直接提供。這裡有兩種延遲類別。

1. 個別評論 - *近乎即時*\
   個別評論不會立即可用，但應會在幾秒內出現。我們預期以退避方式重試即足以讀取全新的評論。
2. 彙總評分 - *15 分鐘以內*
   彙總有快取

### 目錄項目評分 (SearchItems 等)

所有這些評分都會作為我們已發佈目錄中目錄項目的一部分提供。

1. 彙總評分 - *8 小時以內*\
   系統會彙總評分，並將更新推送至目錄。更新可能需要 4 到 8 小時。


## Related topics

- [Unreal Engine 快速入門](https://docs.xbox.com/zh-TW/services/playfab/sdks/unreal/quickstart.md)
- [XAppCapture (API 內容)](https://docs.xbox.com/zh-TW/reference/system/xappcapture/xappcapture_members.md)
- [雲端儲存空間 (內容)](https://docs.xbox.com/zh-TW/services/xbox-services/storage/live-cloud-storage-nav.md)
- [Game Chat 2 概觀](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-overview.md)
- [邀請範例程式碼](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)