Guía de uso para activos

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

• Subiendo nuevos recursos.
• Actualizar recursos existentes con control de versión.
• Actualizar metadatos de activos, incluidas descripciones, nombres de visualización, iconos y previsualizaciones.
• Administrar versiones de activos, como volver a una versión anterior especificada.
• Comprobación de la información existente de un recurso, incluidos metadatos, versiones y cualquier operación de actualización en curso.

Tipos de activos admitidos y límites

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

Permisos de seguridad

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

Claves de API

Para usar la API en tus propios scripts o herramientas, necesitas crear una clave de API para la autorización y la seguridad.Para administrar los recursos que posees individualmente, crea la clave de API bajo tu cuenta.Para administrar los activos de propiedad del grupo, crea la clave de API bajo el grupo objetivo.Para obtener más información sobre las claves API de propiedad del grupo, consulte Permisos de clave API de propiedad del grupo.

Una vez que creas una clave de API, no puedes cambiar su propiedad entre individuos o grupos, por lo que si creas una clave de API bajo tu propia cuenta, no puedes usarla para administrar los recursos del grupo.

Independientemente de si está creando la clave de API para usted o para su grupo, asegúrese de agregar los siguientes permisos:

1. Añade activos a permisos de acceso .
2. Añade permisos de operación Leer y Escribir a tu experiencia seleccionada, dependiendo de los alcances requeridos de los puntos finales que planeas llamar.

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

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

Aplicaciones de OAuth 2.0

Para usar la API para una aplicación de terceros de OAuth 2.0, agregue los alcances de permiso asset:read y asset:write cuando registre su aplicación.Elige estos alcances en función de los requisitos de los puntos finales que planeas usar.

Crear un nuevo recurso

Para subir un nuevo recurso por una solicitud HTTP:

1. Copia la clave de API al encabezado de solicitud x-api-key de la API de Crear recurso del punto final.

2. En su solicitud:

   1. Especifique 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 quieres crear el recurso 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 quieres crear el recurso como recurso de grupo , añade la ID de 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 el camino del archivo y el tipo de contenido de tu activo.

   Example Request for Create Asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"This is a description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Usa groupId para crear un recursode grupo
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Actualizar un recurso existente

Para actualizar un recurso existente con una solicitud HTTP:

1. Copia la clave de API al encabezado de solicitud x-api-key de la interfaz de programación de actualizar recurso.
2. Añade el tipo de recurso y el ID del recurso en tu solicitud. Para copiar tu ID de recurso:

   1. Navegue hasta la página de creación del tablero de creación del creador .
   2. Seleccione la categoría Artículos de desarrollo .
   3. Seleccione la categoría de su activo y encuentre el recursoobjetivo.
   4. Pase el cursor sobre la miniatura del recurso objetivo y haga clic en el botón ⋯ para mostrar una lista de opciones, luego seleccione Copiar ID de recurso de la lista.

Example Request for Updating Asset Content
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 de los activos

Si tu solicitud para crear un nuevo recurso o actualizar un recurso 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 subida con los siguientes pasos:

1. Copia la clave de la API al encabezado de solicitud x-api-key de la función Obtener operación y envía la solicitud, como el siguiente ejemplo de código:

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

2. Si su solicitud tiene éxito, devuelve un objeto Operation que incluye un response que representa la información de la subida de activos o un status que explica por qué la subida de activos falla como se muestra a continuación con el siguiente ejemplo de código:

   Example Response for Get Operation
   {
     "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": "Name",
       "description": "This is a description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Opcional) Compruebe el activo creado en su cuenta de Roblox.

   1. Navegue hasta la página Inventario de su cuenta Roblox.
   2. Seleccione la categoría de la entidad que desea verificar, comprobar.
   3. Encuentra el recurso objetivo y haz clic en su miniatura para ver el recurso.

Añadir la API de recursos a las aplicaciones de OAuth 2.0

Puedes crear aplicaciones de OAuth 2.0 que admitan la API de activos para permitir a tus usuarios subir y actualizar activos a Roblox.

Para usar la API de recursos para tu aplicación y solicitar permisos a tus usuarios, realiza los siguientes ajustes:

1. Cuando registras tu aplicación , bajo permisos , selecciona leer activo y escribir recurso ámbitos.

2. Cuando implementes el flujo de autorización, incluye asset:read y asset:write como parámetros de alcance de la URL de autorización que redirige a los usuarios de vuestra aplicación, como el siguiente ejemplo:

   https://authorize.roblox.com?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, incluya el token de acceso en el encabezado de autorización y los datos de formulario del contenido del activo para crear o actualizar en la URI de solicitud.El siguiente ejemplo muestra una solicitud de muestra para subir un nuevo recurso:

   Petición de ejemplo
   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\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'