Media

Media est la ressource qui contient un fichier téléversé. Chaque fichier, image ou document, est géré comme un Media unique. Pour une boutique de vêtements en ligne, la photo produit « 스테인리스 텀블러 500ml 측면 컷 » correspond à un Media.

Media est géré séparément de Content. Content pointe vers un Media au moyen d'un champ de type Refer (par exemple la « photo principale » d'un produit) pour utiliser ce fichier. Dans CMA, Media est une ressource enfant de Space, et son chemin se base sur /spaces/{spaceId}/medias. Les opérations de gestion s'effectuent dans CMA, et un Media publié est exposé à l'extérieur via une URL de livraison.

Structure de la ressource

Voici la réponse à une lecture unitaire du Media publié « 스테인리스 텀블러 500ml 측면 컷 ». Outre sys (propriétés système), il possède fields (valeurs de champ) et metadata (informations complémentaires comme les tags).

{
  "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": [] }
}

Clés principales :

• sys.id : identifiant unique du Media. Il alimente le {mediaId} des chemins de lecture unitaire, de modification, de suppression et de publication.
• fields : valeurs de champ du Media. Elles se composent de title, description et file ; leur forme détaillée est décrite ci-dessous dans Structure du fichier (file).
• metadata.tags : liste des Tag attachés à ce Media. Chaque élément a la forme Refer<Tag> ; en l'absence de tag, c'est un tableau vide [].

Contrairement à Content, Media ne possède pas de contentType. Sans schéma pour définir la composition des champs, tous les Media partagent la même structure title, description et file.

Structure du fichier (file)

fields comprend title, description et file, chacun étant une carte par locale. title et description associent une clé de Locale à une valeur chaîne, tandis que file associe une clé de Locale à un objet fichier. Comme dans l'exemple ci-dessus, le Media de démonstration possède une valeur sous une seule clé ko-KR.

Une fois la publication terminée, l'objet file d'un Media possède les clés suivantes.

mimeGroups regroupe le fichier par classification logique. Il prend une ou plusieurs des valeurs suivantes.

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

Forme de l'objet file pendant le traitement

Un fichier téléversé n'est pas livré immédiatement après la création du Media. Pendant que le système traite le fichier, deux clés supplémentaires s'ajoutent à l'objet file.

• upload : un Refer<Upload> pointant vers l'Upload à traiter.
• state : l'état du traitement. C'est l'une des valeurs ci-dessous.

Une fois le traitement terminé, upload et state disparaissent et sont remplacés par url et detail. Autrement dit, lorsque la clé state est absente et que url est présent, le fichier est livrable.

Propriétés système (sys)

Tout Media place ses propriétés système communes dans l'objet sys. space, createdBy et updatedBy prennent la forme Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Contrairement à Content, Media ne possède pas de propriété contentType, car il ne suit aucun schéma.

status prend l'une des 4 valeurs suivantes.

L'objet publish est un pointeur vers l'état de publication. Lorsque la ressource est publiée, il possède toutes les clés suivantes.

Après une dépublication, version, at et by disparaissent de publish, ne laissant que firstAt et counter. Si la ressource n'a jamais été publiée, publish vaut { "counter": 0 }.

L'objet archive n'existe que lorsque la ressource est archivée. Dans ce cas, il possède version (le sys.version au moment de l'archivage), at (date d'archivage) et by (utilisateur ayant archivé) ; lorsque la ressource n'est pas archivée, la clé archive elle-même est absente.

Dans les exemples ci-dessous, le sys.version et toutes les valeurs de date correspondent aux valeurs au moment de l'appel réel et varient d'un appel à l'autre.

Cycle de vie : téléversement et publication

Un Media se crée en téléversant d'abord le fichier, puis en référençant le résultat.

1. Téléversez le fichier via l'API Upload pour obtenir un Upload.
2. Créez le Media avec POST /medias en référençant cet Upload. Juste après la création, status vaut Draft et state de file vaut PENDING.
3. Une fois le traitement du fichier terminé, le système passe automatiquement le Media à Published. Le fichier devient alors livrable.

Si vous fournissez l'en-tête X-Weegloo-Ignore-Publish: true dans la requête POST, la publication automatique est ignorée et le Media reste en Draft. La modification et la modification partielle se republient automatiquement par défaut une fois le traitement terminé, et le même en-tête permet de désactiver ce comportement.

Les requêtes de modification, modification partielle, publication, dépublication, archivage et désarchivage doivent porter le sys.version actuel dans l'en-tête x-weegloo-version. Si cette valeur est absente ou ne correspond pas à la version actuelle, l'opération est considérée comme un conflit de modification concurrente et la requête est rejetée. Les requêtes de création et de suppression n'utilisent pas cet en-tête. Les transitions d'état comme la publication, la dépublication, l'archivage et le désarchivage n'ont pas de corps de requête distinct.

L'archivage et la suppression ne peuvent pas s'effectuer directement depuis l'état publié. Il faut d'abord dépublier. Tenter d'archiver un Media publié est rejeté avec WGL422007, et tenter de le supprimer est rejeté avec WGL422009.

API

L'URL de base de tous les points de terminaison ci-dessous est https://cma.weegloo.com/v1, et un jeton Bearer authentifiant CMA est requis dans l'en-tête Authorization. La modification, la modification partielle, la publication, la dépublication, l'archivage et le désarchivage doivent également envoyer l'en-tête X-Weegloo-Version (le sys.version actuel de la ressource) pour le contrôle de concurrence optimiste.

Documents liés

• API Upload : la requête qui téléverse un fichier et renvoie un Upload à utiliser pour créer un Media.
• Content : les données de contenu qui utilisent un Media en pointant vers lui via un champ Refer.
• Tag : l'étiquette de classification attachée dans metadata.tags.