다음을 통해 공유


Catalog - Search Items

Executes a search against the public catalog using the provided search parameters and returns a set of paginated results. SearchItems uses a cache of the catalog with item updates taking up to a few minutes to propagate. You should use the GetItem API for when trying to immediately get recent item updates. More information about the Search API can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search

POST https://titleId.playfabapi.com/Catalog/SearchItems

Request Header

Name Required Type Description
X-EntityToken True

string

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Request Body

Name Required Type Description
Count True

number

Number of items to retrieve. This value is optional. Maximum page size is 50. Default value is 10.

ContinuationToken

string

An opaque token used to retrieve the next page of items, if any are available.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Entity

EntityKey

The entity to perform this action on.

Filter

string

An OData filter used to refine the search query (For example: "type eq 'ugc'"). More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits

Language

string

The locale to be returned in the result.

OrderBy

string

An OData orderBy used to order the results of the search query. For example: "rating/average asc"

Search

string

The text to search for.

Select

string

An OData select query option used to augment the search results. If not defined, the default search result metadata will be returned.

Store

StoreReference

The store to restrict the search request to.

Responses

Name Type Description
200 OK

SearchItemsResponse

400 Bad Request

ApiErrorWrapper

This is the outer wrapper for all responses with errors

Security

X-EntityToken

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Type: apiKey
In: header

Definitions

Name Description
ApiErrorWrapper

The basic wrapper around every failed API response

CatalogAlternateId
CatalogItem
CatalogItemReference
CatalogPrice
CatalogPriceAmount
CatalogPriceAmountOverride
CatalogPriceOptions
CatalogPriceOptionsOverride
CatalogPriceOverride
Content
DeepLink
EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

FilterOptions
Image
KeywordSet
ModerationState
ModerationStatus
Permissions
Rating
SearchItemsRequest
SearchItemsResponse
StoreDetails
StoreReference

ApiErrorWrapper

The basic wrapper around every failed API response

Name Type Description
code

integer

Numerical HTTP code

error

string

Playfab error code

errorCode

integer

Numerical PlayFab error code

errorDetails

object

Detailed description of individual issues with the request object

errorMessage

string

Description for the PlayFab errorCode

status

string

String HTTP code

CatalogAlternateId

Name Type Description
Type

string

Type of the alternate ID.

Value

string

Value of the alternate ID.

CatalogItem

Name Type Description
AlternateIds

CatalogAlternateId[]

The alternate IDs associated with this item. An alternate ID can be set to 'FriendlyId' or any of the supported marketplace names.

ContentType

string

The client-defined type of the item.

Contents

Content[]

The set of content/files associated with this item. Up to 100 files can be added to an item.

CreationDate

string

The date and time when this item was created.

CreatorEntity

EntityKey

The ID of the creator of this catalog item.

DeepLinks

DeepLink[]

The set of platform specific deep links for this item.

DefaultStackId

string

The Stack Id that will be used as default for this item in Inventory when an explicit one is not provided. This DefaultStackId can be a static stack id or '{guid}', which will generate a unique stack id for the item. If null, Inventory's default stack id will be used.

Description

object

A dictionary of localized descriptions. Key is language code and localized string is the value. The NEUTRAL locale is required. Descriptions have a 10000 character limit per country code.

DisplayProperties

object

Game specific properties for display purposes. This is an arbitrary JSON blob. The Display Properties field has a 10000 byte limit per item.

DisplayVersion

string

The user provided version of the item for display purposes. Maximum character length of 50.

ETag

string

The current ETag value that can be used for optimistic concurrency in the If-None-Match header.

EndDate

string

The date of when the item will cease to be available. If not provided then the product will be available indefinitely.

Id

string

The unique ID of the item.

Images

Image[]

The images associated with this item. Images can be thumbnails or screenshots. Up to 100 images can be added to an item. Only .png, .jpg, .gif, and .bmp file types can be uploaded

IsHidden

boolean

Indicates if the item is hidden.

ItemReferences

CatalogItemReference[]

The item references associated with this item. For example, the items in a Bundle/Store/Subscription. Every item can have up to 50 item references.

Keywords

KeywordSet

A dictionary of localized keywords. Key is language code and localized list of keywords is the value. Keywords have a 50 character limit per keyword and up to 32 keywords can be added per country code.

LastModifiedDate

string

The date and time this item was last updated.

Moderation

ModerationState

The moderation state for this item.

Platforms

string[]

The platforms supported by this item.

PriceOptions

CatalogPriceOptions

The prices the item can be purchased for.

Rating

Rating

Rating summary for this item.

StartDate

string

The date of when the item will be available. If not provided then the product will appear immediately.

StoreDetails

StoreDetails

Optional details for stores items.

Tags

string[]

The list of tags that are associated with this item. Up to 32 tags can be added to an item.

Title

object

A dictionary of localized titles. Key is language code and localized string is the value. The NEUTRAL locale is required. Titles have a 512 character limit per country code.

Type

string

The high-level type of the item. The following item types are supported: bundle, catalogItem, currency, store, ugc, subscription.

CatalogItemReference

Name Type Description
Amount

number

The amount of the catalog item.

Id

string

The unique ID of the catalog item.

PriceOptions

CatalogPriceOptions

The prices the catalog item can be purchased for.

CatalogPrice

Name Type Description
Amounts

CatalogPriceAmount[]

The amounts of the catalog item price. Each price can have up to 15 item amounts.

UnitAmount

number

The per-unit amount this price can be used to purchase.

UnitDurationInSeconds

number

The per-unit duration this price can be used to purchase. The maximum duration is 100 years.

CatalogPriceAmount

Name Type Description
Amount

number

The amount of the price.

ItemId

string

The Item Id of the price.

CatalogPriceAmountOverride

Name Type Description
FixedValue

number

The exact value that should be utilized in the override.

ItemId

string

The id of the item this override should utilize.

Multiplier

number

The multiplier that will be applied to the base Catalog value to determine what value should be utilized in the override.

CatalogPriceOptions

Name Type Description
Prices

CatalogPrice[]

Prices of the catalog item. An item can have up to 15 prices

CatalogPriceOptionsOverride

Name Type Description
Prices

CatalogPriceOverride[]

The prices utilized in the override.

CatalogPriceOverride

Name Type Description
Amounts

CatalogPriceAmountOverride[]

The currency amounts utilized in the override for a singular price.

Content

Name Type Description
Id

string

The content unique ID.

MaxClientVersion

string

The maximum client version that this content is compatible with. Client Versions can be up to 3 segments separated by periods(.) and each segment can have a maximum value of 65535.

MinClientVersion

string

The minimum client version that this content is compatible with. Client Versions can be up to 3 segments separated by periods(.) and each segment can have a maximum value of 65535.

Tags

string[]

The list of tags that are associated with this content. Tags must be defined in the Catalog Config before being used in content.

Type

string

The client-defined type of the content. Content Types must be defined in the Catalog Config before being used.

Url

string

The Azure CDN URL for retrieval of the catalog item binary content.

Name Type Description
Platform

string

Target platform for this deep link.

Url

string

The deep link for this platform.

EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

Name Type Description
Id

string

Unique ID of the entity.

Type

string

Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types

FilterOptions

Name Type Description
Filter

string

The OData filter utilized. Mutually exclusive with 'IncludeAllItems'. More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits

IncludeAllItems

boolean

The flag that overrides the filter and allows for returning all catalog items. Mutually exclusive with 'Filter'.

Image

Name Type Description
Id

string

The image unique ID.

Tag

string

The client-defined tag associated with this image. Tags must be defined in the Catalog Config before being used in images

Type

string

Images can be defined as either a "thumbnail" or "screenshot". There can only be one "thumbnail" image per item.

Url

string

The URL for retrieval of the image.

KeywordSet

Name Type Description
Values

string[]

A list of localized keywords.

ModerationState

Name Type Description
LastModifiedDate

string

The date and time this moderation state was last updated.

Reason

string

The current stated reason for the associated item being moderated.

Status

ModerationStatus

The current moderation status for the associated item.

ModerationStatus

Name Type Description
Approved

string

AwaitingModeration

string

Rejected

string

Unknown

string

Permissions

Name Type Description
SegmentIds

string[]

The list of ids of Segments that the a player can be in to purchase from the store. When a value is provided, the player must be in at least one of the segments listed for the purchase to be allowed.

Rating

Name Type Description
Average

number

The average rating for this item.

Count1Star

number

The total count of 1 star ratings for this item.

Count2Star

number

The total count of 2 star ratings for this item.

Count3Star

number

The total count of 3 star ratings for this item.

Count4Star

number

The total count of 4 star ratings for this item.

Count5Star

number

The total count of 5 star ratings for this item.

TotalCount

number

The total count of ratings for this item.

SearchItemsRequest

Name Type Description
ContinuationToken

string

An opaque token used to retrieve the next page of items, if any are available.

Count

number

Number of items to retrieve. This value is optional. Maximum page size is 50. Default value is 10.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Entity

EntityKey

The entity to perform this action on.

Filter

string

An OData filter used to refine the search query (For example: "type eq 'ugc'"). More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits

Language

string

The locale to be returned in the result.

OrderBy

string

An OData orderBy used to order the results of the search query. For example: "rating/average asc"

Search

string

The text to search for.

Select

string

An OData select query option used to augment the search results. If not defined, the default search result metadata will be returned.

Store

StoreReference

The store to restrict the search request to.

SearchItemsResponse

Name Type Description
ContinuationToken

string

An opaque token used to retrieve the next page of items, if any are available.

Items

CatalogItem[]

The paginated set of results for the search query.

StoreDetails

Name Type Description
FilterOptions

FilterOptions

The options for the filter in filter-based stores. These options are mutually exclusive with item references.

Permissions

Permissions

The permissions that control which players can purchase from the store.

PriceOptionsOverride

CatalogPriceOptionsOverride

The global prices utilized in the store. These options are mutually exclusive with price options in item references.

StoreReference

Name Type Description
AlternateId

CatalogAlternateId

An alternate ID of the store.

Id

string

The unique ID of the store.

Error Codes

Name Code
DatabaseThroughputExceeded 1113
ItemNotFound 1047
NotImplemented 1515