Content API v2에서 v2.1로 이전

2019년 3월에는 Content API for Shopping 버전 2.1이 출시되었으며 2021년 4월에는 v2가 2021년 9월 30일에 지원 종료된다고 발표했습니다. 버전 v2에 대한 지원이 중단되었습니다. 즉시 v2.1로 이전하세요.

애플리케이션 마이그레이션

v2에서 v2.1로 이전하려면 새 v2.1 버전을 호출하도록 엔드포인트 URL을 업데이트하고 v2.1에 도입된 브레이킹 체인지를 고려하여 애플리케이션을 수정해야 합니다.

v2.1 엔드포인트를 사용하도록 API 호출 업데이트

v2.1을 호출하려면 새 v2.1 엔드포인트를 사용하도록 요청을 업데이트하세요.

예를 들어 v2로 products.get 메서드를 호출하려면 다음을 사용합니다.

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

v2.1의 경우 URL을 다음과 같이 업데이트합니다.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

v2.1 서비스 및 엔드포인트에 대한 자세한 내용은 API 참조를 확인하세요.

필수 변경사항 적용

API 호출의 URL을 업데이트하는 것 외에도 v2.1에 도입된 여러 브레이킹 체인지를 고려하여 애플리케이션을 업데이트해야 합니다. 다음 섹션을 검토하고 필요에 따라 애플리케이션을 업데이트하세요.

1. inventory 서비스와의 통합 업데이트

v2 inventory 서비스가 삭제되었으며 다음 v2.1 기능에서 동일한 기능을 사용할 수 있습니다.

  • 부분적인 제품 업데이트에는 새로운 보조 피드 또는 products.update를 사용합니다. 이전에 inventory.set로 업데이트된 모든 필드를 포함하여 변경 가능한 모든 제품 필드를 업데이트할 수 있습니다 (localinventory 제외). 자세한 내용은 보조 피드로 이전을 참고하세요.

  • 오프라인 제품 업데이트에는 새로운 localinventory 서비스를 사용합니다.

2. accounts 서비스 호출 업데이트

  • v2.1에서 accounts.update 메서드를 호출하면 요청에 포함된 필드만 업데이트하는 대신 accounts 리소스를 완전히 덮어씁니다. accounts 리소스에서 필드가 삭제되지 않도록 하려면 모든 필드를 포함하도록 호출 요청을 업데이트합니다.

  • reviewsUrl가 삭제되었습니다.

  • adsLinks, googleMyBusinessLink, youtubeChannelLinks의 링크 상태(inactive)가 삭제되었습니다.

3. products 서비스 호출 업데이트

  • 맞춤 속성에 더 이상 유형과 단위가 포함되지 않습니다. 대신 값에 단위가 추가되며 유형은 자동으로 감지되어야 합니다.

  • 반복 필드 productTypes가 productType 및 additionalProductTypes를 모두 대체했습니다.

  • 반복 필드 includedDestinations 및 excludedDestinations가 반복 필드 destinations를 대체했습니다.

  • 다음 애드워즈 관련 필드의 이름이 변경되었습니다.

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • 다음 필드가 삭제되었습니다.

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • includeInvalidInsertedItems 매개변수가 삭제되었습니다. v2.1에서는 기본적으로 모든 제품이 반환됩니다.

  • 이제 products.get 또는 products.list를 통해 삽입된 제품을 검색할 수 있게 되기까지 몇 분 정도 지연이 발생합니다.

  • 반환된 offerId이 더 이상 입력 offerId와 동일하지 않을 수 있습니다. v2.1은 offerId의 선행 및 후행 공백을 잘라내고 여러 공백 문자를 하나로 병합합니다. 이 변경사항은 권장되는 offerId 구문을 준수하는 offerId 값에 영향을 주지 않습니다.

  • 이제 제품이 삽입되기 전에 가격이 검증됩니다. 값 문자열에는 +, -, ., 숫자 (예: 0~9). 쉼표는 더 이상 허용되지 않습니다.

  • products.insert 또는 products.update 호출의 응답에는 다음 속성만 포함됩니다.

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • v2 옵션 includeAttributes은 지원 중단되었습니다. 대신 products.get를 ProductId와 함께 사용하여 전체 제품 정보를 확인하세요.

4. productstatuses 서비스 호출 업데이트

  • product 속성이 includeAttributes 매개변수와 함께 삭제되었습니다. 상태에 해당하는 제품의 속성을 가져오려면 products 서비스를 사용하여 새 productId 필드의 값을 전달합니다.

  • includeInvalidInsertedItems 매개변수가 삭제되었습니다. 이제 제품이 유효한지와 관계없이 모든 제품의 productId가 반환됩니다.

  • destinationStatuses의 intention, approvalStatus, approvalPending 필드는 approved, disapproved, pending 중 하나일 수 있는 문자열인 status로 대체되었습니다.

  • dataQualityIssues을 itemLevelIssues로 대체했습니다.

5. datafeeds 서비스 호출 업데이트

  • 다음 대상 필드가 대체되었습니다.

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations 및 excludedDestinations

  • contentType = "product inventory update"이(가) 포함된 데이터 피드가 삭제되었습니다.

6. orders 및 TestOrders 서비스 호출을 업데이트합니다.

  • v2.1에서는 세금 데이터가 자동으로 계산되므로 호출에 세금 데이터가 포함되면 안 됩니다. Marketplace 공정성 법 (MFA) 또는 이와 유사한 주에서 주문이 이루어지면 세금 데이터가 포함된 호출이 실패합니다. MFA가 아닌 주에서 주문이 처리되면 판매자 센터에 구성된 설정에 따라 세금이 계산됩니다. 구성되지 않은 경우 계산된 세금은 0입니다.

  • InStoreRefundLineItem 및 ReturnRefundLineItem 필드 amountPretax 및 amountTax가 각각 priceAmount 및 taxAmount로 대체되었습니다. priceAmount는 주문 위치에 따라 세전 또는 세후일 수 있습니다.

  • 요청의 ShipLineItem 필드 carrier, shipmentId, trackingId를 shipmentInfos로 이동했습니다.

  • 이제 billingAddress 및 predefinedBillingAddress는 orders 및 TestOrder에서 각각 최상위 필드입니다.

  • customer.explicitMarketingPreference가 customer.marketingRightsInfo로 대체되었습니다.

  • netAmount 필드가 netPriceAmount와 netTaxAmount로 분할되었습니다.

  • shippingOption을 lineItems[].shippingDetails로 대체했습니다.

  • 요청의 CancelLineItem 필드 amount, amountPretax, amountTax가 삭제되었습니다. 이제 환불 금액이 자동으로 계산됩니다.

  • CustomBatch를 삭제했습니다.

  • Refund를 삭제했습니다. 대신 refundOrder 또는 refundItem를 사용하세요.

  • paymentMethod 필드가 삭제되었습니다.

  • v2 메서드 orders.returnlineitem와 orders.refund가 orderreturns.creatOrderReturn 및 orderreturns.process로 대체되었습니다.

  • customer.email, channelType, lineItem.product.channel 필드가 삭제되었습니다.

  • promotions 필드가 TestOrder 서비스에서 삭제되고 Order에서 형식이 변경되었습니다.

7. orderinvoice 서비스 호출 업데이트

  • amountPretax 및 amountTax 필드가 각각 priceAmount 및 taxAmount로 대체되었습니다. priceAmount 필드는 주문 위치에 따라 세전 또는 세후일 수 있습니다.

  • invoiceSummary 및 프로모션 청구 관련 필드에서 잔액 (판매자, 고객, Google)이 삭제되었습니다.

8. v2.1에 포함되지 않은 기능 삭제

다른 몇 가지 기능은 v2.1의 Content API에서 삭제되었습니다. 다음 목록을 검토하고 필요에 따라 애플리케이션을 업데이트하세요.

  • XML은 더 이상 지원되지 않습니다. JSON으로 전환하는 방법에 관한 자세한 내용은 Content API for Shopping의 XML 지원 종료를 참조하세요.

  • dryRun 매개변수가 삭제되었습니다. 이 변경사항은 모든 API 호출에 적용됩니다.

  • 모든 HTTP BATCH 메서드를 삭제했습니다. 대신 customBatch를 사용합니다.

  • 다음 서비스에서 patch 메서드가 삭제되었습니다.

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • orderpayments 서비스가 삭제되었습니다.

이전 테스트

v2.1로 마이그레이션한 후 애플리케이션 변경사항을 테스트하는 방법에 대한 자세한 내용은 Content API for Shopping 사용 테스트를 참조하세요. 업데이트를 테스트하는 동안 문제가 발생하면 Content API 포럼에 문제를 게시할 수 있습니다.

v2.1의 추가 변경사항

업데이트가 필요한 변경사항 외에도 v2.1에는 몇 가지 새로운 기능과 브레이킹 체인지가 아닌 변경사항이 도입되었습니다.

  • 새로운 서비스:

    • 새로운 localinventory 서비스를 사용하면 v2의 inventory 서비스 대신 로컬 제품을 업데이트할 수 있습니다.

    • 새로운 orderreturns 서비스를 사용하면 orders 서비스를 사용하지 않고도 반품을 처리할 수 있어 Buy on Google (이전의 Shopping Actions)을 더 쉽게 관리할 수 있습니다.

  • 보조 피드를 사용하면 제품을 부분적으로 업데이트할 수 있습니다.

  • products 서비스의 추가 변경사항:

    • products.insert 요청에서 더 이상 심각하지 않은 경고나 오류를 보고하지 않습니다. 이렇게 하면 Content API 외부에서 관리되는 피드와 마찬가지로 판매자 센터의 피드 규칙을 통해 제품을 삽입하고 후속 업데이트를 통해 문제를 해결할 수 있습니다.

    • 선택한 제품 필드 집합을 업데이트할 수 있도록 products.update가 추가되었습니다. 가능한 사용에 관한 자세한 내용은 가이드를 참고하세요.

    • 다음 속성 값이 잘못되면 더 이상 삽입 오류가 발생하지 않으며 productstatus 서비스에서 itemLevelIssues의 일부로 반환됩니다.

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • 이제 커스텀 속성이 재귀적이므로 커스텀 그룹이 필요하지 않습니다.

    • 이제 맞춤 속성에 원래 value 필드 외에 groupValues 필드가 있습니다. 필드 중 하나만 설정해야 합니다.