SearchItems

Economy v2 ya está disponible con carácter general. Para obtener soporte técnico y enviar comentarios, vaya al foro de PlayFab.

La API SearchItems ejecuta una búsqueda en el catálogo público usando los parámetros de búsqueda proporcionados y devuelve una lista paginada de artículos. En su forma más básica, el parámetro Search es una búsqueda aproximada de texto sin formato en los campos Title, Description, Keywords y Searchable String Display Properties. Sin embargo, Filter, OrderBy y Select son adiciones de consulta OData que se pueden usar para modificar los parámetros de búsqueda. Los resultados de la búsqueda se pueden filtrar y ordenar por cualquier campo del documento de búsqueda (salvo Title y Description). Puede encontrar más información sobre la sintaxis de consulta de OData aquí Un ejemplo de solicitud de SearchItems:

{
  "Search": "Pirates",
  "Filter": "Tags/any(t:t eq 'desert') and ContentType eq 'map'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2,
  "Language": "en-GB"
}

Una respuesta de ejemplo:

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
               <item metadata> 
            }
        ],
      "ContinuationToken": "MTA="
    }
}

Tokens de continuación

El campo ContinuationToken que se devuelve en una respuesta de búsqueda se puede pasar en una solicitud de búsqueda para paginar entre varios conjuntos de resultados.

Propiedades de visualización

Las búsquedas, los filtros y las ordenaciones también se pueden realizar en campos específicos de DisplayProperties configurados para búsqueda personalizada. Los títulos pueden configurar sus propiedades personalizadas de búsqueda y filtrado en la configuración Display Properties Mappings de Game Manager. Cuando agrega un campo a DisplayProperties, se crea un nuevo índice en la base de datos. Solo se incluirán los documentos agregados o actualizados después de la creación del índice. Si necesita que la propiedad de visualización se aplique a todos los artículos, debe volver a publicar el catálogo completo. Las propiedades de visualización DateTime, Double y Queryable String son consultables; estas propiedades se pueden usar en las instrucciones Filter y OrderBy. Las propiedades de visualización Searchable String son de búsqueda; estas propiedades se consultan con búsqueda aproximada en el campo Search. Las propiedades de búsqueda no se pueden usar en las instrucciones Filter y OrderBy. Los títulos están limitados a cinco propiedades de visualización de cada tipo.

Las asignaciones de propiedades de visualización se almacenan como una lista indexada de pares clave-valor. Eliminar asignaciones de propiedades de visualización existentes puede desplazar los índices y romper el comportamiento de todas las propiedades restantes. Se sugiere agregar una propiedad adicional en lugar de eliminar o editar una existente, y debería evitar eliminar asignaciones de propiedades a menos que sea absolutamente necesario

Filter

El parámetro Filter le permite filtrar la colección de artículos devuelta por la solicitud de búsqueda. La expresión especificada con filter se evalúa con cada artículo del catálogo en los resultados, y solo se incluyen los artículos en los que la expresión se evalúa como “true”. Filter admite los operadores lógicos de OData y la precedencia mediante paréntesis:

Igual: ‘eq’
No igual: ‘ne’
Mayor que: ‘gt’
Mayor o igual que: ‘ge’
Menor que: ‘lt’
Menor o igual que: ‘le’
Y lógico: ‘and’
O lógico: ‘or’
Negación lógica: ‘not’

Filter no admite operadores aritméticos ni funciones de cadena. Los siguientes son ejemplos de Filter:

Filtrado por ContentType

  "Filter": "ContentType eq 'Sword'"

Filtrado con conjunciones

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

Filtrado con valores null

OData admite un tipo null para el filtrado

"Filter": "rating eq null"

La solicitud anterior devuelve todos los artículos sin reseñas

Filtrado por identificador de creador

Para filtrar por un creador específico, debe usar la sintaxis title_player_account!<ID>

  "Filter": "creatorId eq 'title_player_account!C88F55C6A734B1DC'"

Filtrado por campos de matriz

Filter también admite any() para filtrar en matrices. Por ejemplo: alternateIds/any(a: a/value eq 'StoreOfferId')

  "Filter": "tags/any(t: t eq 'featured')"

Filtrado con matrices y comprobaciones de null

El filtro siguiente comprobará si hay artículos que tengan un campo contents con valores no nulos

  "Filter": "contents/any(content: content ne null)"

De forma predeterminada, la búsqueda NO devolverá el contenido de los artículos a menos que se especifique con una instrucción Select. Si la consulta anterior se ejecuta sin una instrucción `“Select”: “contents”“, aplicará correctamente el filtro, pero todos los resultados de búsqueda devueltos tendrán campos de contenido vacíos

Filtrado por propiedades de visualización

El filtrado solo se puede realizar con propiedades de visualización consultables

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy es una lista separada por comas que se usa para ordenar los resultados de la búsqueda.

  "OrderBy": "rating/average asc"

Puede pasar una propiedad secundaria para romper los “empates” de ordenación:

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

Los artículos del catálogo sin un valor secundario tienen un atributo interno de “puntuación” que se usa para romper los empates. Esa puntuación se basa en el orden de almacenamiento en la base de datos subyacente y cambia constantemente a medida que se agregan y eliminan artículos. OrderBy admite un puñado de propiedades de OData para la ordenación:

asc
desc

Si no especifica una dirección, el valor predeterminado es ascendente. Si hay valores null en el campo, aparecen primero para asc y al final para desc. Si no se pasa ningún valor de OrderBy, se usa un valor predeterminado de id asc. Los siguientes son ejemplos de OrderBy:

Ordenación por título

Use el parámetro title/<LANG> combinado con asc o desc para indicar la preferencia de orden.

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

Use NEUTRAL para ordenar por las cadenas neutras

  "OrderBy": "description/NEUTRAL desc"

Ordenación por propiedades de visualización

La ordenación solo se puede realizar con propiedades de visualización consultables

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

De forma predeterminada, la búsqueda devuelve un conjunto completo de metadatos del artículo:

Id
Type
AlternateIds
Title (NEUTRAL o configuración regional de Language)
Description (NEUTRAL o configuración regional de Language)
Keywords (NEUTRAL o configuración regional de Language)
ContentType
Images (solo miniatura)
Tags
CreationDate
LastModifiedDate
CreatorEntityKey (CreatorId en versiones anteriores de la API)
DisplayProperties
ItemReferences

De forma predeterminada solo se devuelven las cadenas neutras usadas en el título y la descripción. Si existe una imagen en miniatura, se devuelve de forma predeterminada. Cada artículo está limitado a una sola imagen de tipo “Thumbnail”. Con Select se pueden devolver opcionalmente más campos dentro de los resultados de búsqueda paginados, incluidos los metadatos del contenido (contents), las imágenes, StartDate, EndDate y el conjunto completo de cadenas localizadas en el título y la descripción. Si el campo select se deja vacío, los resultados de la búsqueda son un subconjunto de los metadatos completos del documento, para facilitar tiempos de carga más rápidos. Esta solicitud devolvería los metadatos predeterminados del artículo además del contenido y las imágenes:

"Select": "contents,images"

Seleccionar title, description o keywords devolverá el conjunto completo de datos de cadenas localizadas:

"Select": "title,description,keywords"

Localización

Se puede pasar una configuración regional en el parámetro Language. Pasar una configuración regional hace que todos los campos Title, Description y Keywords devuelvan esa configuración regional de forma predeterminada, o NEUTRAL si el artículo no tiene esa localización. Puede encontrar un ejemplo de solicitud de SearchItems con un parámetro Language en la parte superior de esta página. Para obtener más información sobre la localización, consulte Localización.

Límites

La complejidad de las consultas de filtro de búsqueda está limitada por solicitud. Las consultas costosas pueden rechazarse, y los títulos deben asegurarse de no intentar consultas demasiado complicadas. Los siguientes son ejemplos de consultas cercanas a la complejidad máxima:

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

Las consultas de filtro de alta complejidad producen un error 400 con el mensaje: "The filter provided in the request does not meet the complexity requirements for source".

Búsqueda en una tienda

Una de las propiedades que puede pasar es el parámetro Store. Esto le permite buscar dentro del contexto de una tienda. Además de poder comprobar si un artículo existe en una tienda concreta, también se puede usar para mostrar los precios invalidados de los artículos o contenidos de la tienda. También puede usar el AlternateId de la tienda para buscarla. Obtenga más información sobre el uso de tiendas aquí

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

​SearchItems

​Tokens de continuación

​Propiedades de visualización

​Filter

​Filtrado por ContentType

​Filtrado con conjunciones

​Filtrado con valores null

​Filtrado por identificador de creador

​Filtrado por campos de matriz

​Filtrado con matrices y comprobaciones de null

​Filtrado por propiedades de visualización

​OrderBy

​Ordenación por título

​Ordenación por propiedades de visualización

​Select

​Localización

​Límites

​Búsqueda en una tienda

SearchItems

Tokens de continuación

Propiedades de visualización

Filter

Filtrado por ContentType

Filtrado con conjunciones

Filtrado con valores null

Filtrado por identificador de creador

Filtrado por campos de matriz

Filtrado con matrices y comprobaciones de null

Filtrado por propiedades de visualización

OrderBy

Ordenación por título

Ordenación por propiedades de visualización

Select

Localización

Límites

Búsqueda en una tienda