SearchItems

O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o Fórum do PlayFab.

A API SearchItems executa uma pesquisa no Catálogo público usando os parâmetros de pesquisa fornecidos e retorna uma lista paginada de itens. Em sua forma mais básica, o parâmetro Search é uma pesquisa difusa em texto simples nos campos Title, Description, Keywords e Searchable String Display Properties. No entanto, Filter, OrderBy e Select são adições de consulta do OData que podem ser usadas para alterar os parâmetros de pesquisa. Os resultados da pesquisa podem ser filtrados e ordenados por qualquer campo do documento de pesquisa (exceto Title e Description). Mais informações sobre a sintaxe de consulta do OData podem ser encontradas aqui Um exemplo de solicitação SearchItems:

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

Um exemplo de resposta:

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

Tokens de continuação

O campo ContinuationToken retornado em uma resposta de pesquisa pode ser passado para uma solicitação de pesquisa para paginar por vários conjuntos de resultados.

Propriedades de exibição

Pesquisas, filtros e ordenações também podem ser feitos em campos específicos de DisplayProperties configurados para pesquisa personalizada. Os títulos podem configurar suas propriedades personalizadas de pesquisa e filtro na configuração Display Properties Mappings no Game Manager.

Captura de tela de Display Properties no Game Manager

Quando você adiciona um campo a DisplayProperties, um novo índice é criado para você no banco de dados. Somente documentos adicionados ou atualizados após a criação do índice serão incluídos. Se você precisar que a propriedade de exibição se aplique a todos os itens, será necessário republicar o catálogo inteiro. As propriedades de exibição DateTime, Double e Queryable String são consultáveis; essas propriedades podem ser usadas em instruções Filter e OrderBy. As propriedades de exibição Searchable String são pesquisáveis; essas propriedades são consultadas com pesquisa difusa no campo Search. Propriedades pesquisáveis não podem ser usadas em instruções Filter e OrderBy. Os títulos estão limitados a cinco propriedades de exibição de cada tipo.

Os mapeamentos de propriedades de exibição são armazenados como uma lista indexada de pares chave-valor. Excluir mapeamentos de propriedades de exibição existentes pode deslocar os índices e interromper o comportamento de todas as propriedades restantes. Recomenda-se adicionar uma propriedade adicional em vez de excluir ou editar uma existente, e você deve evitar excluir mapeamentos de propriedades, a menos que seja absolutamente necessário

Filter

O parâmetro Filter permite filtrar a coleção de itens retornados pela solicitação de pesquisa. A expressão especificada com o filtro é avaliada em cada item do catálogo nos resultados, e somente os itens em que a expressão é avaliada como “true” são incluídos. Filter dá suporte a operadores lógicos do OData e precedência usando parênteses:

Igual: ‘eq’
Diferente: ‘ne’
Maior que: ‘gt’
Maior ou igual: ‘ge’
Menor que: ‘lt’
Menor ou igual: ‘le’
E lógico: ‘and’
Ou lógico: ‘or’
Negação lógica ‘not’

Filter não dá suporte a operadores aritméticos nem a funções de cadeia de caracteres. Veja a seguir exemplos de Filter:

Filtrar por ContentType

  "Filter": "ContentType eq 'Sword'"

Filtrar com conjunções

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

Filtrar com valores nulos

O OData dá suporte a um tipo null para filtragem

"Filter": "rating eq null"

A solicitação acima retorna todos os itens sem avaliações

Filtrar por ID do criador

Para filtrar por um criador específico, você deve usar a sintaxe title_player_account!<ID>

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

Filtrar por campos de matriz

Filter também dá suporte a any() para filtrar em matrizes. Por exemplo: alternateIds/any(a: a/value eq 'StoreOfferId')

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

Filtrar com matrizes e verificações de nulo

O filtro abaixo verificará se há itens que tenham um campo contents com valores não nulos

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

Por padrão, a pesquisa NÃO retornará o conteúdo dos itens, a menos que especificado com uma instrução Select. Se a consulta acima for executada sem uma instrução `“Select”: “contents”“, ela aplicará o filtro corretamente, mas todos os resultados de pesquisa retornados terão campos de conteúdo vazios

Filtrar por propriedades de exibição

A filtragem só pode ser feita com propriedades de exibição consultáveis

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy é uma lista separada por vírgulas usada para classificar os resultados da pesquisa.

  "OrderBy": "rating/average asc"

Você pode passar uma propriedade secundária para desempatar a classificação:

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

Itens do catálogo sem um valor secundário têm um atributo interno de ‘pontuação’ usado para desempates. Essa pontuação se baseia na ordem de armazenamento no banco de dados subjacente e muda constantemente à medida que itens são adicionados e removidos. OrderBy dá suporte a algumas propriedades do OData para ordenação:

asc
desc

Se você não especificar uma direção, o padrão será crescente. Se houver valores nulos no campo, eles aparecerão primeiro para asc e por último para desc. Se nenhum valor de OrderBy for passado, um valor padrão id asc será usado. Veja a seguir exemplos de OrderBy:

Classificar por título

Use o parâmetro title/<LANG> combinado com asc ou desc para indicar a preferência de ordem.

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

Use NEUTRAL para ordenar pelas cadeias de caracteres neutras

  "OrderBy": "description/NEUTRAL desc"

Classificar por propriedades de exibição

A classificação só pode ser feita com propriedades de exibição consultáveis

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

Por padrão, a pesquisa retorna um conjunto completo de metadados do item:

Id
Type
AlternateIds
Title (NEUTRAL ou localidade de Language)
Description (NEUTRAL ou localidade de Language)
Keywords (NEUTRAL ou localidade de Language)
ContentType
Images (somente miniatura)
Tags
CreationDate
LastModifiedDate
CreatorEntityKey (CreatorId em versões anteriores da API)
DisplayProperties
ItemReferences

Somente as cadeias de caracteres neutras usadas no título e na descrição são retornadas por padrão. Se existir uma imagem de miniatura, ela será retornada por padrão. Cada item está limitado a apenas uma imagem do tipo “Thumbnail”. Com Select, mais campos podem ser retornados opcionalmente nos resultados de pesquisa paginados, incluindo metadados de conteúdo (contents), imagens, StartDate, EndDate e o conjunto completo de cadeias de caracteres localizadas no título e na descrição. Se o campo select for deixado vazio, os resultados da pesquisa serão um subconjunto dos metadados completos do documento, para facilitar tempos de carregamento mais rápidos. Esta solicitação retornaria os metadados padrão do item além do conteúdo e das imagens:

"Select": "contents,images"

Selecionar title, description e/ou keywords retornará o conjunto completo de dados de cadeias de caracteres localizadas:

"Select": "title,description,keywords"

Localização

Uma localidade pode ser passada no parâmetro Language. Passar uma localidade faz com que todos os campos Title, Description e Keywords retornem essa localidade por padrão, ou NEUTRAL se o item não tiver essa localização. Um exemplo de solicitação SearchItems com um parâmetro Language pode ser encontrado no início desta página. Para obter mais informações sobre localização, consulte Localização.

Limites

A complexidade das consultas de filtro de pesquisa é limitada por solicitação. Consultas caras podem ser rejeitadas, e os títulos devem garantir que não estão tentando consultas excessivamente complicadas. Veja a seguir exemplos de consultas próximas da complexidade 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

Consultas de filtro de alta complexidade geram um erro 400 com a mensagem: "The filter provided in the request does not meet the complexity requirements for source".

Pesquisar em uma loja

Uma das propriedades que você pode passar é o parâmetro Store. Isso permite pesquisar no contexto de uma loja. Além de permitir verificar se um item existe em uma loja específica, ele também pode ser usado para exibir os preços substituídos dos itens/conteúdos da loja. Você também pode usar o AlternateId da loja para pesquisá-la. Saiba mais sobre como usar lojas aqui

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

​SearchItems

​Tokens de continuação

​Propriedades de exibição

​Filter

​Filtrar por ContentType

​Filtrar com conjunções

​Filtrar com valores nulos

​Filtrar por ID do criador

​Filtrar por campos de matriz

​Filtrar com matrizes e verificações de nulo

​Filtrar por propriedades de exibição

​OrderBy

​Classificar por título

​Classificar por propriedades de exibição

​Select

​Localização

​Limites

​Pesquisar em uma loja

SearchItems

Tokens de continuação

Propriedades de exibição

Filter

Filtrar por ContentType

Filtrar com conjunções

Filtrar com valores nulos

Filtrar por ID do criador

Filtrar por campos de matriz

Filtrar com matrizes e verificações de nulo

Filtrar por propriedades de exibição

OrderBy

Classificar por título

Classificar por propriedades de exibição

Select

Localização

Limites

Pesquisar em uma loja