SearchItems

项目
11/29/2023

重要

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

API SearchItems 使用提供的搜索参数对公共目录执行搜索，并返回分页的项目列表。

最基本的 Search 参数是对标题、描述、 关键字和 可搜索字符串显示属性 字段的纯文本模糊搜索。但是，Filter，OrderBy， Select 是可用于更改搜索参数的 OData 查询添加项。搜索结果可以按搜索文档中的任何字段（禁止标题和描述）进行筛选和排序。

有关 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 的 "显示属性映射 "设置中配置其自定义搜索和筛选属性。

Game Manager 中的显示属性屏幕截图

将字段添加到 DisplayProperties 时，它会在数据库中为你创建一个新索引。仅包含创建索引后添加或更新的文档。如果需要将显示属性应用于所有项目，则需要重新发布整个目录。

DateTime、 Double和 Queryable String 显示属性 可查询，这些属性可用于 Filter 和 OrderBy 语句。

Searchable String 显示属性是可搜索的，这些属性针对 Search 字段使用模糊搜索进行查询。无法在 Filter 和 OrderBy 语句中使用可搜索属性。

游戏限制为每种类型的五个显示属性。

警告

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

筛选器

使用 Filter 参数可以筛选搜索请求返回的项的集合。使用筛选器指定的表达式将针对结果中的每个目录项进行计算，并且仅包括表达式计算结果为 "true" 的项。

筛选器支持使用括号的 OData 逻辑运算符和优先级：

等于："eq"
不相等： ‘ ne’
大于： ‘ gt’
大于或等于： ‘ ge’
小于： ‘ lt’
小于或等于： ‘ le’
逻辑和："and"
逻辑或：’or’
逻辑求反"not"

筛选器不支持算术运算符或字符串函数。

以下是筛选器示例：

按 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 值的内容字段的任何项

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

注意

默认情况下，除非使用Select语句指定，否则搜索不会返回项的内容。如果运行上述查询时没有""Select"： "contents"'' 语句，它将正确应用筛选器，但所有返回的搜索结果都将具有空的内容字段

按显示属性筛选

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

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

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

  "OrderBy": "rating/average asc"

可以传递辅助属性来中断排序 "ties"：

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

没有辅助值的目录项具有用于中断关联的内部“score”属性。该评分基于基础数据库中的存储顺序，并且在添加和删除项时会不断变化。

OrderBy支持少量 OData 属性进行排序：

asc
desc

如果未指定方向，则默认值为升序。如果字段中存在 null 值，则它们将首先为 asc 显示，最后显示为 desc。如果未传递 OrderBy 值，则使用默认的 id asc 值。

下面是 OrderBy 示例：

按标题排序

使用 title/<LANG>parameter 与 ascor desc来指示顺序首选项。

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

使用 NEUTRAL 按中性字符串排序

  "OrderBy": "description/NEUTRAL desc"

按显示属性排序

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

  "OrderBy": "DisplayProperties/DifficultyRating desc"

选择

默认情况下，搜索将返回一组丰富的项元数据：

Id
Type
AlternateIds
Title （NEUTRAL 或 Language locale）
Description （NEUTRAL 或 Language locale）
Keywords （NEUTRAL 或 Language locale）
ContentType
Images （仅限缩略图）
Tags
CreationDate
LastModifiedDate
CreatorEntityKey（早期 API 版本中的 CreatorId）
DisplayProperties
ItemReferences

默认情况下，仅返回标题和说明中使用的中性字符串。如果缩略图存在，则默认返回它。每个项仅限于一个 " 的图像缩略图>类型。

使用 Select 可以选择在分页搜索结果中返回，包括内容元数据（内容）、图像、StartDate、EndDate 以及标题和说明中的完整本地化字符串集。如果选择字段留空，则搜索结果是完整文档元数据的子集，以便加快加载时间。

此请求将返回默认项元数据以及内容和图像：

"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}}"
  },
}

通过