Media

Un Media es un recurso que contiene un archivo subido. Cada archivo, como una imagen o un documento, se gestiona como un único Media. Tomando como ejemplo una tienda de ropa en línea, la foto de producto "스테인리스 텀블러 500ml 측면 컷" es un único Media.

Un Media se gestiona de forma separada del Content. El Content apunta a un Media mediante un campo de tipo Refer (por ejemplo, la "foto principal" de un producto) para usar ese archivo. En CMA, Media es un recurso secundario de Space, y su ruta se basa en /spaces/{spaceId}/medias. Las operaciones de gestión se realizan en CMA, y el Media publicado se entrega al exterior mediante una URL de entrega.

Estructura del recurso

A continuación se muestra la respuesta de consulta individual del Media publicado "스테인리스 텀블러 500ml 측면 컷". Junto con sys (propiedades del sistema), tiene fields (valores de los campos) y metadata (información adicional como las etiquetas).

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PV9MlFUzv3r",
    "type": "Media",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "publish": {
      "version": 1,
      "at": "2026-06-18T10:11:46.712Z",
      "firstAt": "2026-06-18T10:11:46.712Z",
      "counter": 1,
      "by": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }
    },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T10:11:46.586Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T10:11:46.712Z",
    "version": 2,
    "status": "Published"
  },
  "fields": {
    "title": { "ko-KR": "스테인리스 텀블러 500ml 측면 컷" },
    "description": { "ko-KR": "흰 배경에서 찍은 텀블러 측면 제품 사진입니다." },
    "file": {
      "ko-KR": {
        "fileName": "tumbler.png",
        "contentType": "image/png",
        "mimeGroups": ["Image"],
        "url": "https://weegloo-media.com/medias/HnQ32YiH/v3r/3trmXRM3RqbgSnifyg7PV9MlFUzv3r/ko-KR/1/tumbler.png",
        "detail": { "size": 50847, "image": { "width": 900, "height": 900 } }
      }
    }
  },
  "metadata": { "tags": [] }
}

Claves principales:

• sys.id: identificador único del Media. Se inserta en el {mediaId} de las rutas de consulta individual, modificación, eliminación y publicación.
• fields: los valores de los campos del Media. Se compone de tres elementos, title, description y file, cuya forma detallada se explica más abajo en Estructura del archivo (file).
• metadata.tags: la lista de Tag asignados a este Media. Cada elemento tiene la forma Refer<Tag>, y si no hay etiquetas es un array vacío [].

A diferencia del Content, el Media no tiene contentType. Sin una plantilla que defina la composición de los campos, todos los Media tienen la misma estructura title, description y file.

Estructura del archivo (file)

fields se compone de tres elementos, title, description y file, y cada uno es un mapa por Locale. title y description asocian la clave de Locale con un valor de tipo cadena, y file asocia la clave de Locale con un objeto de archivo. Como en el ejemplo anterior, el Media de demostración tiene un valor bajo una única clave ko-KR.

El objeto file de un Media ya publicado tiene las siguientes claves.

mimeGroups es el valor que agrupa el archivo en una clasificación lógica. Tiene uno o más de los siguientes valores.

Attachment, Plaintext, Image, Audio, Video, RichText, Presentation, Spreadsheet, PdfDocument, Archive, Code, Markup.

Forma del objeto file durante el procesamiento

Un archivo subido no se entrega de inmediato justo después de crear el Media. Mientras el sistema procesa el archivo, al objeto file se le añaden dos claves más.

• upload: un Refer<Upload> que apunta al Upload objeto del procesamiento.
• state: el estado del procesamiento. Es uno de los siguientes valores.

Cuando termina el procesamiento, upload y state desaparecen, y en su lugar se rellenan url y detail. Es decir, si no hay clave state y existe url, ese archivo está en estado entregable.

Propiedades del sistema (sys)

Todo Media contiene las propiedades de sistema comunes en el objeto sys. space, createdBy y updatedBy se incluyen con la forma Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

A diferencia del Content, el Media no tiene la propiedad contentType, porque no sigue ninguna plantilla.

status es uno de los siguientes 4 valores.

El objeto publish es un puntero que indica el estado de publicación. Cuando está publicado, tiene todas las siguientes claves.

Al anular la publicación, de publish desaparecen version, at y by, y solo quedan firstAt y counter. Si nunca se ha publicado, publish es { "counter": 0 }.

El objeto archive solo existe cuando está archivado. Si está archivado, tiene version (el sys.version en el momento del archivado), at (momento del archivado) y by (usuario que lo archivó); si no está en estado archivado, la propia clave archive no existe.

El sys.version y todos los valores de fecha y hora del ejemplo siguiente corresponden al momento real de la llamada y varían en cada llamada.

Ciclo de vida de subida y publicación

Un Media se crea subiendo primero el archivo y referenciando después su resultado.

1. Sube el archivo con la API de Upload y obtén un Upload.
2. Crea el Media con POST /medias referenciando ese Upload. Justo después de la creación, status es Draft y el state de file es PENDING.
3. Cuando el sistema termina de procesar el archivo, cambia automáticamente el Media a Published. En ese momento el archivo pasa a ser entregable.

Si se añade el encabezado X-Weegloo-Ignore-Publish: true a la petición POST, se omite la publicación automática y el Media se deja en Draft. La modificación y la modificación parcial también, por defecto, se vuelven a publicar automáticamente cuando termina el procesamiento, y se pueden desactivar con el mismo encabezado.

Las peticiones de modificación, modificación parcial, publicación, anulación de publicación, archivado y desarchivado deben llevar el sys.version actual en el encabezado x-weegloo-version. Si este valor falta o no coincide con la versión actual, se considera un conflicto de modificación concurrente y la petición se rechaza. Las peticiones de creación y eliminación no llevan este encabezado. Las transiciones de estado como publicación, anulación de publicación, archivado y desarchivado no tienen cuerpo de petición.

El archivado y la eliminación no se pueden hacer directamente desde el estado publicado. Primero hay que anular la publicación. Si se intenta archivar un Media en estado publicado, se rechaza con WGL422007, y si se intenta eliminar, con WGL422009.

API

La URL base de todos los endpoints siguientes es https://cma.weegloo.com/v1, y se requiere un token Bearer que autentique en CMA en el encabezado Authorization. La modificación, modificación parcial, publicación, anulación de publicación, archivado y desarchivado deben enviar también el encabezado X-Weegloo-Version (el sys.version del recurso actual) para el control de concurrencia optimista.

Documentos relacionados

• API de Upload: petición para subir un archivo y obtener el Upload que se usa al crear un Media.
• Content: datos de contenido que usan un Media apuntándolo con un campo Refer.
• Tag: etiqueta de clasificación que se añade en metadata.tags.