Guía de uso para activos

La API de Activos de Open Cloud te permite cargar y actualizar activos con una sola solicitud HTTP en lugar de importarlos manualmente a Studio. Esta API soporta:

• Carga de nuevos activos.
• Actualización de activos existentes con control de versiones.
• Actualización de metadatos de activos, incluyendo descripciones, nombres para mostrar, íconos y vistas previas.
• Gestión de versiones de activos, como volver a una versión anterior especificada.
• Comprobación de información existente de un activo, incluyendo metadatos, versiones y cualquier operación de actualización en proceso.

Tipos de activos soportados y límites

Para los puntos finales que no crean un nuevo activo o actualizan el contenido de activos existentes, no hay restricciones ni límites. Sin embargo, la funcionalidad de carga de contenido de activos impulsada por los puntos finales Crear Activo y Actualizar Activo solo soporta tipos limitados de activos con restricciones. Para cada llamada, solo puedes crear o actualizar un activo con un tamaño de archivo de hasta 20 MB con los siguientes límites:

Permisos de seguridad

La API soporta tanto el uso de primera parte con autorización de clave API como el uso de terceros en aplicaciones OAuth 2. Cada forma requiere diferentes configuraciones de permisos de seguridad.

Claves API

Para usar la API en tus propios scripts o herramientas, necesitas crear una clave API para autorización y seguridad.

Al crear una clave API, asegúrate de agregar los siguientes permisos:

1. Agrega activos a Permisos de Acceso.
2. Agrega permisos de operación Leer y Escribir a tu juego seleccionado, dependiendo de los ámbitos requeridos de los puntos finales que planeas llamar.

Una vez que tengas la clave API, cópiala en el encabezado de solicitud x-api-key. Todos los puntos finales requieren el encabezado de solicitud x-api-key.

--header 'x-api-key: ${ApiKey}' \

Aplicaciones OAuth 2.0

Para usar la API para una aplicación de terceros OAuth 2.0, agrega los ámbitos de permiso asset:read y asset:write al registrar tu aplicación. Elige estos ámbitos según los requisitos de los puntos finales que planeas usar.

Crear un nuevo activo

Para cargar un nuevo activo mediante una solicitud HTTP:

1. Copia la clave API en el encabezado de solicitud x-api-key del punto final Crear Activo.

2. En tu solicitud:

   1. Especifica el tipo de activo objetivo.
   2. Agrega el nombre y la descripción de tu activo.
   3. Agrega la información del creador.

      • Si deseas crear el activo en tu propio nombre, agrega tu ID de usuario. Puedes encontrar tu ID de usuario en la URL de tu perfil de Roblox. Por ejemplo, para https://www.roblox.com/users/1234567/profile, tu ID de usuario es 1234567.
      • Si deseas crear el activo como un activo de grupo, agrega el ID de grupo de tu grupo. Puedes encontrar el ID de grupo en la URL de la página de tu grupo. Por ejemplo, para https://www.roblox.com/groups/7654321/example-group#!/, el ID de grupo es 7654321.
   4. Agrega la ruta del archivo y el tipo de contenido de tu activo.

   Ejemplo de Solicitud para Crear Activo

   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nombre\",
     \"description\": \"Esta es una descripción\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Usa groupId para crear un activo de grupo
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Actualizar un activo existente

Para actualizar un activo existente mediante una solicitud HTTP:

1. Copia la clave API en el encabezado de solicitud x-api-key del punto final Actualizar Activo.
2. Agrega el tipo de activo y el ID del activo en tu solicitud. Para copiar tu ID de activo:

   1. Navega a la página de Creación del Tablero del Creador.
   2. Selecciona la categoría Elementos de Desarrollo.
   3. Selecciona la categoría de tu activo y encuentra el activo objetivo.
   4. Pasa el cursor sobre la miniatura del activo objetivo y haz clic en el botón ⋯ para mostrar una lista de opciones, luego selecciona Copiar ID de Activo de la lista.

curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

Recuperar el estado de la operación del activo

Si tu solicitud para crear un nuevo activo o actualizar un activo existente tiene éxito, devuelve un ID de Operación en el formato de { "path": "operations/${operationId}" }. Puedes usarlo para verificar el estado y el resultado de tu carga con los siguientes pasos:

1. Copia la clave API en el encabezado de solicitud x-api-key del método Obtener Operación y envía la solicitud, como el siguiente ejemplo de código:

   Ejemplo de Solicitud para Obtener Operación

   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. Si tu solicitud tiene éxito, devuelve un objeto Operation, que incluye un response que representa la información del activo cargado o un status que explica por qué la carga del activo falla, como muestra el siguiente ejemplo de código:

   Ejemplo de Respuesta para Obtener Operación

   {
     "path": "operations/{operationId}",
     "done": true,
     "response": {
       "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
       "path": "assets/2205400862",
       "revisionId": "1",
       "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
       "assetId": "2205400862",
       "displayName": "Nombre",
       "description": "Esta es una descripción",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. OPCIONAL

   Verifica el activo creado en tu cuenta de Roblox.

   1. Navega a la página de Inventario de tu cuenta de Roblox.
   2. Selecciona la Categoría del activo que deseas verificar.
   3. Encuentra el activo objetivo y haz clic en su miniatura para ver el activo.

Usar activos cargados en Studio

Un activo que cargas pertenece al usuario o grupo en el creationContext de tu solicitud, por lo que está disponible en Studio como cualquier otro activo que el creador posea:

• Insértalo desde el Toolbox o el Administrador de Activos.
• Los modelos se cargan como paquetes, así que verifica Inventario ⟩ Mis Paquetes en el Toolbox (o Creaciones ⟩ Paquetes de Grupo si un grupo los posee).
• Para usar un activo en una propiedad, ingresa rbxassetid:// seguido del assetId de la respuesta de operación en la ventana de Propiedades. En un script, asigna esa cadena a una propiedad de tipo cadena como AudioPlayer.Asset, o pasa el assetId a Content.fromAssetId() para una propiedad de tipo Content, como Decal.ColorMapContent. Para más información, consulta rbxassetid.

Agregar la API de activos a aplicaciones OAuth 2.0

Puedes crear aplicaciones OAuth 2.0 que soporten la API de Activos para permitir que tus usuarios carguen y actualicen activos en Roblox.

Para usar la API de Activos para tu aplicación y solicitar permisos de tus usuarios, realiza las siguientes configuraciones:

1. Al registrar tu aplicación, bajo Permisos, selecciona los ámbitos asset:read y asset:write.

2. Al implementar el flujo de autorización, incluye asset:read y asset:write como los parámetros de ámbito de la URL de autorización que redirige a los usuarios de vuelta a tu aplicación, como el siguiente ejemplo:

   https://apis.roblox.com/oauth/v1/authorize?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. Al enviar la solicitud, incluye el token de acceso en el encabezado de autorización y los datos del formulario del contenido del activo a crear o actualizar en la URI de la solicitud. El siguiente ejemplo muestra una solicitud de muestra para cargar un nuevo activo:

   Ejemplo de Solicitud

   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Decal\", 
   
     \"displayName\": \"DecalDemo123\", 
   
     \"description\": \"Esta es una descripción\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'