> ## 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. # 搜索 > 使用 OData 过滤器、排序、分页和延续令牌，通过 SearchItems API 查询 PlayFab Economy v2 公共目录。 # SearchItems Economy v2 现已正式发布。如需支持和反馈，请访问 [PlayFab 论坛](https://community.playfab.com)。 `SearchItems` API 使用所提供的搜索参数对公共目录执行搜索，并返回一个分页的物品列表。 在最基本的形式中，`Search` 参数是对 **Title**、**Description**、**Keywords** 和 **Searchable String Display Properties** 字段的纯文本模糊搜索。但是，`Filter`、`OrderBy` 和 `Select` 是可用于更改搜索参数的 OData 查询扩展。搜索结果可以通过搜索文档中的任何字段进行筛选和排序（Title 和 Description 除外）。 有关 OData 查询语法的更多信息，请参见[此处](https://www.odata.org/getting-started/basic-tutorial/#queryData) `SearchItems` 请求示例： ```csharp theme={null} { "Search": "Pirates", "Filter": "Tags/any(t:t eq 'desert') and ContentType eq 'map'", "OrderBy": "lastModifiedDate asc", "ContinuationToken": "abc=", "Count": 2, "Language": "en-GB" } ``` 示例响应： ```csharp theme={null} { "code": 200, "status": "OK", "data": { "Items": [ { } ], "ContinuationToken": "MTA=" } } ``` ## 延续令牌 从搜索响应返回的 `ContinuationToken` 字段可以传入搜索请求，以分页浏览多个计数的结果。 ## 显示属性 搜索、筛选和排序也可以在为自定义搜索配置的特定 `DisplayProperties` 字段上进行。游戏可以在 Game Manager 的 [Display Properties Mappings 设置](/services/playfab/economy-monetization/economy-v2/settings#display-property-mappings) 中配置其自定义搜索和筛选属性。 Game Manager 中的显示属性屏幕截图 当你向 `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 筛选 ```json theme={null} "Filter": "ContentType eq 'Sword'" ``` ### 使用连词进行筛选 ```json theme={null} "Filter": "rating/average gt 1 and rating/average lt 4" ``` ### 使用 null 值进行筛选 OData 支持 `null` 类型用于筛选 ```json theme={null} "Filter": "rating eq null" ``` 上述请求返回所有没有评论的物品 ### 按创建者 ID 筛选 要按特定创建者筛选，你应使用语法 `title_player_account!` ```json theme={null} "Filter": "creatorId eq 'title_player_account!C88F55C6A734B1DC'" ``` ### 按数组字段筛选 Filter 还支持 `any()` 以针对数组进行筛选。例如：`alternateIds/any(a: a/value eq 'StoreOfferId')` ```json theme={null} "Filter": "tags/any(t: t eq 'featured')" ``` ### 使用数组和 null 检查进行筛选 下面的过滤器将检查任何具有非 null 值的 contents 字段的物品 ```json theme={null} "Filter": "contents/any(content: content ne null)" ``` 默认情况下，搜索**不会**返回物品的内容，除非通过 [Select](/services/playfab/economy-monetization/economy-v2/catalog/search#select) 语句指定。如果在没有 `"Select": "contents"` 语句的情况下运行上述查询，它将正确应用筛选器，但所有返回的搜索结果将具有空内容字段 ### 按显示属性筛选 筛选只能使用**可查询**的显示属性 ```json theme={null} "Filter": "DisplayProperties/DifficultyRating ge 5" ``` ## OrderBy `OrderBy` 是一个逗号分隔的列表，用于对搜索结果进行排序。 ```json theme={null} "OrderBy": "rating/average asc" ``` 你可以传递一个次要属性来打破排序"平局"： ```json theme={null} "OrderBy": "rating/average asc, rating/totalCount desc" ``` 没有次要值的目录物品有一个内部"score"属性，用于打破平局。该评分基于底层数据库中的存储顺序，随着物品的添加和删除而不断变化。 `OrderBy` 支持一些用于排序的 OData 属性： * `asc` * `desc` 如果你未指定方向，默认为升序。如果字段中有 null 值，它们对 `asc` 首先显示，对 `desc` 最后显示。如果未传递 `OrderBy` 值，则使用默认 `id asc` 值。 以下是 OrderBy 示例： ### 按 Title 排序 使用 `title/` 参数与 `asc` 或 `desc` 结合以指示顺序偏好。 ```json theme={null} "OrderBy": "title/en-GB asc" ``` 使用 `NEUTRAL` 按中性字符串排序 ```json theme={null} "OrderBy": "description/NEUTRAL desc" ``` ### 按显示属性排序 排序只能使用**可查询**的显示属性 ```json theme={null} "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 字段留空，搜索结果是完整文档元数据的子集，以便更快加载。 此请求将返回默认物品元数据**以及**内容和图像： ```json theme={null} "Select": "contents,images" ``` 选择 `title`、`description` 和/或 `keywords` 将返回完整的本地化字符串数据集： ```json theme={null} "Select": "title,description,keywords" ``` ## 本地化 可以将区域设置传入 `Language` 参数。传递区域设置会导致所有 `Title`、`Description`、`Keywords` 字段默认返回该区域设置，如果物品没有该本地化，则返回 NEUTRAL。 带有 `Language` 参数的 `SearchItems` 请求示例可在[本页顶部](#searchitems)找到。 有关本地化的更多信息，请参阅 [本地化](/services/playfab/economy-monetization/economy-v2/catalog/localization)。 ## 限制 每个请求的搜索筛选查询的复杂度受到限制。昂贵的查询可能会被拒绝，游戏应确保它们没有尝试过于复杂的查询。以下是接近最大复杂度的查询示例： ```json theme={null} 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 ``` ```json theme={null} 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` 进行搜索。有关使用商店的更多信息，请参阅[此处](/services/playfab/economy-monetization/economy-v2/catalog/stores) ```json theme={null} { "Search": "", "Filter": "ContentType eq 'weapons'", "Store": { "Id": "{{StoreID}}" }, } ``` ## Related topics - [PFLobby 搜索键](/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/constants/pflobbysearchkeys.md) - [创建可搜索的大厅](/zh-CN/services/playfab/multiplayer/lobby/define-search-keywords.md) - [服务器概述页面](/zh-CN/services/playfab/multiplayer/servers/build-server-overview.md) - [查找大厅](/zh-CN/services/playfab/multiplayer/lobby/find-lobbies.md) - [多人游戏概念概述](/zh-CN/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts.md)