Chuyển từ Content API phiên bản 2 sang phiên bản 2.1

Vào tháng 3 năm 2019, chúng tôi đã phát hành Content API for Shopping phiên bản 2.1. Vào tháng 4 năm 2021, chúng tôi đã thông báo rằng phiên bản 2 sẽ ngừng hoạt động vào ngày 30 tháng 9 năm 2021. Phiên bản 2 đã ngừng hoạt động. Vui lòng di chuyển sang phiên bản 2.1 ngay.

Di chuyển ứng dụng

Việc di chuyển từ phiên bản 2 sang phiên bản 2.1 bao gồm việc cập nhật URL điểm cuối để gọi các phiên bản 2.1 mới và sửa đổi ứng dụng để tính đến các thay đổi mang tính đột phá được giới thiệu trong phiên bản 2.1.

Cập nhật các lệnh gọi API để sử dụng điểm cuối 2.1

Để thực hiện lệnh gọi đến phiên bản 2.1, hãy cập nhật các yêu cầu để sử dụng điểm cuối 2.1 mới.

Ví dụ: để gọi phương thức products.get bằng phiên bản 2, bạn sẽ sử dụng:

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

Đối với phiên bản 2.1, hãy cập nhật URL thành:

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

Để biết thông tin đầy đủ về các dịch vụ và điểm cuối của phiên bản 2.1, hãy xem Tài liệu tham khảo về API.

Thực hiện các thay đổi bắt buộc

Ngoài việc cập nhật URL cho các lệnh gọi API, bạn cũng cần cập nhật ứng dụng để tính đến một số thay đổi mang tính đột phá được giới thiệu trong phiên bản 2.1. Xem các phần sau đây và cập nhật ứng dụng nếu cần.

1. Cập nhật các mục tích hợp với dịch vụ inventory

Dịch vụ inventory của phiên bản 2 đã bị xoá và chức năng tương đương có trong các tính năng sau của phiên bản 2.1:

2. Cập nhật các lệnh gọi đến dịch vụ accounts

  • Các lệnh gọi đến phương thức accounts.update trong phiên bản 2.1 sẽ ghi đè hoàn toàn tài nguyên accounts, thay vì chỉ cập nhật các trường có trong yêu cầu. Để tránh xoá các trường trên tài nguyên accounts, hãy cập nhật các yêu cầu gọi để đưa vào tất cả các trường.

  • Đã xoá reviewsUrl.

  • Đã xoá trạng thái liên kết inactive cho adsLinks, googleMyBusinessLink và youtubeChannelLinks.

3. Cập nhật các lệnh gọi đến dịch vụ products

  • Thuộc tính tuỳ chỉnh không còn chứa loại và đơn vị. Thay vào đó, đơn vị sẽ được thêm vào giá trị và các loại sẽ được tự động phát hiện.

  • Trường lặp lại productTypes đã thay thế cả productType và additionalProductTypes.

  • Các trường lặp lại includedDestinations và excludedDestinations đã thay thế trường lặp lại destinations.

  • Các trường sau đây liên quan đến AdWords đã được đổi tên:

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

  • Các trường sau đây đã bị xoá:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • Đã xoá tham số includeInvalidInsertedItems. Trong phiên bản 2.1, tất cả sản phẩm đều được trả về theo mặc định.

  • Hiện có một khoảng thời gian trễ vài phút trước khi bạn có thể truy xuất một sản phẩm đã chèn thông qua products.get hoặc products.list.

  • offerId được trả về không còn được đảm bảo giống với offerId đầu vào. Phiên bản 2.1 sẽ cắt khoảng trắng ở đầu và cuối trong offerId và hợp nhất nhiều ký tự khoảng trắng thành một. Thay đổi này không ảnh hưởng đến các giá trị offerId tuân thủ cú pháp offerId được đề xuất.

  • Giá hiện được xác thực trước khi chèn sản phẩm. Bạn chỉ được dùng các ký tự sau trong chuỗi giá trị: +, -, . và các chữ số (tức là 0-9). Dấu phẩy không còn được chấp nhận.

  • Phản hồi từ lệnh gọi products.insert hoặc products.update chỉ chứa các thuộc tính sau:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • Tuỳ chọn includeAttributes của phiên bản 2 không được dùng nữa. Thay vào đó, hãy sử dụng products.get với ProductId để xem thông tin đầy đủ về sản phẩm.

4. Cập nhật các lệnh gọi đến dịch vụ productstatuses

  • Đã xoá thuộc tính product cùng với tham số includeAttributes. Để truy xuất các thuộc tính của sản phẩm tương ứng với một trạng thái, hãy sử dụng dịch vụ products và truyền giá trị của trường productId mới.

  • Đã xoá tham số includeInvalidInsertedItems. productId của mọi sản phẩm hiện được trả về bất kể sản phẩm đó có hợp lệ hay không.

  • Các trường intention, approvalStatus và approvalPending trong destinationStatuses đã được thay thế bằng status. Đây là một chuỗi có thể là một trong các giá trị approved, disapproved hoặc pending.

  • dataQualityIssues đã được thay thế bằng itemLevelIssues.

5. Cập nhật các lệnh gọi đến dịch vụ datafeeds

  • Các trường mục tiêu sau đây đã được thay thế:

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations và excludedDestinations

  • Nguồn cấp dữ liệu có contentType = "product inventory update" đã bị xoá.

6. Cập nhật các lệnh gọi đến dịch vụ orders và TestOrders

  • Trong phiên bản 2.1, các lệnh gọi không được chứa dữ liệu thuế vì dữ liệu thuế được tính tự động. Nếu đơn đặt hàng được thực hiện ở một tiểu bang có Đạo luật về sự công bằng của thị trường (MFA) hoặc đạo luật tương tự, thì các lệnh gọi có chứa dữ liệu thuế sẽ không thành công. Nếu đơn đặt hàng được thực hiện ở một tiểu bang không có MFA, thì thuế sẽ được tính dựa trên các chế độ cài đặt được định cấu hình trong Merchant Center. Nếu không được định cấu hình, thuế được tính là 0.

  • Các trường InStoreRefundLineItem và ReturnRefundLineItem amountPretax và amountTax đã được thay thế bằng priceAmount và taxAmount tương ứng. priceAmount có thể là trước thuế hoặc sau thuế, tuỳ thuộc vào vị trí của đơn đặt hàng.

  • Các trường ShipLineItem carrier, shipmentId và trackingId trong yêu cầu đã được chuyển sang shipmentInfos.

  • billingAddress và predefinedBillingAddress hiện là các trường cấp cao nhất trong orders và TestOrder tương ứng.

  • customer.explicitMarketingPreference đã được thay thế bằng customer.marketingRightsInfo.

  • Trường netAmount đã được chia thành netPriceAmount và netTaxAmount.

  • shippingOption đã được thay thế bằng lineItems[].shippingDetails.

  • Các trường CancelLineItem amount, amountPretax và amountTax trong yêu cầu đã bị xoá. Số tiền hoàn lại hiện được tính tự động.

  • CustomBatch đã bị xoá.

  • Refund đã bị xoá. Thay vào đó, hãy sử dụng refundOrder hoặc refundItem.

  • Trường paymentMethod đã bị xoá.

  • Các phương thức orders.returnlineitem và orders.refund của phiên bản 2 được thay thế bằng orderreturns.creatOrderReturn và orderreturns.process.

  • Các trường customer.email, channelType và lineItem.product.channel đã bị xoá.

  • Trường promotions đã bị xoá khỏi dịch vụ TestOrder và định dạng của trường này đã thay đổi trong Order.

7. Cập nhật các lệnh gọi đến dịch vụ orderinvoice

  • Các trường amountPretax và amountTax đã được thay thế bằng priceAmount và taxAmount tương ứng. Trường priceAmount có thể là trước thuế hoặc sau thuế, tuỳ thuộc vào vị trí của đơn đặt hàng.

  • Đã xoá số dư (người bán, khách hàng, Google) trong invoiceSummary và các trường liên quan đến phí khuyến mãi.

8. Xoá chức năng không có trong phiên bản 2.1

Một số tính năng khác đã bị xoá khỏi Content API trong phiên bản 2.1. Xem danh sách sau đây và cập nhật ứng dụng nếu cần:

  • XML không còn được hỗ trợ nữa. Để biết thêm thông tin về cách chuyển sang JSON, hãy xem bài viết Ngừng hỗ trợ XML trong Content API for Shopping.

  • Đã xoá tham số dryRun. Thay đổi này áp dụng cho tất cả các lệnh gọi API.

  • Tất cả các phương thức HTTP BATCH đã bị xoá. Thay vào đó, hãy sử dụng customBatch.

  • Phương thức patch đã bị xoá khỏi các dịch vụ sau:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • Dịch vụ orderpayments đã bị xoá.

Kiểm thử quá trình di chuyển

Để biết thêm thông tin về cách kiểm thử các thay đổi đối với ứng dụng sau khi di chuyển sang phiên bản 2.1, hãy xem bài viết Kiểm thử các trường hợp sử dụng Content API for Shopping. Nếu gặp vấn đề khi kiểm thử các bản cập nhật, bạn có thể liên hệ với chúng tôi.

Các thay đổi khác trong phiên bản 2.1

Ngoài những thay đổi yêu cầu cập nhật, phiên bản 2.1 cũng giới thiệu một số tính năng mới và các thay đổi không mang tính đột phá:

  • Dịch vụ mới:

    • Dịch vụ localinventory mới cho phép bạn cập nhật sản phẩm địa phương (thay cho dịch vụ inventory trong phiên bản 2).

    • Dịch vụ orderreturns mới giúp bạn dễ dàng quản lý tính năng Mua trên Google (trước đây gọi là Mua sắm trên Google) bằng cách cho phép bạn xử lý hàng trả lại mà không cần sử dụng dịch vụ orders.

  • Nguồn cấp dữ liệu bổ sung cho phép bạn cập nhật một phần sản phẩm.

  • Các thay đổi khác đối với dịch vụ products:

    • Các yêu cầu products.insert không còn báo cáo các lỗi hoặc thông tin cảnh báo không nghiêm trọng. Điều này cho phép bạn chèn sản phẩm và thực hiện các bản cập nhật tiếp theo để giải quyết vấn đề thông qua quy tắc nguồn cấp dữ liệu trong Merchant Center, giống như cách bạn làm với các nguồn cấp dữ liệu được quản lý bên ngoài Content API.

    • products.update đã được thêm vào để cho phép bạn cập nhật một nhóm trường sản phẩm đã chọn. Để biết thêm thông tin về cách sử dụng có thể, hãy xem hướng dẫn.

    • Các giá trị không hợp lệ cho các thuộc tính sau đây không còn kích hoạt lỗi chèn và được trả về trong itemLevelIssues theo dịch vụ productstatus:

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

    • Các thuộc tính tuỳ chỉnh hiện có tính đệ quy, giúp bạn không cần dùng đến các nhóm tuỳ chỉnh.

    • Các thuộc tính tuỳ chỉnh hiện có trường groupValues ngoài trường value ban đầu. Bạn phải đặt chính xác một trong các trường.