문서 작업 가이드
JSON 배열을 스프레드시트용 CSV로 변환하기
API 응답이나 JSON fixture의 레코드 배열을 추출하고, 컬럼·중첩 값·긴 ID·수식 셀을 검토한 뒤 엑셀과 구글 스프레드시트에서 열 수 있는 CSV로 내보냅니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
“선택 필드가 있는 API 레코드를 CSV로 내보내기” 확인에는 가이드 원본 데이터와 JSON CSV 변환기의 “구분 기호와 중첩 값 방식을 선택합니다” 절차를 사용했습니다. 출력은 문서 결과와 일치해야 했습니다. 기록 전 경계 증거는 “API 래퍼 전체를 붙여넣음”, “중첩 객체가 자동으로 원하는 표가 될 것이라 가정함” 항목별로 검토했습니다.
CSV 내보내기는 늦게 등장한 active까지 포함해 id,email,plan,active 열을 처음 등장한 순서로 만들고 API 레코드 두 개를 모두 보존했습니다. 각 레코드에 없는 plan 또는 active는 빈 셀로 남았고, 응답 wrapper는 데이터 행으로 직렬화하지 않았습니다.
문제 상황
API의 JSON은 레코드가 data.items 같은 래퍼 안에 있거나 행마다 키가 다를 수 있습니다. 그대로 CSV로 만들면 한 행짜리 래퍼, 누락된 컬럼, [object Object], 변형된 긴 ID, 실행 가능한 수식 셀이 생길 수 있으므로 배열 추출과 결과 검수가 필요합니다.
공식 출처와 표준
다음 공식 문서는 이 작업 흐름에서 다루는 형식과 보안 경계의 기준입니다. 도구별 실행 검증은 위에 별도로 기록합니다.
이럴 때 사용하세요
- API가 반환한 사용자, 주문, 이벤트 레코드를 엑셀이나 구글 스프레드시트에서 필터링해야 할 때
- JSON fixture나 데이터 덤프를 QA·운영팀이 검토할 CSV로 전달해야 할 때
- 중첩 응답에서 특정 배열만 골라 행 단위로 내보내야 할 때
- 선택 필드, 긴 숫자 ID, 다국어 텍스트, 쉼표와 줄바꿈이 있는 값을 안전하게 보존해야 할 때
단계
- 1단계
CSV 행이 될 배열을 확인합니다
최상위 값이 객체 배열인지 확인합니다. 실제 레코드가 data.items나 results 아래에 있으면 JSONPath Tester로 해당 배열만 추출해 각 객체가 한 행이 되도록 준비합니다.
- 2단계
엄격한 JSON 문법과 데이터 형태를 점검합니다
JSON Formatter에서 후행 쉼표, 빠진 따옴표, 중복 키를 확인합니다. 행마다 다른 키가 있다면 어떤 컬럼이 빈 셀이 될지 미리 정하고, 9007199254740991보다 큰 ID는 JSON 문자열로 감쌉니다.
- 3단계
구분 기호와 중첩 값 방식을 선택합니다
일반 CSV는 쉼표를 사용합니다. 대상 시스템이 요구하면 탭, 세미콜론, 파이프를 선택합니다. 중첩 객체를 profile.name 같은 컬럼으로 나누려면 평탄화를, 원래 구조를 한 셀에 남기려면 JSON 텍스트를 선택합니다.
- 4단계
행·컬럼·경고 수를 검토합니다
예상한 레코드 수와 출력 행 수가 같은지 확인합니다. 뒤쪽 레코드에만 있는 필드도 컬럼으로 유지되는지, 없는 필드와 null이 빈 셀인지, 배열이 JSON 텍스트로 따옴표 처리됐는지 살펴봅니다.
- 5단계
수식 보호를 유지하고 파일을 다시 엽니다
사용자 입력이 포함됐다면 수식 보호를 켜 둡니다. UTF-8 CSV를 다운로드해 스프레드시트에서 한 번 열고 한글, 선행 0, 긴 ID, 줄바꿈, 쉼표가 있는 셀이 그대로인지 확인한 뒤 공유합니다.
예시
선택 필드가 있는 API 레코드를 CSV로 내보내기
입력
[{"id":42,"email":"dev@example.com","plan":"pro"},{"id":43,"email":"ops@example.com","active":true}]출력
id,email,plan,active
42,dev@example.com,pro,
43,ops@example.com,,true흔한 실수
API 래퍼 전체를 붙여넣음
필요한 레코드가 data.items 아래에 있다면 그 배열을 먼저 추출하세요. 래퍼 객체는 여러 행이 아니라 중첩 값이 들어간 한 행으로 변환됩니다.
중첩 객체가 자동으로 원하는 표가 될 것이라 가정함
CSV는 평면 표입니다. 평탄화와 JSON 텍스트 중 목적에 맞는 방식을 선택하고, 생성된 헤더와 배열 셀을 직접 확인하세요.
없는 키와 null을 같은 빈 셀로 보고 지나침
CSV에서는 둘 다 빈 셀로 보일 수 있습니다. 값이 누락된 것인지 명시적인 null인지 구분이 중요하다면 변환 전에 별도 상태 필드를 만드세요.
긴 ID와 사용자 입력을 일반 셀로 취급함
큰 숫자 ID는 자릿수가 바뀔 수 있고 수식 문자로 시작하는 텍스트는 실행될 수 있습니다. 긴 ID는 JSON 문자열로 만들고 수식 보호를 유지하세요.
자주 묻는 질문
CSV로 가장 잘 변환되는 JSON 형태는 무엇인가요?
최상위 객체 배열이 가장 안정적입니다. 각 객체가 한 행이 되고, 전체 레코드에서 발견한 키가 처음 나타난 순서대로 컬럼이 됩니다.
중첩된 API 응답도 변환할 수 있나요?
가능하지만 먼저 필요한 레코드 배열을 추출하는 편이 좋습니다. data.items나 results 아래에 있다면 JSONPath Tester로 해당 배열만 가져오세요.
숫자는 CSV에서도 숫자로 유지되나요?
CSV는 텍스트이며 스프레드시트가 값을 다시 해석합니다. 안전 정수 범위를 넘는 ID는 변환 전에 문자열로 감싸고, 계정 번호·우편번호·선행 0은 파일을 연 뒤 다시 확인하세요.
왜 일부 셀 앞에 작은따옴표가 붙나요?
수식 보호가 위험한 문자열을 수식이 아닌 텍스트로 열도록 작은따옴표를 붙인 것입니다. 사용자가 입력한 값이 포함된 CSV에서는 이 보호를 유지하는 것이 안전합니다.