다음을 통해 공유

SearchItems

  • 아티클

Important

이제 Economy v2가 일반 공급됩니다. 지원 및 피드백을 받으려면 PlayFab 포럼으로 이동하세요.

SearchItems API는 제공된 검색 매개 변수를 사용하여 공개 카탈로그에서 검색을 실행하고 페이징된 항목 목록을 반환합니다.

가장 기본적인 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 필드에서도 검색과 필터링, 정렬을 할 수 있습니다. 타이틀은 게임 관리자의 디스플레이 속성 매핑 설정에서 사용자 지정 검색 및 필터 속성을 구성할 수 있습니다.

게임 관리자의 디스플레이 속성 스크린샷

DisplayProperties에 필드를 추가하면 데이터베이스에 새 인덱스가 생성됩니다. 인덱스를 생성한 후에 추가되거나 업데이트된 문서만 포함됩니다. 모든 항목에 적용할 디스플레이 속성이 필요한 경우 전체 카탈로그를 다시 게시해야 합니다.

DateTime, Double 및 Queryable String 표시 속성은 쿼리 가능하며 이러한 속성은 Filter 및 OrderBy 문에서 사용할 수 있습니다.

Searchable String 디스플레이 속성은 검색할 수 있으며, 이러한 속성은 Search 필드에 대한 퍼지 검색으로 쿼리됩니다. 필터 및 OrderBy 문에는 검색 가능한 속성을 사용할 수 없습니다.

타이틀은 각 유형의 표시 속성이 5개로 제한됩니다.

Warning

디스플레이 속성 매핑은 키 값 쌍의 인덱싱된 목록으로 저장됩니다. 기존 디스플레이 속성 매핑을 삭제하면 인덱스를 이동하고 나머지 모든 속성의 동작을 끊을 수 있습니다. 기존 속성을 삭제하거나 편집하는 대신 추가 속성을 추가하는 것이 좋습니다. 반드시 필요한 경우를 제외하고는 속성 매핑을 삭제하지 않도록 해야 합니다.

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

배열 필드로 필터링

필터는 배열에 대한 필터링에 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"

보조 속성을 전달하여 정렬 '관계'를 해제할 수 있습니다.

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

보조 값이 없는 카탈로그 항목에는 관계 해제에 사용되는 내부 'score' 특성이 있습니다. 이 점수는 기본 데이터베이스의 저장소 순서를 기반으로 하며 항목이 추가되고 제거됨에 따라 지속적으로 변경됩니다.

OrderBy은(는) 정렬을 위해 소수의 OData 속성을 지원합니다.

  • asc
  • desc

방향을 지정하지 않으면 기본값으로 오름차순을 사용합니다. 필드에 null 값이 있는 경우 asc은(는) 처음에, desc는(는) 마지막에 표시됩니다. OrderBy 값이 전달되지 않으면 기본 id asc 값이 사용됩니다.

다음은 OrderBy 예제입니다.

타이틀로 정렬

asc 또는 desc와(과) 함께 title/<LANG> 매개 변수를 사용하여 순서 기본 설정을 나타냅니다.

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

NEUTRAL을(를) 사용하여 중립 문자열 순서를 지정

  "OrderBy": "description/NEUTRAL desc"

디스플레이 속성으로 정렬

정렬은 쿼리 가능한 디스플레이 속성으로만 수행될 수 있습니다.

  "OrderBy": "DisplayProperties/DifficultyRating desc"

선택

기본적으로 검색은 다양한 항목 메타데이터 집합을 반환합니다.

  • Id
  • Type
  • AlternateIds
  • Title (NEUTRAL 또는 Language 로캘)
  • Description (NEUTRAL 또는 Language 로캘)
  • Keywords (NEUTRAL 또는 Language 로캘)
  • 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 필드가 기본적으로 로캘을 반환하거나 중립을 반환합니다.

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

복잡성이 높은 필터 쿼리는 다음과 같은 메시지 "The filter provided in the request does not meet the complexity requirements for source"과(와) 함께 400 오류를 반환합니다.

스토어 검색

전달할 수 있는 속성 중 하나는 Store 매개 변수입니다. 이렇게 하면 저장소의 컨텍스트 내에서 검색할 수 있습니다. 특정 스토어에 항목이 있는지 확인할 수 있을 뿐만 아니라 스토어 항목/콘텐츠의 재정의된 가격을 표시하는 데에도 사용할 수 있습니다. 스토어의 AlternateId을(를) 사용하여 검색할 수도 있습니다. 스토어 사용에 대한 자세한 내용은 여기를 참조하세요.

{
  "Search": "",
  "Filter": "ContentType eq 'weapons'",
  "Store": {
    "Id": "{{StoreID}}"
  },
}