Media

Media é o recurso que armazena os arquivos enviados. Cada arquivo, como imagens e documentos, é gerenciado como um único Media. Tomando uma loja de roupas como exemplo, a foto de produto "스테인리스 텀블러 500ml 측면 컷" é um Media.

Media é gerenciado separadamente de Content. Content aponta para um Media por meio de um campo do tipo Refer (por exemplo, a "foto principal" de um produto) para usar aquele arquivo. No CMA, Media é um recurso filho de Space, e o caminho tem como base /spaces/{spaceId}/medias. As operações de gerenciamento são realizadas no CMA, e o Media publicado é exposto externamente por uma URL de entrega.

Estrutura do recurso

A seguir está a resposta da consulta individual do Media publicado "스테인리스 텀블러 500ml 측면 컷". Junto com sys (propriedades de sistema), ele tem fields (valores dos campos) e metadata (informações adicionais, como 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": [] }
}

Chaves principais:

• sys.id: identificador exclusivo do Media. Entra em {mediaId} nos caminhos de consulta individual, modificação, exclusão e publicação.
• fields: valores dos campos do Media. É composto por três itens, title, description e file, e o formato detalhado é explicado mais abaixo em Estrutura do arquivo (file).
• metadata.tags: lista de Tag aplicadas a este Media. Cada item tem o formato Refer<Tag>, e, se não houver tags, é um array vazio [].

Diferente de Content, Media não tem contentType. Sem um molde que defina a composição dos campos, todo Media tem a mesma estrutura title, description e file.

Estrutura do arquivo (file)

fields tem três itens, title, description e file, e cada um é um mapa por locale. title e description mapeiam chaves de Locale para valores de texto, e file mapeia chaves de Locale para um objeto de arquivo. Como no exemplo acima, o Media de demonstração tem valor em uma única chave ko-KR.

O objeto file de um Media que terminou de ser publicado tem as seguintes chaves.

mimeGroups é o valor que agrupa o arquivo em classificações lógicas. Tem um ou mais dos seguintes valores.

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

Formato do objeto file durante o processamento

O arquivo enviado não é entregue imediatamente logo após a criação do Media. Enquanto o sistema processa o arquivo, duas chaves adicionais são anexadas ao objeto file.

• upload: um Refer<Upload> que aponta para o Upload alvo do processamento.
• state: o estado do processamento. É um dos valores abaixo.

Quando o processamento termina, upload e state são removidos e, em seu lugar, url e detail são preenchidos. Ou seja, se a chave state não existe e url está presente, esse arquivo está em estado entregável.

Propriedades de sistema (sys)

Todo Media armazena propriedades de sistema comuns no objeto sys. space, createdBy e updatedBy entram no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Diferente de Content, Media não tem a propriedade contentType, porque não segue um molde.

status é um dos 4 valores a seguir.

O objeto publish é um ponteiro que aponta para o estado de publicação. Quando publicado, tem todas as seguintes chaves.

Ao anular a publicação, version, at e by são removidos de publish, restando apenas firstAt e counter. Se nunca foi publicado, publish é { "counter": 0 }.

O objeto archive existe apenas quando arquivado. Quando arquivado, tem version (o sys.version no momento do arquivamento), at (momento do arquivamento) e by (usuário que arquivou); quando não está em estado arquivado, a própria chave archive não existe.

O sys.version e todos os valores de horário do exemplo abaixo são os valores no momento real da chamada e variam a cada chamada.

Ciclo de vida de envio e publicação

Media é criado enviando primeiro o arquivo e, em seguida, referenciando o resultado.

1. Envie o arquivo com a Upload API e receba um Upload.
2. Crie o Media com POST /medias referenciando esse Upload. Logo após a criação, status é Draft e o state de file é PENDING.
3. Quando o sistema termina de processar o arquivo, ele muda o Media automaticamente para Published. Nesse momento, o arquivo se torna entregável.

Se você passar o cabeçalho X-Weegloo-Ignore-Publish: true na requisição POST, a publicação automática é ignorada e o Media permanece como Draft. A modificação e a modificação parcial também são, por padrão, republicadas automaticamente quando o processamento termina, e podem ser desativadas com o mesmo cabeçalho.

As requisições de modificação, modificação parcial, publicação, anulação de publicação, arquivamento e desarquivamento devem carregar o sys.version atual no cabeçalho x-weegloo-version. Se esse valor estiver ausente ou não corresponder à versão atual, é considerado um conflito de modificação simultânea e a requisição é rejeitada. As requisições de criação e exclusão não têm esse cabeçalho. Transições de estado como publicação, anulação de publicação, arquivamento e desarquivamento não têm corpo de requisição próprio.

O arquivamento e a exclusão não podem ser feitos diretamente a partir do estado publicado. É preciso anular a publicação primeiro. Tentar arquivar ou excluir um Media em estado publicado é rejeitado, e o código devolvido é diferente conforme a operação (veja Erros).

Erros

São os códigos que você encontra ao lidar com o Media. Para os códigos comuns a todos os recursos, consulte Erros comuns.

API

A URL base de todos os endpoints abaixo é https://cma.weegloo.com/v1, e o cabeçalho Authorization precisa de um token Bearer que autentique no CMA. Modificação, modificação parcial, publicação, anulação de publicação, arquivamento e desarquivamento devem enviar junto o cabeçalho X-Weegloo-Version (o sys.version atual do recurso) para o controle de concorrência otimista.

Documentos relacionados

• Upload API: requisição para enviar um arquivo e receber um Upload a ser usado na criação de Media.
• Content: dados de corpo que apontam para Media por um campo Refer.
• Tag: rótulos de classificação aplicados em metadata.tags.