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：‘and’
邏輯 Or：‘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 陳述式指定，否則 Search 不會傳回項目的內容。如果執行上述查詢時未使用 `“Select”: “contents”“ 陳述式，它會正確套用篩選，但所有傳回的 Search 結果都會有空白的內容欄位

依顯示屬性篩選

只能使用可查詢的顯示屬性進行篩選

  "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/<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

​依標題排序

​依顯示屬性排序

​Select

​當地語系化

​限制

​搜尋商店

SearchItems

接續權杖

顯示屬性

Filter

依 ContentType 篩選

使用連接詞篩選

使用 null 值篩選

依建立者 ID 篩選

依陣列欄位篩選

使用陣列和 null 檢查篩選

依顯示屬性篩選

OrderBy

依標題排序

依顯示屬性排序

Select

當地語系化

限制

搜尋商店