Guía de uso para activos

La API de Activos de Open Cloud te permite cargar y actualizar activos con una única 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, incluidos descripciones, nombres para mostrar, iconos y vistas previas.
• Administrar versiones de activos, como volver a una versión anterior especificada.
• Comprobar información existente de un activo, incluidos metadatos, versiones y cualquier operación de actualización en proceso.

Tipos de activos y límites soportados

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 de 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 añadir los siguientes permisos:

1. Añadir activos a Permisos de Acceso.
2. Añadir 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 al encabezado de solicitud x-api-key. Todos los puntos finales requieren el encabezado de solicitud x-api-key.

Ejemplo de Encabezado de Solicitud API
--header 'x-api-key: ${ApiKey}' \

Aplicaciones OAuth 2.0

Para usar la API para una aplicación de terceros OAuth 2.0, añade los ámbitos de permiso asset:read y asset:write al registrar tu aplicación. Elige estos ámbitos basándote en 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 al encabezado de solicitud x-api-key del Crear Activo punto final.

2. En tu solicitud:

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

      • Si deseas crear el activo en tu propio nombre, añade 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, añade el ID del grupo de tu grupo. Puedes encontrar el ID del grupo en la URL de la página de tu grupo. Por ejemplo, para https://www.roblox.com/groups/7654321/example-group#!/, el ID del grupo es 7654321.
   4. Añade 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 al encabezado de solicitud x-api-key del Actualizar Activo punto final.
2. Añade el tipo de activo y la 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 ratón 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.

Ejemplo de Solicitud para Actualizar el Contenido del Activo
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 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 verificar el estado y el resultado de tu carga con los siguientes pasos:

1. Copia la clave API al 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 Operación, incluyendo ya sea una respuesta que representa la información del activo cargado o un estado que explica por qué la carga del activo falla, como se muestra en 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.

Añadir 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 suban y actualicen activos a Roblox.

Para usar la API de Activos para tu aplicación y solicitar permisos a 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 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 para 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"'