v1beta에서 v1로 마이그레이션

이 가이드는 일반 제공의 첫 번째 버전인 Merchant API v1beta에서 v1로 이전하는 데 도움이 됩니다. v1 버전에는 여러 업데이트와 코드 업데이트가 필요할 수 있는 몇 가지 변경사항이 도입되었습니다. 이러한 변경사항은 API를 간소화하고 판매자 센터 계정 관리를 개선하기 위해 설계되었습니다.

주요 차이점

v1beta에서 로 이전할 때 알아야 할 가장 중요한 변경사항은 다음과 같습니다.v1

  • Merchant API를 사용하기 위한 API 개발자 1회 등록: 연락처 세부정보를 제공하려면 registerGcp 메서드를 호출해야 합니다 (인증에 사용되는 각 Google Cloud 프로젝트에 대해 한 번만 호출). 이렇게 하면 API를 사용하고 Merchant API와 관련된 업데이트 및 공지사항을 받을 수 있습니다. 이 단계를 완료할 때까지 v1 또는 v1alpha API를 사용할 수 없습니다. 등록 절차에 관한 자세한 내용은 등록을 참고하세요.

  • 제품 이름 인코딩: ProductInput.name 및 Product.name 필드는 패딩되지 않은 base64url (RFC 4648 섹션 5) 인코딩을 지원합니다. 다음 가이드라인을 따르세요.

    • 인코딩하기 전에 문자열은 contentLanguage~feedLabel~offerId 형식을 준수해야 합니다.

    • 제품 이름에 Merchant API에서 사용하는 문자 또는 다음과 같은 URL 예약 문자가 포함된 경우 인코딩이 필수 입니다.

      % . + / : ~ , ( * ! ) & ? = @ # $

    • 제품 이름이 contentLanguage~feedLabel~offerId 형식을 준수하고 Merchant API에서 사용하는 문자 또는 URL 예약 문자를 포함하지않는 경우 인코딩 없이 일반 형식을 사용할 수 있습니다.

    • 일관되고 올바른 파싱을 위해 모든 제품 이름에 패딩되지 않은 base64url 인코딩을 사용하는 것이 좋습니다.

  • 제품 수준 세금 정보 삭제: taxes 및 taxCategory.

  • Product.attributes 이름 변경: Product.attributes 필드의 이름이 Product.productAttributes로 바뀌었습니다.

  • 제품 수준 세금 정보 삭제: taxes 및 taxCategory 필드가 Product.productAttributes 객체에서 삭제되었습니다. 자세한 내용은 세금에 관한 Google 판매자 센터 도움말 을 참고하세요.

  • GTIN 필드 변경사항: gtin 필드가 여러 값을 보유할 수 있음을 더 잘 반영하도록 Product.productAttributes 객체의 gtins로 이름이 바뀌었습니다. gtin 필드는 OrderTrackingSignals.lineItemDetails 객체의 array이며 이름이 gtins로 바뀌었습니다.

  • 채널 필드 삭제: channel 필드가 제품, 제품 입력, 데이터 소스에서 삭제되었습니다. 오프라인 매장에서만 판매되는 제품을 명확하게 지정하기 위해 새로운 불리언 필드인 legacyLocal이 도입되었습니다. 참고: legacyLocal 필드는 이전을 지원하는 보조 필드이며 온라인 및 오프라인 마케팅 방법을 단일 제품 소스로 완전히 타겟팅할 수 있게 되면 결국 지원 중단됩니다. 자세한 내용은 다음 섹션의 표를 참고하세요.

  • 지역 및 오프라인 판매점 인벤토리 속성을 위한 새 필드:

    • name, account, region을 제외한 모든 RegionalInventory 필드는 이제 regionalInventoryAttributes 라는 새 객체로 래핑됩니다. 예를 들어 RegionalInventory.price 속성은 이제 RegionalInventory.regionalInventoryAttributes.price 아래에 있습니다.
    • name, account 및 storeCode를 제외한 모든 LocalInventory 필드는 이제 localInventoryAttributes 라는 새 객체로 래핑됩니다. 예를 들어 LocalInventory.price 속성은 이제 LocalInventory.localInventoryAttributes.price 아래에 있습니다.

  • 지역 및 오프라인 판매점 인벤토리에서 customAttributes 삭제: customAttributes 필드가 RegionalInventory 및 LocalInventory 리소스에서 삭제되었습니다.

  • 계정 생성 개선: 중복된 users 필드가 CreateAndConfigureAccountRequest에서 삭제되었습니다. 단수 user 필드를 사용하여 초기 사용자를 새 계정과 연결합니다.

  • 특정 속성 유형이 문자열에서 enum으로 변경됨: 정의된 짧은 값 목록이 있는 Product 및 Inventory 리소스 내의 일부 필드가 더 나은 데이터 유효성 검사를 위해 string 유형에서 enum 유형으로 변경되었습니다 (예: Product.ProductAttributes.condition 필드는 이제 enum).

  • 온라인 반품 정책 업데이트 메서드 삭제: onlineReturnPolicy.update 메서드가 v1에서 삭제되었습니다. 대신 onlineReturnPolicy.create 메서드를 사용하여 온라인 반품 정책을 만드세요.

마이그레이션 방법

Merchant API의 v1beta 버전은 2026년 2월 28일에 지원 중단될 예정입니다. 지원 중단 일정에 관한 자세한 내용은 Merchant API 버전 관리 가이드를 참고하세요.

  • 이전의 첫 번째 단계는 1회 개발자 등록을 실행하는 것입니다 ( 개발자로 등록 참고). v1 메서드가 작동하기 전에 인증에 사용하는 각 Google Cloud 프로젝트에 대해 registerGcp 메서드를 호출해야 합니다.

  • API를 호출하는 방법 (REST, gRPC 또는 클라이언트 라이브러리 사용)과 관계없이 단계별로 이전할 수 있습니다. 즉, 전체 통합을 한 번에 업데이트하지 않고도 한 번에 하나의 API를 업데이트하고 이전할 수 있습니다 (예: Accounts API를 v1beta에 유지하면서 Products API를 v1로 이동).

세부 필드 변경사항

이 표에서는 v1beta 버전과 v1 버전 간에 변경된 필드를 자세히 비교합니다.

v1beta v1 설명
ProductInput.name ProductInput.name Unpadded base64url encoding Merchant API에서 사용하는 문자 또는 URL 예약 문자가 포함된 제품 이름에 대해 지원되며 필수입니다.
Product.name Product.name Unpadded base64url encoding Merchant API에서 사용하는 문자 또는 URL 예약 문자가 포함된 제품 이름에 대해 지원되며 필수입니다.
Product.gtin Product.gtins GTIN 필드의 이름이 바뀌었습니다.
Product.taxes 삭제됨 taxes 필드가 삭제되었습니다.
Product.taxCategory 삭제됨 taxCategory 필드가 삭제되었습니다.
Product.channel 삭제됨 channel 필드가 삭제되었습니다. 오프라인 사용 사례에는 legacyLocal 필드를 사용하세요.
Product.attributes Product.productAttributes attributes 필드의 이름이 productAttributes로 바뀌었습니다.
Product 필드의 availability, condition, gender, includedDestinations, excludedDestinations는 strings (또는 strings의 array)로 표시됩니다. 이제 이러한 필드는 enums (또는 enums의 array)입니다. 정의된 짧은 값 목록이 있는 필드가 string 유형에서 enum으로 변경되었습니다.
RegionalInventory의 price, salePrice, salePriceEffectiveDate, availability RegionalInventory.regionalInventoryAttributes로 이동됨 이러한 필드는 regionalInventoryAttributes 아래로 이동되었습니다.
RegionalInventory.availability 필드는 string입니다. RegionalInventory.regionalInventoryAttributes.availability는 이제 enums입니다. 가용성 유형이 string에서 enum으로 변경되었습니다.
LocalInventory의 price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla, instoreProductLocation LocalInventory.localInventoryAttributes로 이동됨 이러한 필드는 localInventoryAttributes 아래로 이동되었습니다.
LocalInventory.availability 필드는 string입니다. LocalInventory.localInventoryAttributes.availability는 이제 enums입니다. 가용성 유형이 string에서 enum으로 변경되었습니다.
LocalInventory.customAttributes 삭제됨 오프라인 판매점 인벤토리에는 더 이상 맞춤 속성이 지원되지 않습니다.
RegionalInventory.customAttributes 삭제됨 지역 인벤토리에는 더 이상 맞춤 속성이 지원되지 않습니다.
ProductInput.channel 삭제됨 channel 필드가 삭제되었습니다. 오프라인 사용 사례에는 legacyLocal 필드를 사용하세요.
DataSource.channel 삭제됨 channel 필드가 삭제되었습니다. 오프라인 사용 사례에는 legacyLocal 필드를 사용하세요.
사용할 수 없음 ProductInput.legacyLocal 제품이 오프라인 마케팅 방법만 타겟팅할 수 있음을 나타내는 새로운 불리언 필드입니다. 제품 리소스 ID에는 'local~' 접두어가 있습니다.
사용할 수 없음 Product.legacyLocal 제품이 오프라인 매장에서만 판매되고 온라인 구매에는 사용할 수 없음을 나타내는 새로운 불리언 필드입니다.
사용할 수 없음 DataSource.legacyLocal 데이터 소스에 오프라인 매장에서만 판매되는 제품이 포함되어 있음을 나타내는 새로운 불리언 필드입니다.
OrderTrackingSignals.LineItemDetails.gtin OrderTrackingSignals.LineItemDetails.gtins gtin 필드의 이름이 gtins로 바뀌었으며 이제 문자열이 아닌 문자열 배열입니다.
CreateAndConfigureAccountRequest.users 삭제됨 users 필드가 삭제되었습니다. 필드를 사용하여 초기 관리자를 계정에 추가합니다.user

이전
Refactor code for concurrent requests
다음
Overview