> ## 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 のカタログ アイテムにプレイヤーの評価とレビューを追加します。
Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、[PlayFab フォーラム](https://community.playfab.com) を参照してください。
このガイドでは、ゲームに評価およびレビュー システムを追加するために使用できる API 呼び出しについて説明します。
## アイテムのレビュー
クライアントから `ReviewItem` API を呼び出すことで、アイテムに評価またはレビューを添付できます。アイテムをレビューするには、そのアイテムがすべてのプレイヤーに対して公開カタログで表示されている必要があります。評価およびレビューは API を呼び出したプレイヤーに紐付けられ、1 つのアイテムにつきプレイヤーごとに 1 件のレビューのみを関連付けることができます。アイテムの作成者は、自分自身のアイテムに対してレビューを送信することはできません。レビューは `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 を使用して、1 つ以上のレビューをテイクダウンするリクエストを送信できます。この API は **title entity** からのみ呼び出すことができます。この呼び出しは、テイクダウンするレビューのセットを受け取ります。
```json theme={null}
{
"Reviews": [
{
"ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
"ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef"
}
]
}
```
リクエストの処理により、レビューがテイクダウンされるまで最大 24 時間の遅延が発生する可能性があります。
## 評価の設計とキャッシング
評価を取得する方法は 2 つあります。2 つのパスの違いは、レビューと直接やり取りするか、カタログ アイテムとやり取りするかにあります。
1. 評価を直接提供します (`GetItemReviews` などを介して)
2. 評価の集計値をカタログ アイテムに含めて提供します (`SearchItems` などを介して)
どちらの経路も非同期であり、理解しておくべきタイミングの遅延があります。
### 直接評価 (GetItemReviews など)
これらの評価およびレビューはすべて直接提供されます。ここには 2 つのカテゴリのレイテンシーがあります。
1. 個別レビュー - *ほぼリアルタイム*\
個別レビューはすぐには利用できませんが、数秒以内に表示されるはずです。バックオフを付けて再試行すれば、新しく作成されたレビューを読み取るのに十分なはずです。
2. 集計評価 - *15 分未満*
集計値にはキャッシュがあります
### カタログ アイテムの評価 (SearchItems など)
これらの評価はすべて、公開されたカタログのカタログ アイテムの一部として提供されます。
1. 集計評価 - *8 時間未満*\
システムは評価を集計し、更新をカタログにプッシュします。更新には 4 ～ 8 時間かかることがあります。
## Related topics
- [プレイヤーにアドオン コンテンツへのアクセスを付与する](/ja-jp/publishing/xstore-commerce/xstore-granting-access.md)
- [MSIXVC2 によるコンテンツ更新](/ja-jp/build/core-features/common/packaging/packaging-updates-msixvc2.md)
- [製品変更とコンテンツ アップデート](/ja-jp/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
- [XStoreCanAcquireLicenseForStoreIdAsync](/ja-jp/reference/system/xstore/functions/xstorecanacquirelicenseforstoreidasync.md)
- [XStoreCanAcquireLicenseForPackageAsync](/ja-jp/reference/system/xstore/functions/xstorecanacquirelicenseforpackageasync.md)