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:

• Cargar nuevos activos.
• Actualizar activos existentes con control de versiones.
• Actualizar metadatos de activos, incluyendo descripciones, nombres para mostrar, íconos y vistas previas.
• Gestionar versiones de activos, como retroceder a una versión anterior especificada.
• Comprobar la 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 alcances 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 alcances de permisos asset:read y asset:write al registrar tu aplicación. Elige estos alcances 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 de 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 { "path": "operations/${operationId}" }. Puedes usarlo para comprobar 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.

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 alcances asset:read y asset:write.

2. Al implementar el flujo de autorización, incluye asset:read y asset:write como los parámetros de alcance de la URL de autorización que redirige a los usuarios de vuelta a tu aplicación, como en 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"'