Freigeben über

Inventar

  • Artikel

Wichtig

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

Mit den PlayFab-Bestands-APIs können Sie Ihre Spielerbestände und Bestandsdaten verwalten und speichern. Features wie Stapel und Sammlungen ermöglichen eine flexible Strukturierung von Spielerbeständen und ermöglichen es diesem System, mit jedem Spiel zu arbeiten.

Verwalten von Spielerinventaren

Die folgenden APIs werden verwendet, um Elemente im Bestand eines Spielers hinzuzufügen, zu entfernen, zu aktualisieren und zu löschen. Der aktuelle Grenzwert beträgt 10.000 Elemente, und Sie erhalten eine Fehlermeldung, wenn Sie diesen Wert überschreiten.

Abrufen des Inventars eines Spielers

  1. Navigieren Sie im Game Manager zu Players
  2. Wählen Sie den Player aus, den Sie anzeigen oder erstellen New Playermöchten, und wechseln Sie dann zu Inventory (V2)

Weitere Informationen zur Verwendung CollectionIdund Verwendung mehrerer Inventare pro Spieler finden Sie hier.

Fortsetzungstoken

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

Hinzufügen von Bestandselementen

Die AddInventoryItems API wird verwendet, um elemente direkt zum Bestand eines bestimmten Spielers hinzuzufügen. Es verwendet die EntityIdParameter ,ItemId, und Amount fügt das angegebene Element dem Inventar eines Spielers hinzu.

Eine Beispielanforderung AddInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Subtrahieren von Bestandselementen

Die SubtractInventoryItems API wird verwendet, um ein Element im Bestand eines Spielers direkt um einen bestimmten Betrag zu reduzieren. Er verwendet die EntityIdParameter ,ItemId, und Amount und entfernt die angegebene Menge des Elements. Diese API löst einen Fehler aus, wenn Sie versuchen, mehr als den derzeit verfügbaren Betrag zu entfernen.

Eine Beispielanforderung SubtractInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Aktualisieren von Bestandselementen

Die UpdateInventoryItems API wird verwendet, um ein Element im Bestand eines Spielers direkt auf einen bestimmten Betrag festzulegen. Er verwendet die EntityIdParameter ,ItemId, und Amount legt die angegebene Menge des Elements fest. Diese API kann verwendet werden, um die Menge eines Elements zu erhöhen oder zu verringern und dem Bestand eines Spielers Elemente hinzuzufügen, wenn das Element nicht vorhanden ist.

Eine Beispielanforderung UpdateInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "Amount": 10
    }
}

Löschen von Bestandselementen

Die DeleteInventoryItems API wird verwendet, um einen gesamten Stapel von Elementen aus dem Bestand eines Spielers zu löschen.

Eine Beispielanforderung DeleteInventoryItems :

{
   "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
}

Kauf von Bestandsartikeln

Die PurchaseInventoryItems API verwendet den katalogdefinierten Preis des Elements und zieht die Kosten für den Bestand des Spielers ab und tauscht ihn mit der gewünschten Menge des Elements aus. Sie müssen den Item Kauf und die des Amount Artikels, den Sie kaufen möchten, angeben.

Es gibt einige wichtige Parameter, die für die PurchaseInventoryItems API spezifisch sind:

  • PriceAmounts ist eine Liste von Elementen und Beträgen, die die Preise pro Artikel des Artikels sind. Diese Preise müssen mit einem Wert übereinstimmen, der im Katalog oder im angegebenen Store konfiguriert ist.
  • StoreId ist ein optionaler Parameter des Stores, in dem der Artikel gekauft werden soll. Weitere Informationen zu Stores finden Sie hier.

Eine Beispielanforderung PurchaseInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
}

Lagerbestandselemente übertragen

Die TransferInventoryItems API kann auf drei verschiedene Arten verwendet werden.

  1. Zum Übertragen von Gegenständen zwischen Spielern (z. B. gibt Spieler A drei Äpfel an Spieler B)
  2. Zum Übertragen von Gegenständen zwischen den Inventarsammlungen eines einzelnen Spielers (z. B. verschiebt Spieler A sein Long-Schwert aus seinem Inventar der Assistentenfiguren in das Inventar seiner Kriegerfiguren)
  3. Zum Übertragen von Gegenständen innerhalb des Inventars eines einzelnen Spielers zum Erstellen, Entfernen und Bearbeiten von Elementstapeln (z. B. teilt Spieler A seinen Stapel von 10 Goldmünzen in zwei Stapel mit drei und sieben Goldmünzen auf)

Die GivingItem Parameter und Amount werden verwendet, um den Betrag und das zu übertragende Element darzustellen. stellt ReceivingItem das Elementziel für das Konto des empfangenden Spielers dar. Sowohl der -Parameter als auch der GivingItem -Parameter sind InventoryItemReference Objekte, die das Id -Element und das StackId-Element ReceivingItem enthalten. Sowohl als ReceivingItem auch GivingItem können leer sein, um Übertragungen zu verarbeiten, bei denen eine Entität keine Elemente überträgt. Sofern nicht angegeben, werden alle Elemente für default das StackId festgelegt, wenn sie dem Inventar eines Spielers hinzugefügt/übertragen werden.

1. Übertragung zwischen Spielern

Für eine Übertragung zwischen Spielern sollten und GivingEntityReceivingEntity angegeben werden, die den Spieler darstellen, der die Gegenstände überträgt, bzw. den Spieler, der die Gegenstände empfängt.

Eine Beispielanforderung TransferInventoryItems zwischen Spielern:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "DEFG98765432"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 1
}

2. Übertragung zwischen Sammlungen

Für eine Übertragung zwischen Sammlungen sollten und GivingCollectionIdReceivingCollectionId festgelegt werden, die die Bestandssammlungs-ID darstellt, von der bzw. an die die Anforderung übertragen wird.

Eine Beispielanforderung TransferInventoryItems zwischen Sammlungen:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "main_character",
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10
}

Die obige Anforderung überträgt 10 des Elements aus der Sammlung des Spielers default in seine main_character Sammlung.

Weitere Informationen zu Sammlungen finden Sie hier.

3. Übertragung zwischen Stapeln

Für eine Übertragung zwischen Stapeln sollten die StackId für und GivingItem die ReceivingItem der Anforderung angegeben werden.

Eine Beispielanforderung TransferInventoryItems zwischen Stapeln:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10
}

Die obige Anforderung überträgt 10 des Elements aus dem Stapel des Spielers default in seinen MyNewStack Stapel.

Weitere Informationen zu Stapeln finden Sie hier.

ExecuteInventoryOperations-API

Sie können die ExecuteInventoryOperations API verwenden, um mehrere Inventurvorgänge in einer einzelnen Anforderung zu batchen. Vorgänge werden in der angegebenen Anforderungsreihenfolge ausgeführt, und wenn ein Vorgang nicht ausgeführt werden kann, wird der gesamte Satz von Vorgängen abgebrochen.

Der ExecuteInventoryOperations akzeptiert einen Operation Parameter, bei dem es sich um eine Liste von Vorgängen handelt. Es können maximal zehn Vorgänge in der Operation Liste vorhanden sein, aber Vorgangstypen können wiederholt werden (z. B. sind 10 Add-Vorgänge gültig). Es gibt auch eine Beschränkung auf 250 Elemente, die in einer einzelnen Anforderung geändert/hinzugefügt werden können. Das Hinzufügen eines Bündels mit 50 Elementen zählt beispielsweise als 50 geänderte Elemente. Die gültigen Vorgangstypen sind:

  • Hinzufügen
  • Shapes voneinander abziehen
  • Update
  • Kaufen
  • Übertragung*
  • Löschen

Notiz

*Innerhalb eines Batches werden nur Übertragungen mit einer einzelnen Sammlung unterstützt.

Eine Beispielanforderung ExecuteInventoryOperations :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Operations": [
        {
            "Update": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                    "Amount": 10
                }
            }
        },
        {
            "Subtract": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                },
                "Amount": 5
            }
        }
    ]
}

Idempotenz

Beim Aufrufen von Bestands-APIs können Sie eine IdempotencyId übergeben, die in Situationen verwendet werden kann, in denen wiederholte Aufrufe zu Fallback- oder Redundanzzwecken erfolgen. Wenn mehrere API-Aufrufe denselben IdempotencyIdaufweisen, stellt das System sicher, dass nur eine dieser Anforderungen verarbeitet wird.

Beispielsweise kann die folgende PurchaseItem API-Anforderung mehrmals aufgerufen werden, aber da alle Anforderungen denselben IdempotencyIdhaben, wird nur ein einzelner Kauf für den Bestand dieses Spielers getätigt.

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
    "IdempotencyId": "ABC123"
}

IdempotencyId werden 14 Tage lang gespeichert und erzwungen, danach kann die ID wieder verwendet werden.

Notiz

Die Verwendung von für IdempotencyId verschiedene Anforderungstypen führt zu einem Konflikt und löst einen Fehler aus.

Anzeigeeigenschaften

Anzeigeeigenschaften sind benutzerdefinierte Elementeigenschaften, die Elementen und Elementstapeln in Spielerbeständen hinzugefügt werden können.

Diese Eigenschaften können durch AddInventoryItems-, -, TransferInventoryItemsPurchaseInventoryItems- und UpdateInventoryItems -Vorgänge hinzugefügt werden.

Hinzufügen von Eigenschaften zu neuen Stapeln/Elementen

Für die AddInventoryItemsPurchaseInventoryItems APIs und TransferInventoryItems können Anzeigeeigenschaften nur hinzugefügt werden, wenn ein neuer Stapel erstellt wird. Um Anzeigeeigenschaften für neue Elemente festzulegen, muss der NewStackValues Parameter in der API-Anforderung festgelegt werden.

Eine Beispielanforderung AddInventoryItems mit NewStackValues:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}

Weitere Informationen zu Stapeln finden Sie hier.

Aktualisieren von Eigenschaften auf vorhandene Stapel/Elemente

Um Anzeigeeigenschaften für vorhandene Elemente zu aktualisieren, kann die UpdateInventoryItems API verwendet werden, um Eigenschaften direkt zu ändern.

Eine Beispielanforderung UpdateInventoryItems mit DisplayProperties:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack",
        "Amount": 15,
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": false,
            "Rarity": "Epic"
        }
    }
}