SearchItems

Wichtig

Economy v2 ist jetzt allgemein verfügbar. Unterstützung und Feedback erhalten Sie im PlayFab-Forum.

Die SearchItems API führt eine Suche für den öffentlichen Katalog mit den bereitgestellten Suchparametern aus und gibt eine ausgelagerte Liste von Elementen zurück.

Der einfachste Search Parameter ist eine Nur-Text-Fuzzysuche für die Felder Titel, Beschreibung, Schlüsselwörter und Durchsuchbare Zeichenfolgenanzeigeeigenschaften . Allerdings Filtersind , OrderByund Select OData-Abfragezusätze, die zum Ändern der Suchparameter verwendet werden können. Suchergebnisse können nach einem beliebigen Feld im Suchdokument (ohne Titel und Beschreibung) gefiltert und sortiert werden.

Weitere Informationen zur OData-Abfragesyntax finden Sie hier.

Eine Beispielanforderung SearchItems :

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

Eine Beispielantwort:

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

Fortsetzungstoken

Das ContinuationToken Feld, das von einer Suchantwort zurückgegeben wird, kann an eine Suchanforderung übergeben werden, um mehrere Anzahlen von Ergebnissen zu paginieren.

Anzeigeeigenschaften

Such-, Filter- und Sortiervorgänge können auch für bestimmte DisplayProperties Felder ausgeführt werden, die für die benutzerdefinierte Suche konfiguriert sind. Titel können ihre benutzerdefinierten Such- und Filtereigenschaften in der Einstellung Zuordnungen von Anzeigeeigenschaften im Game Manager konfigurieren.

Wenn Sie ein Feld zu DisplayPropertieshinzufügen, wird ein neuer Index für Sie in der Datenbank erstellt. Nur Dokumente, die nach der Indexerstellung hinzugefügt oder aktualisiert werden, werden einbezogen. Wenn die Display-Eigenschaft auf alle Elemente angewendet werden soll, müssen Sie den gesamten Katalog erneut veröffentlichen.

DateTimeDie Anzeigeeigenschaften , Doubleund Queryable String können abfragbar sein. Diese Eigenschaften können in Den Anweisungen Filter und OrderBy verwendet werden.

Searchable String Anzeigeeigenschaften sind durchsuchbar. Diese Eigenschaften werden mit Fuzzysuche für das Search Feld abgefragt. Durchsuchbare Eigenschaften können nicht in Filter - und OrderBy-Anweisungen verwendet werden.

Titel sind auf fünf Anzeigeeigenschaften jedes Typs beschränkt.

Warnung

Anzeigeeigenschaftenzuordnungen werden als indizierte Liste von Schlüssel-Wert-Paaren gespeichert. Das Löschen vorhandener Anzeigeeigenschaftenzuordnungen kann Indizes verschieben und das Verhalten aller verbleibenden Eigenschaften unterbrechen. Es wird empfohlen, eine zusätzliche Eigenschaft hinzuzufügen, anstatt eine vorhandene Eigenschaft zu löschen oder zu bearbeiten. Sie sollten das Löschen von Eigenschaftenzuordnungen vermeiden, es sei denn, dies ist unbedingt erforderlich.

Filter

Mit dem Parameter Filter können Sie die Sammlung von Elementen filtern, die von der Suchanforderung zurückgegeben werden. Der mit filter angegebene Ausdruck wird für jedes Katalogelement in den Ergebnissen ausgewertet, und nur Elemente, bei denen der Ausdruck als "true" ausgewertet wird, werden eingeschlossen.

Filter unterstützt logische OData-Operatoren und Rangfolge mit Klammern:

• Gleich: "eq"
• Ungleich: "ne"
• Größer als: 'gt'
• Größer als oder Gleich: 'ge'
• Kleiner als: "lt"
• Kleiner als oder Gleich: "le"
• Logisches Und: "and"
• Logisch oder: "or"
• Logische Negation "not"

Filter unterstützt keine arithmetischen Operatoren oder Zeichenfolgenfunktionen.

Im Folgenden sind Filterbeispiele aufgeführt:

Filtern nach ContentType

  "Filter": "ContentType eq 'Sword'"

Filtern mit Konjunktionen

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

Filtern mit NULL-Werten

OData unterstützt einen null Typ zum Filtern.

"Filter": "rating eq null"

Die obige Anforderung gibt alle Elemente ohne Überprüfungen zurück.

Filtern nach Ersteller-ID

Um nach einem bestimmten Ersteller zu filtern, sollten Sie die Syntax verwenden. title_player_account!<ID>

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

Filtern nach Arrayfeldern

Filter unterstützt any() auch das Filtern nach Arrays. Beispiel: alternateIds/any(a: a/value eq ‘StoreOfferId’)

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

Filtern mit Arrays und NULL-Überprüfungen

Der folgende Filter überprüft alle Elemente, die über ein Inhaltsfeld mit Werten ungleich NULL verfügen.

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

Notiz

Standardmäßig gibt Search KEINE Inhalte für Elemente zurück, es sei denn, dies ist mit einer Select-Anweisung angegeben. Wenn die obige Abfrage ohne eine "Select": "contents"'-Anweisung ausgeführt wird, wird der Filter ordnungsgemäß angewendet, aber alle zurückgegebenen Suchergebnisse enthalten leere Inhaltsfelder.

Filtern nach Anzeigeeigenschaften

Das Filtern kann nur mit abfragbaren Anzeigeeigenschaften erfolgen.

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy ist eine durch Trennzeichen getrennte Liste, die zum Sortieren von Suchergebnissen verwendet wird.

  "OrderBy": "rating/average asc"

Sie können eine sekundäre Eigenschaft übergeben, um die Sortierung von "Ties" zu unterbrechen:

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

Katalogelemente ohne sekundären Wert verfügen über ein internes "score"-Attribut, das für breaking ties verwendet wird. Diese Bewertung basiert auf der Speicherreihenfolge in der zugrunde liegenden Datenbank und ändert sich ständig, wenn Elemente hinzugefügt und entfernt werden.

OrderBy unterstützt eine Handvoll OData-Eigenschaften für die Sortierung:

• asc
• desc

Wenn Sie keine Richtung angeben, ist der Standardwert aufsteigend. Wenn das Feld NULL-Werte enthält, werden sie zuerst für asc und zuletzt für descangezeigt. Wenn kein OrderBy Wert übergeben wird, wird ein Standardwert id asc verwendet.

Im Folgenden sind OrderBy-Beispiele aufgeführt:

Sortieren nach Titel

Verwenden Sie den title/<LANG> -Parameter in Kombination mit asc oder desc , um die Bestellpräferenz anzugeben.

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

Verwenden Sie NEUTRAL , um nach den neutralen Zeichenfolgen zu sortieren.

  "OrderBy": "description/NEUTRAL desc"

Sortieren nach Anzeigeeigenschaften

Die Sortierung kann nur mit abfragbaren Anzeigeeigenschaften erfolgen.

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Auswählen

Standardmäßig gibt Search einen umfangreichen Satz von Elementmetadaten zurück:

• Id
• Type
• AlternateIds
• Title (NEUTRAL oder Language Gebietsschema)
• Description (NEUTRAL oder Language Gebietsschema)
• Keywords (NEUTRAL oder Language Gebietsschema)
• ContentType
• Images (Nur Miniaturansicht)
• Tags
• CreationDate
• LastModifiedDate
• CreatorEntityKey (CreatorId in früheren API-Versionen)
• DisplayProperties
• ItemReferences

Standardmäßig werden nur die neutralen Zeichenfolgen zurückgegeben, die in Titel und Beschreibung verwendet werden. Wenn ein Miniaturbild vorhanden ist, wird es standardmäßig zurückgegeben. Jedes Element ist auf nur ein Bild vom Typ "Miniaturansicht" beschränkt.

Mit Select weiteren Feldern können optional innerhalb der ausgelagerten Suchergebnisse zurückgegeben werden, einschließlich Inhaltsmetadaten (Inhalte), Bildern, StartDate, EndDate und dem vollständigen Satz lokalisierter Zeichenfolgen in Titel und Beschreibung. Wenn das Auswahlfeld leer bleibt, sind die Suchergebnisse eine Teilmenge der vollständigen Dokumentmetadaten, um schnellere Ladezeiten zu ermöglichen.

Diese Anforderung würde zusätzlich zu den Inhalten und Bildern die Standardelementmetadaten zurückgeben:

"Select": "contents,images"

Wenn Sie title, descriptionund/oder keywords auswählen, wird der vollständige Satz lokalisierter Zeichenfolgendaten zurückgegeben:

"Select": "title,description,keywords"

Lokalisierung

Ein Gebietsschema kann an den Language Parameter übergeben werden. Das Übergeben eines Gebietsschemas bewirkt, dass alle TitleFelder , Descriptionund Keywords standardmäßig das Gebietsschema oder NEUTRAL zurückgeben, wenn das Element nicht über diese Lokalisierung verfügt.

Eine Beispielanforderung SearchItems mit einem Language Parameter finden Sie oben auf dieser Seite.

Weitere Informationen zur Lokalisierung finden Sie unter Lokalisierung.

Limits

Die Komplexität von Suchfilterabfragen ist pro Anforderung begrenzt. Teure Abfragen können abgelehnt werden, und Titel sollten sicherstellen, dass sie keine übermäßig komplizierten Abfragen versuchen. Im Folgenden finden Sie Beispiele für Abfragen, die der maximalen Komplexität nahe kommen:

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

Filterabfragen mit hoher Komplexität lösen einen Fehler 400 mit einer Meldung aus: "The filter provided in the request does not meet the complexity requirements for source".

Durchsuchen eines Stores

Eine der Eigenschaften, die Sie übergeben können, ist der Store -Parameter. Dadurch können Sie im Kontext eines Speichers suchen. Zusätzlich zur Überprüfung, ob ein Artikel in einem bestimmten Geschäft vorhanden ist, kann es auch verwendet werden, um die überschriebenen Preise der Artikel/Inhalte des Stores anzuzeigen. Sie können auch die AlternateId des Speichers verwenden, um danach zu suchen. Weitere Informationen zur Verwendung von Stores finden Sie hier.

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