Inventario

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

Las API de inventario de PlayFab le ofrecen la capacidad de administrar y almacenar los inventarios de los jugadores y sus datos de inventario. Características como las pilas y las colecciones permiten flexibilidad a la hora de estructurar los inventarios de los jugadores y hacen que este sistema funcione con cualquier juego

Administración de los inventarios de los jugadores

Las siguientes API se usan para ayudar a agregar, quitar, actualizar y eliminar artículos del inventario de un jugador. El límite actual es de 10 000 artículos y obtendrá un error si lo supera.

Obtención del inventario de un jugador

Game Manager

En Game Manager, vaya a Players
Seleccione el jugador que quiere ver o cree un New Player y, a continuación, vaya a Inventory (V2)

API

Puede usar GetInventoryItems para obtener el inventario de un jugador. Los jugadores solo pueden acceder a su propio inventario y manipularlo. Las entidades de título pueden pasar un parámetro Entity para indicar a qué inventario de jugador quieren acceder. Un ejemplo de solicitud GetInventoryItems:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
  },
  "CollectionId": "main_character",
  "Count": 15,
  "ContinuationToken": "abc="
}

Puede encontrar más información sobre el uso de CollectionId y sobre tener varios inventarios por jugador aquí.

Tokens de continuación

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

Adición de artículos al inventario

La API AddInventoryItems se usa para agregar directamente artículos al inventario de un jugador específico. Acepta los parámetros EntityId, ItemId y Amount, y agrega el artículo indicado al inventario de un jugador Un ejemplo de solicitud AddInventoryItems:

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

Sustracción de artículos del inventario

La API SubtractInventoryItems se usa para reducir directamente un artículo del inventario de un jugador en una cantidad específica. Acepta los parámetros EntityId, ItemId y Amount, y quita la cantidad indicada del artículo. Esta API generará un error si se intenta quitar más de la cantidad disponible actualmente. Un ejemplo de solicitud SubtractInventoryItems:

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

Actualización de artículos del inventario

La API UpdateInventoryItems se usa para establecer directamente un artículo del inventario de un jugador en una cantidad específica. Acepta los parámetros EntityId, ItemId y Amount, y establece la cantidad indicada del artículo. Esta API se puede usar tanto para aumentar como para reducir la cantidad de un artículo, y para agregar artículos al inventario de un jugador si el artículo no existe. Un ejemplo de solicitud UpdateInventoryItems:

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

Eliminación de artículos del inventario

La API DeleteInventoryItems se usa para eliminar una pila completa de artículos del inventario de un jugador. Un ejemplo de solicitud DeleteInventoryItems:

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

Compra de artículos de inventario

La API PurchaseInventoryItems usa el precio del artículo definido en el catálogo, deduce el costo del inventario del jugador y lo intercambia por la cantidad deseada del artículo. Debe especificar el Item que quiere comprar y el Amount del artículo que quiere comprar. Hay algunos parámetros clave específicos de la API PurchaseInventoryItems:

PriceAmounts es una lista de artículos y cantidades que son los precios por artículo del artículo. Estos precios deben coincidir con un valor configurado en el catálogo o en la tienda especificada.
StoreId es un parámetro opcional de la tienda desde la que se va a comprar el artículo. Puede encontrar más información sobre las tiendas aquí

Un ejemplo de solicitud PurchaseInventoryItems:

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

La API PurchaseInventoryItems se usa para compras con monedas virtuales. Para compras con dinero real a través de marketplaces externos (Apple App Store, Google Play, Steam, Microsoft Store), use las API de canje correspondientes (como RedeemAppleAppStoreInventoryItems, RedeemGooglePlayInventoryItems, RedeemSteamInventoryItems o RedeemMicrosoftStoreInventoryItems). Estas API validan el recibo de compra con el marketplace y conceden los artículos al inventario del jugador. Para obtener más información, consulte Canje en marketplaces.

Paquetes

Cuando se compra un paquete (mediante PurchaseInventoryItems o una API de canje de marketplace), el paquete se desempaqueta automáticamente en el inventario del jugador. Los artículos individuales a los que se hace referencia en las ItemReferences del paquete se conceden directamente: el paquete en sí no aparece como un artículo en el inventario del jugador. Por ejemplo, al comprar un paquete que contiene 2 Laser Sword y 2 Laser Gun, esos artículos se conceden individualmente. El costo en moneda virtual definido en las PriceOptions del paquete se deduce del inventario del jugador como parte de la transacción. Los paquetes que están vinculados a productos de marketplace mediante AlternateIds siguen el mismo comportamiento de desempaquetado cuando se canjean. Para obtener más información sobre la creación de paquetes, consulte Paquetes.

Transferencia de artículos de inventario

La API TransferInventoryItems se puede usar de tres maneras diferentes.

Para transferir artículos entre jugadores (por ejemplo, el jugador A da tres manzanas al jugador B)
Para transferir artículos entre las colecciones de inventario de un mismo jugador (por ejemplo, el jugador A mueve su espada larga del inventario de su personaje mago al inventario de su personaje guerrero)
Para transferir artículos dentro del inventario de un mismo jugador con el fin de crear, quitar y manipular pilas de artículos (por ejemplo, el jugador A divide su pila de 10 monedas de oro en dos pilas de tres y siete monedas de oro)

Los parámetros GivingItem y Amount se usan para representar la cantidad y el artículo que se transfiere. ReceivingItem representa el destino del artículo en la cuenta del jugador receptor. Tanto el parámetro GivingItem como ReceivingItem son objetos InventoryItemReference que contienen el Id del artículo y el StackId. Tanto GivingItem como ReceivingItem pueden estar vacíos para gestionar transferencias en las que una entidad no transfiere artículos. A menos que se especifique lo contrario, todos los artículos se establecen en default para el StackId cuando se agregan o transfieren al inventario de un jugador.

1. Transferencia entre jugadores

Para una transferencia entre jugadores, se deben especificar GivingEntity y ReceivingEntity, que representan al jugador que transfiere los artículos y al jugador que los recibe, respectivamente. Un ejemplo de solicitud TransferInventoryItems entre jugadores:

{
    "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. Transferencia entre colecciones

Para una transferencia entre colecciones, se deben establecer GivingCollectionId y ReceivingCollectionId, que representan el identificador de la colección de inventario desde la que se transfiere y a la que se transfiere la solicitud, respectivamente. Un ejemplo de solicitud TransferInventoryItems entre colecciones:

{
    "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
}

La solicitud anterior transfiere 10 unidades del artículo de la colección default del jugador a su colección main_character. Puede encontrar más información sobre las colecciones aquí.

3. Transferencia entre pilas

Para una transferencia entre pilas, se debe especificar el StackId del GivingItem y del ReceivingItem de la solicitud. Un ejemplo de solicitud TransferInventoryItems entre pilas:

{
    "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
}

La solicitud anterior transfiere 10 unidades del artículo de la pila default del jugador a su pila MyNewStack. Puede encontrar más información sobre las pilas aquí.

API ExecuteInventoryOperations

Puede usar la API ExecuteInventoryOperations para agrupar por lotes varias operaciones de inventario en una sola solicitud. Las operaciones se realizarán en el orden especificado en la solicitud y, si una operación no se puede realizar, se cancela todo el conjunto de operaciones. ExecuteInventoryOperations acepta un parámetro Operation que es una lista de operaciones. Puede haber como máximo 50 operaciones en la lista Operation, pero los tipos de operación pueden repetirse (por ejemplo, 10 operaciones Add son válidas). También hay un límite de 300 artículos que se pueden modificar o agregar en una sola solicitud. Por ejemplo, agregar un paquete con 50 artículos cuenta como 50 artículos modificados. Los tipos de operación válidos son:

Add
Subtract
Update
Purchase
Transfer*
Delete

*Dentro de un lote solo se admiten transferencias dentro de una única colección.

Un ejemplo de solicitud 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
            }
        }
    ]
}

Idempotencia

Al llamar a las API de inventario, puede pasar un IdempotencyId que se puede usar en situaciones en las que se realizan llamadas repetitivas por motivos de reserva o redundancia. Si varias llamadas a la API tienen el mismo IdempotencyId, el sistema garantizará que solo se procese una de esas solicitudes. Por ejemplo, la siguiente solicitud de la API PurchaseItem se puede llamar varias veces pero, como todas las solicitudes tienen el mismo IdempotencyId, solo se realizará una única compra en el inventario de ese jugador.

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

Los IdempotencyId se almacenan y se aplican durante 14 días, tras los cuales el identificador se puede volver a usar.

Usar el mismo IdempotencyId para diferentes tipos de solicitud provocará un conflicto y generará un error.

ETags y control de simultaneidad

Las API de escritura de inventario admiten el control de simultaneidad optimista mediante ETags y encabezados HTTP. Para obtener todos los detalles, consulte ETags de inventario.

Propiedades de presentación

Las propiedades de presentación son propiedades de artículo personalizadas que se pueden agregar a los artículos y a las pilas de artículos de los inventarios de los jugadores. Estas propiedades se pueden agregar mediante las operaciones AddInventoryItems, PurchaseInventoryItems, TransferInventoryItems y UpdateInventoryItems.

Adición de propiedades a pilas o artículos nuevos

Para las API AddInventoryItems, PurchaseInventoryItems y TransferInventoryItems, las propiedades de presentación solo se pueden agregar cuando se crea una pila nueva. Para establecer propiedades de presentación en artículos nuevos, se debe establecer el parámetro NewStackValues en la solicitud de la API. Un ejemplo de solicitud AddInventoryItems con 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"
        }
    }
}

Puede encontrar más información sobre las pilas aquí.

Actualización de propiedades en pilas o artículos existentes

Para actualizar las propiedades de presentación de artículos existentes, se puede usar la API UpdateInventoryItems para modificar directamente las propiedades. Un ejemplo de solicitud UpdateInventoryItems con 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"
        }
    }
}

​Inventario

​Administración de los inventarios de los jugadores

​Obtención del inventario de un jugador

​Game Manager

​API

Tokens de continuación

​Adición de artículos al inventario

​Sustracción de artículos del inventario

​Actualización de artículos del inventario

​Eliminación de artículos del inventario

​Compra de artículos de inventario

​Paquetes

​Transferencia de artículos de inventario

​1. Transferencia entre jugadores

​2. Transferencia entre colecciones

​3. Transferencia entre pilas

​API ExecuteInventoryOperations

​Idempotencia

​ETags y control de simultaneidad

​Propiedades de presentación

​Adición de propiedades a pilas o artículos nuevos

​Actualización de propiedades en pilas o artículos existentes

Inventario

Administración de los inventarios de los jugadores

Obtención del inventario de un jugador

Game Manager

API

Adición de artículos al inventario

Sustracción de artículos del inventario

Actualización de artículos del inventario

Eliminación de artículos del inventario

Compra de artículos de inventario

Paquetes

Transferencia de artículos de inventario

1. Transferencia entre jugadores

2. Transferencia entre colecciones

3. Transferencia entre pilas

API ExecuteInventoryOperations

Idempotencia

ETags y control de simultaneidad

Propiedades de presentación

Adición de propiedades a pilas o artículos nuevos

Actualización de propiedades en pilas o artículos existentes