잘못된 CSV 헤더 때문에 즉시 거절당하는 이유와 이를 올바르게 작성하는 스크립트

저는 CSV 헤더 하나 때문에 제 인생의 네 시간을 잃었습니다. 그날은 화요일이었습니다. 저는 Adobe Stock에 업로드할 준비가 된 62개의 JPG 파일, 스프레드시트에서 직접 만든 메타데이터 CSV, 그리고 며칠 걸릴 거라고 생각했던 검토 대기열을 가지고 있었습니다. 모든 파일이 몇 분 만에 거절되었습니다. '품질 문제'도 아니었고, '키워드 문제'도 아니었습니다. 거절 이유는 62개 모두 동일했습니다: 유효하지 않은 파일 형식(invalid file format). 문제는 이미지가 아니었습니다. 헤더 행이었습니다. 저는 저에게 논리적으로 맞는 것이라 생각해서 Filename, Title, Keywords, Category라고 작성했습니다. Adobe의 일괄 업로드 기능은 특정 다섯 개의 열 레이아웃을 기대하며, 그들의 파서는 다른 것을 보기 전에 헤더 행을 확인합니다. 잘못된 헤더 때문에 즉시 거절되고, 어떤 열이 틀렸는지에 대한 피드백조차 없습니다. 이러한 실패가 바로 make_metadata.py가 존재하는 이유이며, 제가 CSV 파일을 수동으로 만드는 것을 완전히 중단하게 된 이유입니다.

파서가 가장 먼저 읽는 것은 헤더이다

이것은 아무도 알려주지 않는 부분입니다. 스톡 플랫폼들은 업로드 단계에서 사용자의 CSV를 인간적인 방식으로 '검토'하지 않습니다. 스크립트가 그것을 읽습니다. 그 스크립트는 구조를 먼저 검증합니다: 정확한 열 개수, 정확한 열 순서, 정확한 헤더 이름. 만약 구조에 실패하면 파일은 검토자에게 도달조차 할 수 없습니다. Adobe의 일괄 업로드 템플릿은 다섯 개의 열입니다. Vecteezy는 네 개의 열이고, Dreamstime은 열다섯 개입니다. 이것들은 제안이 아니라, 그들의 데이터 수집(ingestion) 코드가 기대하는 스키마이며, 각 플랫폼은 벗어나는 모든 것을 거절합니다. 최악인 부분은 오류 메시지가 '헤더가 잘못되었습니다'라고 말해주지 않는다는 것입니다. 파일 처리가 불가능했다고만 하며, 사용자는 추측하며 재시도 주기를 소모하게 됩니다. 저는 실제 템플릿 파일을 열고 제 것과 문자 단위로 비교하기 전까지 세 번이나 그렇게 추측했습니다.

왜 세 플랫폼이 의견을 일치시키지 못하는가

CSV가 CSV일 것이라고 가정할 수 있습니다. 하지만 그렇지 않습니다. Adobe는 파일명(filename), 제목(title), 키워드(keywords), 카테고리(category), 릴리스(releases)를 포함하는 다섯 개의 열을 요구합니다. Vecteezy는 네 개를 요구하고, Dreamstime은 설명 필드, 추가 키워드 슬롯, 그리고 검토자 워크플로우에 의존하는 메타데이터가 포함되어 있어 열다섯 개를 요구합니다. 만약 하나의 마스터 스프레드시트를 유지하고 그 변형들을 내보낸다면, 촉박한 마감 기한 압박 속에서 수동으로 변환하기 때문에 결국 세 가지 중 하나는 틀리게 됩니다. 실제로 저에게 효과가 있었던 해결책은 CSV 파일을 손으로 작성하는 것을 멈추고 하나의 진실의 원천(source of truth)으로부터 생성하는 것이었습니다. 모든 에셋은 파일명과 함께 폴더에 존재합니다. 스크립트가 그 폴더를 순회하며 플랫폼이 요구하는 정확한 헤더를 적용하고, 열을 채우며, 파일을 작성합니다. 따라서 헤더는 다시는 인간에 의해 입력되지 않으므로 틀릴 수 없습니다.

생성기가 실제로 하는 일

make_metadata.py는 파일 폴더와 플랫폼 플래그를 받아 해당 플랫폼의 파서가 예상하는 정확한 헤더를 가진 CSV 파일을 작성합니다. Adobe는 다섯 개의 열을 받습니다. Vecteezy는 네 개를 받고, Dreamstime은 열다섯 개를 받습니다. 그 외에는 아무것도 없습니다. 기본적으로 파일명을 제목 형식(title-case)으로 변환하여 이를 제목으로 사용하는데, 이는 첫 번째 시도로는 괜찮지만 저는 항상 이것을 대체합니다. 여기에 --titles titles.json 플래그가 있어 파일별 실제 제목과 키워드를 공급할 수 있으며, 제출하기 전에는 제가 이것을 사용합니다. 파일명으로 된 제목은 마치 파일명처럼 보이고 검토자들이 알아차립니다. 이 스크립트 자체는 표준 라이브러리만 사용합니다. pandas도 없고, 의견이 담긴 CSV 라이브러리도 없으며, 설치 단계도 없습니다. 이는 중요합니다. 제 전체 파이프라인은 GPU가 없는 1 vCPU, 2 GB RAM 서버에서 실행되기 때문에, 추가하는 모든 의존성은 제가 가지고 있지 않은 메모리가 됩니다. 키트에 포함된 두 개의 스크립트, 즉 메타데이터 빌더(metadata builder)와 업로드 추적기(upload tracker)는 파이썬만 있으면 됩니다.

플래그되는 두 번째 방법: 배치 실행을 두 번 하는 것

올바른 CSV를 생성하는 것은 하나의 실패 모드를 해결했지만, 또 다른 위험을 만들었습니다. 업로드 과정을 스크립트로 처리하게 되면, 특히 일부 파일만 실패한 경우 어떤 파일이 통과했는지 확신할 수 없을 때 같은 배치를 두 번 실행하기가 너무 쉬워집니다. 중복 게시(Double-posting)는 계정이 플래그 지정되는 가장 빠른 방법이며, 작은 규모의 계정에서는 관용을 베풀지 않습니다. 따라서 수정 작업의 후반부는 upload_tracker.py입니다. 이것은 무엇이 완료되었는지 기억하는 단순한 원장(ledger) 역할을 합니다. pending은 게시되지 않은 항목을 보여주고, done은 항목을 표시하며, status는 개요를 제공합니다. 이 배치를 재실행하면 이미 원장에 있는 것은 건너뜁니다. 이것은 영리하지 않습니다. 단순히 텍스트 파일과 규율의 문제이며, 그 이후로 제가 만들었을 모든 중복을 막아주었습니다.

지루하지만 중요한 교훈

제가 스톡 플랫폼에서 받았던 모든 거절 사유는 두 가지 원인 중 하나를 거슬러 올라갑니다. 첫째, 플랫폼의 파서(parser)가 구조를 받아들이지 않았거나, 둘째, 무언가를 두 번 제출했기 때문입니다. 이 둘 다 예술적인 문제가 아닙니다. 둘 다 프로세스 문제입니다. 그리고 둘 다 올바른 것을 자동화된 것으로 만듦으로써 해결됩니다. 손으로 타이핑한 헤더와 기억에 의존하는 업로드 추적은 약 20개의 파일 정도에서 실패합니다. 저는 현재 39개의 완성된 제품과 이 워크플로우를 위해 약 19,000줄의 파이프라인 코드를 가지고 있으며, 이 모든 것은 동일한 2GB 박스에서 검증되었고, 헤더 타이핑을 중단한 날 이후로 헤더 거절을 받은 적이 없습니다.

저는 작동하는 버전의 스크립트들, 즉 정확한 Adobe, Vecteezy 및 Dreamstime 헤더 처리 방식과 업로드 원장을 컴플라이언스 메타데이터 키트(compliance metadata kit)로 패키징했습니다. 이것은 제가 화요일에 만든 도구이며, 이에 대한 강좌가 아닙니다. 그리고 이 메타데이터 스크립트는 설치 없이 실행됩니다.

컴플라이언스 메타데이터 키트 받기

디지털 제품을 제작하시나요? 디지털 제품 판매자를 위한 무료 가이드 및 키트.