파일 기반 피드, Merchant API 또는 이 둘의 조합을 사용하여 판매자 센터에 제품 데이터를 업로드할 수 있습니다.
- 파일 기반 제품 피드: SFTP, Google Cloud Storage, Google Sheets 또는 예약된 가져오기를 사용하여 CSV, TSV 또는 XML 파일을 업로드합니다.
- Merchant API: 제품 데이터가 변경될 때마다 백엔드에서 직접 프로그래매틱 요청을 전송하여 증분 업데이트를 수행하고, 정기적으로 전체 카탈로그를 동기화합니다.
이 가이드에서는 두 가지 접근 방식을 비교하고, 어떤 경우에 어떤 방식을 사용해야 하는지(또는 둘 다 사용해야 하는지) 설명하며, 일부 또는 모든 제품을 파일 피드에서 API로 이전하기로 결정한 경우를 위한 단계별 이전 플레이북을 제공합니다.
데이터 소스 접근 방식 선택
카탈로그 변동성, 백엔드 아키텍처, 운영 워크플로를 평가하여 Merchant API, 파일 피드 또는 하이브리드 설정을 사용할지 결정합니다.
Merchant API를 사용해야 하는 경우
다음과 같은 경우 API 기본 데이터 소스를 사용하세요.
- 직접 프로그래매틱 통합: 파일을 생성하고 파일 전송 파이프라인(예: SFTP 또는 Google Cloud Storage)을 관리하는 대신 백엔드에서 직접 API를 호출하는 것을 선호합니다.
- 높은 가격 및 재고 변동성: 제품 가격 또는 재고 수준이 하루 동안 자주 변경됩니다.
- 데이터 변경 시 즉시 업데이트: 다음 예약된 파일 생성 및 업로드를 기다리지 않고 백엔드에서 제품 변경사항이 발생하는 즉시 Google에 전송하려고 합니다.
- 증분 카탈로그 업데이트: 매번 전체 카탈로그를 다시 업로드하지 않고 개별 제품이 변경될 때마다 삽입, 업데이트 또는 삭제하려는 경우
- 부분 속성 업데이트: 전체 제품 페이로드를 다시 전송하지 않고 제품의 특정 필드(예:
productInputs.patch를 사용하는price또는availability)를 업데이트하려는 경우
파일 피드를 사용해야 하는 경우
다음과 같은 경우 파일 기반 기본 데이터 소스를 사용하세요.
- 정적 카탈로그: 제품 데이터가 자주 변경되지 않습니다(예: 하루에 한 번 이하).
- 델타 추적이 없는 스냅샷 전용 백엔드: 백엔드는 전체 카탈로그 스냅샷만 내보내며 항목 수준 변경사항이나 명시적인 제품 삭제를 추적할 수 없습니다.
- 스프레드시트 기반 워크플로: 엔지니어링 이외의 팀이 Google Sheets 또는 CSV 파일에서 직접 제품 데이터를 선별하거나 재정의합니다.
- 유지보수가 적은 작업: 요청 속도 조절, 재시도 처리, 주기적인 전체 카탈로그 동기화가 포함된 API 통합을 운영하는 대신 판매자 센터에서 가져오기 및 스냅샷 처리를 처리하는 예약된 파일 내보내기를 선호합니다.
둘 다 사용하는 경우
다음 시나리오에서는 동일한 판매자 센터 계정에서 파일 피드와 Merchant API를 결합할 수 있습니다.
- 분할된 제품 카탈로그: 빠르게 변화하는 제품(예: 반짝 세일 또는 회전율이 높은 인벤토리)에는 Merchant API를 사용하고 정적 카탈로그 세그먼트 또는 별도의 제품 라인에는 파일 피드를 사용합니다. 각 제품이 하나의 기본 데이터 소스로만 업로드되는지 확인합니다(병렬 사용 및 기본 데이터 소스 소유권 참고).
- 파일 기반 보조 피드가 있는 API 기본 데이터: API 기본 데이터 소스를 통해 핵심 제품 데이터를 관리하는 한편, 엔지니어링 이외의 팀이나 서드 파티 파트너가 속성 규칙과 결합된 파일 기반 보조 피드(예: Google Sheets 또는 CSV 파일)를 통해 추가 속성을 제공하거나 그 반대의 경우도 가능합니다.
- 부분 또는 단계적 이전: 특정 시장, 카테고리 또는 하위 계정을 API로 전환하고 나머지 카탈로그는 파일 피드에 유지합니다.
일부 또는 모든 제품을 파일 피드에서 Merchant API로 이동하기로 결정한 경우 단계별 이전 플레이북을 따르세요.
주요 아키텍처 차이점
파일 피드와 푸시 기반 Merchant API는 Google에서 제품 데이터를 처리하고 관리하는 방식이 다릅니다.
| 개념 | 파일 피드 | Merchant API |
|---|---|---|
| 통합 모델 | 오프라인 파일 덤프: 카탈로그를 파일로 내보내고 SFTP, Google Cloud Storage, Google Sheets 또는 예약된 가져오기를 사용하여 전송합니다. | 직접 프로그래매틱 통합: 백엔드에서 API 엔드포인트로 요청을 직접 전송합니다. |
| 변형 세부사항 | 일괄 처리: 일반적으로 항목 하나를 수정하려면 전체 파일을 다시 처리해야 합니다. | 세분화된 트랜잭션: 변경된 제품만 삽입, 패치 또는 삭제할 수 있습니다. |
| 동기화 타이밍 | 일괄 동기화: 변경사항은 다음 예약된 파일 내보내기 및 전송 주기가 될 때까지 백엔드에서 대기합니다. | 즉시 또는 예약된 호출: 주기적인 전체 동기화와 함께 증분 변경사항이 발생할 때마다 즉시 전송할 수 있습니다. |
| 삭제 동작 | 암시적(스냅샷): 각 파일은 완전한 스냅샷입니다. 기본 파일에서 행을 삭제하면 제품이 삭제됩니다. | 명시적: 스냅샷 개념이 없습니다. productInputs.delete를 호출하여 중단된 제품을 삭제합니다. |
| 리소스 표현 | 단일 상태: 파일의 행이 원시 입력을 나타냅니다. | 원시 데이터와 처리된 데이터 분리: API는 데이터를 ProductInput(원시 입력)와 Product(최종 처리된 상태)로 분할합니다. |
| 속성(피드) 규칙 | 판매자 센터 UI의 원시 파일 열에 적용됩니다. | 판매자 센터 UI에서 지원됩니다. API 데이터를 서드 파티 보조 파일과 병합할 때 필요합니다. 백엔드에서 처리되는 경우 단일 소스 변환에는 선택사항입니다. |
병렬 사용 및 기본 데이터 소스 소유권('마지막 업데이트가 우선 적용됨')
동일한 판매자 센터 계정에서 파일 피드와 API를 모두 사용할 수 있지만, 특정 제품을 삽입할 때는 한 가지 방법만 사용하는 것이 좋습니다.
판매자 센터는 '최종 업데이트 우선' 모델로 운영됩니다. 가장 최근에 제품 삽입을 푸시한 기본 데이터 소스(API 또는 파일 피드)가 해당 제품 데이터의 기본 소유권을 갖습니다.
- 파일 데이터 소스가 제품을 소유하는 경우: 후속 파일 업로드에서 제품을 생략하면 암시적 삭제가 트리거되어 판매자 센터 에서 제품이 삭제됩니다.
- API 데이터 소스가 제품을 소유하는 경우: 파일 피드가 더 이상 제품을 소유하지 않으므로 파일 업로드에서 제품을 생략해도 아무런 영향을 미치지 않습니다.
삭제하려면
accounts.productInputs.delete를 호출해야 합니다. - 의도치 않은 소유권 재획득 위험: API 푸시 후 업데이트된 파일 피드가 실행되고 제품이 포함된 경우 파일 데이터 소스가 소유권을 다시 획득합니다. 이후 파일에서 누락되면 제품이 예기치 않게 삭제됩니다.
예기치 않은 삭제나 API 업데이트 손실을 방지하려면 API와 파일 기본 데이터 소스를 모두 사용하여 동일한 제품에 대해 동시 업데이트를 수행하지 마세요.
주요 API 고려사항
구현을 시작하기 전에 다음과 같은 중요한 Merchant API 동작을 이해하세요.
유연한 데이터 소스(언어 또는 라벨 없음)
특정 타겟 피드 라벨과 언어를 미리 정의해야 하는 파일 피드와 달리 Merchant API를 사용하면 feedLabel 또는 contentLanguage를 지정하지 않고도 기본 데이터 소스를 만들 수 있습니다.
- 유연한 업로드: 언어 또는 피드 라벨 조합이 있는 제품을 단일 데이터 소스에 업로드할 수 있습니다.
- 간소화된 관리: 타겟 시장마다 별도의 데이터 소스를 만들고 관리할 필요가 없습니다. 참고: 데이터 소스 전략 선택에 관한 자세한 내용은 데이터 소스 전략 선택을 참고하세요.
동기화 전략 및 할당량
전체 카탈로그를 한 번에 업로드하는 파일 피드와 달리, 증분 업데이트와 단계적 전체 동기화를 모두 고려하여 Merchant API 통합을 설계하세요.
- 증분 업데이트와 정기적인 전체 동기화 결합: 백엔드에서 제품 속성이 변경되면
productInputs.insert또는productInputs.patch요청을 전송합니다. 증분 업데이트에만 의존하면 시간이 지남에 따라 데이터가 동기화되지 않을 수 있으므로 주기적인 전체 동기화를 실행하여 카탈로그를 정보 소스와 조정하세요(30일 제품 만료도 새로고침됨). 전체 동기화를 실행하는 빈도는 카탈로그 크기와 사용 가능한 API 할당량에 따라 다릅니다. - API 할당량을 준수하도록 요청 속도 조절: 모든 제품에 대해 한 번에 API를 호출하지 마세요. 증분 변경사항은 발생하는 대로 전송할 수 있지만, 분당 및 일일 메서드 호출 할당량을 초과하지 않도록 전체 동기화 요청을 하루 동안 균등하게 분산하세요. 자세한 내용은 할당량 및 한도와 제품을 자주 업데이트하기를 참고하세요.
통합 테스트
프로덕션으로 이동하기 전에 안전한 환경에서 통합 로직을 검증합니다.
테스트 계정 사용
프로덕션 환경에서 변경하기 전에 샌드박스 테스트 계정에서 이전의 초기 단계를 실행하는 것이 좋습니다.
- 테스트 계정 만들기: 실시간 광고 또는 무료 등록정보에 영향을 주지 않고 안전하게 실험할 수 있도록 격리된 테스트 계정을 설정합니다.
- API 데이터 소스 만들기: API 기본 데이터 소스를 만드는 연습을 합니다.
- 속성 규칙 테스트: 데이터 변환 및 보조 피드 조인을 확인합니다.
- 페이로드 및 제품 키 검증: 샘플 제품을 푸시하여 SKU 대소문자, 인코딩, 오류 처리를 확인합니다.
자세한 내용은 1단계: 테스트 계정 만들기 및 테스트 계정 가이드를 참고하세요.
제품 키 정렬 검증
프로그래매틱 페이로드 제품 키가 파일 피드 SKU와 정확히 일치하는지 확인합니다. Google은 다음을 결합하여 제품을 식별합니다.
offerId(파일 피드에서id라고 하며 대소문자 구분)contentLanguage(예:en)feedLabel(예:US)
특수문자 및 인코딩
제품 식별자에 /, % 또는 ~와 같은 문자가 포함된 경우 API 호출에서 인코딩된 형식(패딩되지 않은 base64url 인코딩)을 사용합니다. 자세한 내용은 ProductInput.name을 참고하세요.
동시 실행 제어
실시간 통합에서는 네트워크 지연 시간으로 인해 업데이트가 순서에 맞지 않게 도착할 수 있습니다. 이전 업데이트가 최신 데이터를 덮어쓰지 않도록 하려면 ProductInput 리소스에서 versionNumber 필드를 사용합니다.
단계별 이전 플레이북
일부 또는 모든 제품을 파일 피드에서 Merchant API로 이전하기로 결정한 경우 이 플레이북에 따라 노출수나 게재 내역을 잃지 않고 제품을 이전하세요.
1. 테스트 계정에서 이전 리허설
프로덕션 환경에서 변경하기 전에 accounts.createTestAccount 메서드를 사용하여 샌드박스 테스트 계정을 만듭니다(테스트 계정 가이드 참고). 테스트 계정은 기본적으로 오퍼가 승인되고 도메인 확인이 필요하지 않으며 데이터가 공개적으로 제공되지 않는 격리된 환경을 제공합니다.
테스트 계정을 사용하여 프로덕션 설정을 미러링하고 엔드 투 엔드 이전을 리허설합니다.
- 제품 피드 설정 미러링: 테스트 계정에서 파일 기본 데이터 소스(및 보조 데이터 소스)를 만들고 프로덕션 제품 피드 파일의 샘플을 업로드합니다.
- 테스트 API 데이터 소스 및 규칙 만들기: API 기본 데이터 소스를 만들고 필요한 속성 규칙 또는 보조 피드 조인을 구성합니다.
- 소유권 인수 및 키 정렬 테스트: 샘플 제품에 대해
productInputs.insert요청을 전송하고 API 데이터 소스가 중복 제품을 만들지 않고 기존 항목의 소유권을 가져오는지 확인합니다. - 업데이트 및 삭제 확인:
productInputs.patch를 사용하여 부분 업데이트를 테스트하고productInputs.delete를 사용하여 삭제를 테스트한 후products.get를 사용하여 결과 리소스를 검사합니다.
2. 프로덕션 API 데이터 소스 만들기
데이터를 푸시하기 전에 계정에 API 유형의 기본 데이터 소스를 만듭니다.
API 기본 데이터 소스 만들기
API 푸시를 허용하는 데이터 소스를 만들려면 dataSources 엔드포인트에 POST 요청을 전송합니다. 자세한 내용은 기본 제품 데이터 소스 만들기를 참고하세요.
3. 맞춤 속성 규칙 전환
커스텀 속성 규칙은 특정 데이터 소스에 바인딩되며 파일 데이터 소스에서 새 API 데이터 소스로 자동 전송되지 않습니다.
속성 규칙을 전환하는 방법은 목적에 따라 다릅니다.
- 교차 소스 병합 및 서드 파티 보조 피드: 기본 API 데이터를 외부 보조 데이터 소스(예: 서드 파티 공급업체 파일, 인벤토리 스프레드시트, 프로모션 피드)와 결합하는 경우 판매자 센터 UI에서 속성 규칙을 다시 만들고 새 API 데이터 소스에 연결해야 합니다. 클라이언트 측 사전 처리는 여러 독립 소스의 데이터를 조인하는 규칙을 대체할 수 없습니다.
- 단일 소스 데이터 변환: 기본 카탈로그 데이터의 단일 소스 정리, 기본값 또는 문자열 형식 지정의 경우 다음 중에서 선택합니다.
- 백엔드 변환(권장): API를 호출하기 전에 자체 시스템에서 변환을 적용합니다. 이를 통해 프로그래매틱 제어, 더 쉬운 테스트, 간소화된 디버깅이 가능합니다.
- 판매자 센터 속성 규칙: 판매자 센터에서 자동으로 계속 관리하도록 하려면 판매자 센터 UI에서 새 API 데이터 소스의 변환 규칙을 다시 만듭니다.
4. API 통합 사용 설정
프로덕션 API 통합을 사용 설정하여 새 API 기본 데이터 소스에서 제품을 삽입, 업데이트, 삭제합니다.
제품 삽입 및 업데이트(소유권 인수): 통합에서
productInputs.insert및productInputs.patch요청을 전송합니다. 기존 파일 피드 제품과 동일한 키(offerId,contentLanguage,feedLabel)를 사용하여 API를 통해 제품을 삽입하면 API 데이터 소스가 해당 제품의 소유권을 가져오고 게재 내역을 보존합니다. 자세한 내용은 제품 삽입 및 제품 추가 및 관리를 참고하세요.판매 중단된 제품 삭제: 카탈로그에서 제품이 삭제될 때마다
productInputs.delete를 명시적으로 호출하도록 통합을 구성합니다.점진적 배포: 대규모 카탈로그의 경우 한 번에 하나의 판매자 센터 하위 계정 또는 하나의 데이터 소스에 대해 통합을 사용 설정합니다.
동시 실행 구성: 많은 요청을 보내는 경우 동시 요청을 처리하고 여러 연결을 관리하도록 클라이언트를 구성합니다. 동시 요청을 위한 코드 리팩터링 가이드를 참고하세요.
5. 파일 데이터 소스 업데이트 일시중지
API 통합이 활성화되면 파일 데이터 소스가 API 업데이트를 덮어쓰지 않도록 다음 예약된 파일 실행 전에 파일 업데이트를 중지합니다.
- SFTP/FTP 위치, Google Cloud Storage 또는 Google Sheets에 새 파일 업로드를 중지합니다.
- 판매자 센터 UI에서 파일 데이터 소스로 이동하여 예약된 가져오기를 일시중지합니다.
- 파일 데이터 소스가 소유한 기존 제품은 API 통합에서 삽입할 때까지 최대 30일 동안 게시된 상태로 유지됩니다.
6. 이전이 완료될 때까지 기다린 후 확인하기
모든 활성 제품이 파일 데이터 소스에서 API 데이터 소스로 이전될 때까지 기다립니다. 증분 업데이트는 제품이 변경될 때 제품을 이전하지만, 정기적인 통합을 통해 단계적 전체 카탈로그 동기화를 실행하면 전체 카탈로그를 더 빠르게 이전할 수 있습니다(동기화 전략 및 할당량 참조).
이 단계에서는 다음을 수행합니다.
- 판매자 센터 UI에서 상품 수를 모니터링합니다. 파일 데이터 소스 수가
0로 감소하고 API 데이터 소스 수가 활성 카탈로그와 일치할 때까지 기다립니다. products.get를 사용하여 속성과 맞춤 속성 규칙이 예상대로 병합되는지 확인합니다.- 판매자 센터 UI에서 API 진단 도구를 모니터링하여 오류율과 API 성능을 추적합니다.
7. 파일 데이터 소스 사용 중단
전환이 완료되고 파일 피드 항목 수가 0인 경우:
- 업데이트가 실시간으로 반영되는지 확인합니다.
- 실수로 파일 기반 업데이트가 API 데이터를 덮어쓰지 않도록 판매자 센터 UI에서 기존 파일 데이터 소스를 삭제합니다.