SearchItems

Economy v2 现已正式发布。如需支持和反馈，请访问 PlayFab 论坛。

SearchItems API 使用所提供的搜索参数对公共目录执行搜索，并返回一个分页的物品列表。在最基本的形式中，Search 参数是对 Title、Description、Keywords 和 Searchable String Display Properties 字段的纯文本模糊搜索。但是，Filter、OrderBy 和 Select 是可用于更改搜索参数的 OData 查询扩展。搜索结果可以通过搜索文档中的任何字段进行筛选和排序（Title 和 Description 除外）。有关 OData 查询语法的更多信息，请参见此处 SearchItems 请求示例：

{
  "Search": "Pirates",
  "Filter": "Tags/any(t:t eq 'desert') and ContentType eq 'map'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2,
  "Language": "en-GB"
}

示例响应：

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
               <item metadata> 
            }
        ],
      "ContinuationToken": "MTA="
    }
}

延续令牌

从搜索响应返回的 ContinuationToken 字段可以传入搜索请求，以分页浏览多个计数的结果。

显示属性

搜索、筛选和排序也可以在为自定义搜索配置的特定 DisplayProperties 字段上进行。游戏可以在 Game Manager 的 Display Properties Mappings 设置中配置其自定义搜索和筛选属性。当你向 DisplayProperties 添加字段时，它会在数据库中为你创建一个新索引。仅索引创建后添加或更新的文档才会包含在内。如果你需要显示属性适用于所有物品，则需要重新发布整个目录。 DateTime、Double 和 Queryable String 显示属性是可查询的，这些属性可用于 Filter 和 OrderBy 语句。 Searchable String 显示属性是可搜索的，这些属性通过对 Search 字段进行模糊搜索来查询。可搜索属性不能用于 Filter 和 OrderBy 语句。游戏被限制为每种类型五个显示属性。

显示属性映射存储为键值对的索引列表。删除现有的显示属性映射可能会移动索引并破坏所有剩余属性的行为。建议添加额外的属性，而不是删除或编辑现有属性，除非绝对必要，否则应避免删除属性映射。

Filter

Filter 参数允许你筛选搜索请求返回的物品集合。使用 filter 指定的表达式会对结果中的每个目录物品进行评估，只有表达式评估为”true”的物品才会包含在内。 Filter 支持 OData 逻辑运算符和使用括号的优先级：

等于：“eq”
不等于：“ne”
大于：“gt”
大于或等于：“ge”
小于：“lt”
小于或等于：“le”
逻辑与：“and”
逻辑或：“or”
逻辑取反：“not”

Filter 不支持算术运算符或字符串函数。以下是 Filter 示例：

按 ContentType 筛选

  "Filter": "ContentType eq 'Sword'"

使用连词进行筛选

  "Filter": "rating/average gt 1 and rating/average lt 4"

使用 null 值进行筛选

OData 支持 null 类型用于筛选

"Filter": "rating eq null"

上述请求返回所有没有评论的物品

按创建者 ID 筛选

要按特定创建者筛选，你应使用语法 title_player_account!<ID>

  "Filter": "creatorId eq 'title_player_account!C88F55C6A734B1DC'"

按数组字段筛选

Filter 还支持 any() 以针对数组进行筛选。例如：alternateIds/any(a: a/value eq 'StoreOfferId')

  "Filter": "tags/any(t: t eq 'featured')"

使用数组和 null 检查进行筛选

下面的过滤器将检查任何具有非 null 值的 contents 字段的物品

  "Filter": "contents/any(content: content ne null)"

默认情况下，搜索不会返回物品的内容，除非通过 Select 语句指定。如果在没有 "Select": "contents" 语句的情况下运行上述查询，它将正确应用筛选器，但所有返回的搜索结果将具有空内容字段

按显示属性筛选

筛选只能使用可查询的显示属性

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy 是一个逗号分隔的列表，用于对搜索结果进行排序。

  "OrderBy": "rating/average asc"

你可以传递一个次要属性来打破排序”平局”：

  "OrderBy": "rating/average asc, rating/totalCount desc"

没有次要值的目录物品有一个内部”score”属性，用于打破平局。该评分基于底层数据库中的存储顺序，随着物品的添加和删除而不断变化。 OrderBy 支持一些用于排序的 OData 属性：

asc
desc

如果你未指定方向，默认为升序。如果字段中有 null 值，它们对 asc 首先显示，对 desc 最后显示。如果未传递 OrderBy 值，则使用默认 id asc 值。以下是 OrderBy 示例：

按 Title 排序

使用 title/<LANG> 参数与 asc 或 desc 结合以指示顺序偏好。

  "OrderBy": "title/en-GB asc"

使用 NEUTRAL 按中性字符串排序

  "OrderBy": "description/NEUTRAL desc"

按显示属性排序

排序只能使用可查询的显示属性

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

默认情况下，Search 返回一组丰富的物品元数据：

Id
Type
AlternateIds
Title (NEUTRAL 或 Language 区域设置)
Description (NEUTRAL 或 Language 区域设置)
Keywords (NEUTRAL 或 Language 区域设置)
ContentType
Images （仅缩略图）
Tags
CreationDate
LastModifiedDate
CreatorEntityKey（早期 API 版本中的 CreatorId）
DisplayProperties
ItemReferences

默认情况下，仅返回 title 和 description 中使用的中性字符串。如果存在缩略图，则默认返回。每个物品仅限一张”Thumbnail”类型的图像。使用 Select，可以在分页搜索结果中可选地返回更多字段，包括内容元数据 (contents)、图像、StartDate、EndDate 以及 title 和 description 中完整的本地化字符串集。如果 select 字段留空，搜索结果是完整文档元数据的子集，以便更快加载。此请求将返回默认物品元数据以及内容和图像：

"Select": "contents,images"

选择 title、description 和/或 keywords 将返回完整的本地化字符串数据集：

"Select": "title,description,keywords"

本地化

可以将区域设置传入 Language 参数。传递区域设置会导致所有 Title、Description、Keywords 字段默认返回该区域设置，如果物品没有该本地化，则返回 NEUTRAL。带有 Language 参数的 SearchItems 请求示例可在本页顶部找到。有关本地化的更多信息，请参阅本地化。

限制

每个请求的搜索筛选查询的复杂度受到限制。昂贵的查询可能会被拒绝，游戏应确保它们没有尝试过于复杂的查询。以下是接近最大复杂度的查询示例：

contentType eq 'testType' and tags/any(t: t eq 'blue' or t eq 'green' or t eq 'violet') and platforms/any(p: p eq 'square' or p eq 'circle' or p eq 'triangle') and displayProperties/isFavorite eq true

contents/any(c: c/minClientVersion gt '1.2.3' and c/maxClientVersion lt '4.5.6' and c/tags/any(t: t eq 'map')) and rating/totalRatingsCount ge 20 and rating/averageRating ge 4.0

高复杂度过滤查询会抛出 400 错误，消息为："The filter provided in the request does not meet the complexity requirements for source"。

搜索商店

你可以传入的属性之一是 Store 参数。这允许你在商店的上下文中进行搜索。除了能够检查特定商店中是否存在物品外，它还可用于显示商店物品/内容的覆盖价格。你也可以使用商店的 AlternateId 进行搜索。有关使用商店的更多信息，请参阅此处

{
  "Search": "",
  "Filter": "ContentType eq 'weapons'",
  "Store": {
    "Id": "{{StoreID}}"
  },
}

​SearchItems

​延续令牌

​显示属性

​Filter

​按 ContentType 筛选

​使用连词进行筛选

​使用 null 值进行筛选

​按创建者 ID 筛选

​按数组字段筛选

​使用数组和 null 检查进行筛选

​按显示属性筛选

​OrderBy

​按 Title 排序

​按显示属性排序

​Select

​本地化

​限制

​搜索商店

SearchItems

延续令牌

显示属性

Filter

按 ContentType 筛选

使用连词进行筛选

使用 null 值进行筛选

按创建者 ID 筛选

按数组字段筛选

使用数组和 null 检查进行筛选

按显示属性筛选

OrderBy

按 Title 排序

按显示属性排序

Select

本地化

限制

搜索商店