SearchItems

Economy v2는 이제 정식으로 사용할 수 있습니다(GA). 지원 및 피드백은 PlayFab Forum을 방문하세요.

SearchItems API는 제공된 검색 매개 변수를 사용하여 공용 Catalog에 대한 검색을 실행하고 페이지 매김된 아이템 목록을 반환합니다. 가장 기본적으로 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="
    }
}

Continuation Token

검색 응답에서 반환된 ContinuationToken 필드를 검색 요청에 전달하여 여러 개의 결과 카운트를 페이지 매김할 수 있습니다.

Display Properties

검색, 필터 및 정렬은 사용자 지정 검색을 위해 구성된 특정 DisplayProperties 필드에서도 수행할 수 있습니다. 타이틀은 Game Manager의 Display Properties Mappings setting에서 사용자 지정 검색 및 필터 속성을 구성할 수 있습니다.

DisplayProperties에 필드를 추가하면 데이터베이스에 새 인덱스가 만들어집니다. 인덱스 생성 후에 추가되거나 업데이트된 문서만 포함됩니다. Display Property가 모든 아이템에 적용되어야 하는 경우 전체 카탈로그를 다시 게시해야 합니다. DateTime, Double, Queryable String display 속성은 쿼리 가능하며, 이러한 속성은 Filter와 OrderBy 문에서 사용할 수 있습니다. Searchable String display 속성은 검색 가능하며, 이러한 속성은 Search 필드에 대한 퍼지 검색으로 쿼리됩니다. 검색 가능한 속성은 Filter 및 OrderBy 문에서 사용할 수 없습니다. 타이틀은 각 유형의 display 속성이 5개로 제한됩니다.

Display 속성 매핑은 키-값 쌍의 색인화된 목록으로 저장됩니다. 기존 display 속성 매핑을 삭제하면 인덱스가 이동하고 남아 있는 모든 속성의 동작이 손상될 수 있습니다. 기존 속성을 삭제하거나 편집하는 대신 추가 속성을 추가하는 것이 좋으며, 절대적으로 필요한 경우가 아니면 속성 매핑을 삭제하지 않아야 합니다.

Filter

Filter 매개 변수를 사용하면 검색 요청에서 반환된 아이템 컬렉션을 필터링할 수 있습니다. filter로 지정된 식은 결과의 각 Catalog Item에 대해 평가되며 식이 “true”로 평가되는 아이템만 포함됩니다. Filter는 OData 논리 연산자와 괄호를 사용한 우선 순위를 지원합니다.

Equal: ‘eq’
Not Equal: ‘ne’
Greater Than: ‘gt’
Greater than or Equal: ‘ge’
Less than: ‘lt’
Less than or Equal: ‘le’
Logical And: ‘and’
Logical Or: ‘or’
Logical Negation ‘not’

Filter는 산술 연산자나 문자열 함수를 지원하지 않습니다. 다음은 Filter 예제입니다.

ContentType으로 필터링

  "Filter": "ContentType eq 'Sword'"

Conjunction으로 필터링

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

null 값으로 필터링

OData는 필터링을 위한 null 형식을 지원합니다.

"Filter": "rating eq null"

위 요청은 리뷰가 없는 모든 아이템을 반환합니다.

Creator 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)"

기본적으로 Search는 Select 문으로 지정되지 않는 한 아이템에 대한 contents를 반환하지 않습니다. 위 쿼리가 "Select": "contents" 문 없이 실행되면 필터는 올바르게 적용되지만 반환된 모든 Search 결과는 빈 content 필드를 갖게 됩니다.

Display Properties로 필터링

필터링은 쿼리 가능한 Display Properties로만 수행할 수 있습니다.

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy는 검색 결과를 정렬하는 데 사용되는 쉼표로 구분된 목록입니다.

  "OrderBy": "rating/average asc"

정렬 ‘tie’를 깨기 위해 보조 속성을 전달할 수 있습니다.

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

보조 값이 없는 카탈로그 아이템은 tie를 깨는 데 사용되는 내부 ‘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"

Display Properties로 정렬

정렬은 쿼리 가능한 Display Properties로만 수행할 수 있습니다.

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

기본적으로 Search는 풍부한 아이템 메타데이터 집합을 반환합니다.

Id
Type
AlternateIds
Title (NEUTRAL 또는 Language 로케일)
Description (NEUTRAL 또는 Language 로케일)
Keywords (NEUTRAL 또는 Language 로케일)
ContentType
Images (Thumbnail만)
Tags
CreationDate
LastModifiedDate
CreatorEntityKey (이전 API 버전에서는 CreatorId)
DisplayProperties
ItemReferences

기본적으로 title과 description에 사용된 중립 문자열만 반환됩니다. Thumbnail 이미지가 있으면 기본적으로 반환됩니다. 각 아이템은 “Thumbnail” 유형의 이미지 하나만으로 제한됩니다. Select를 사용하면 콘텐츠 메타데이터(contents), images, StartDate, EndDate 및 title과 description의 지역화된 문자열 전체 집합을 포함하여 페이지 매김된 검색 결과 내에서 더 많은 필드를 선택적으로 반환할 수 있습니다. Select 필드를 비워두면 검색 결과는 로드 시간을 더 빠르게 하기 위해 전체 문서 메타데이터의 하위 집합이 됩니다. 이 요청은 기본 아이템 메타데이터 및 content와 images를 반환합니다.

"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

​Continuation Token

​Display Properties

​Filter

​ContentType으로 필터링

​Conjunction으로 필터링

​null 값으로 필터링

​Creator ID로 필터링

​배열 필드로 필터링

​배열 및 null 확인으로 필터링

​Display Properties로 필터링

​OrderBy

​제목으로 정렬

​Display Properties로 정렬

​Select

​지역화

​제한

​스토어 검색

SearchItems

Continuation Token

Display Properties

Filter

ContentType으로 필터링

Conjunction으로 필터링

null 값으로 필터링

Creator ID로 필터링

배열 필드로 필터링

배열 및 null 확인으로 필터링

Display Properties로 필터링

OrderBy

제목으로 정렬

Display Properties로 정렬

Select

지역화

제한

스토어 검색