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 phiên bản 2.1 của Content API for Shopping và vào tháng 4 năm 2021, chúng tôi thông báo về việc ngừng cung cấp phiên bản 2 vào ngày 30 tháng 9 năm 2021. Phiên bản v2 đã ngừng hoạt động. Vui lòng chuyển sang phiên bản 2.1 ngay lập tức.

Di chuyển ứng dụng

Để di chuyển từ phiên bản 2 sang phiên bản 2.1, bạn cần phải cập nhật URL điểm cuối để gọi các phiên bản v2.1 mới và sửa đổi các ứng dụng để tính đến những thay đổi có thể gây lỗi được giới thiệu trong phiên bản 2.1.

Cập nhật lệnh gọi API để sử dụng điểm cuối phiên bản 2.1

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

Ví dụ: để gọi phương thức products.get bằng v2, 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 phiên bản 2.1, hãy xem Tài liệu tham khảo 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 có thể gây lỗi được giới thiệu trong phiên bản 2.1. Xem các phần sau đây rồi cập nhật đơn đăng ký nếu cần.

1. Cập nhật các hoạt động tích hợp với dịch vụ inventory

Dịch vụ inventory v2 đã bị xoá và chức năng tương đương hiện có sẵn với các tính năng sau trong v2.1:

  • Sử dụng Nguồn cấp dữ liệu bổ sung hoặc products.update mới để cập nhật một phần sản phẩm. Bạn có thể cập nhật tất cả các trường sản phẩm có thể thay đổi, bao gồm tất cả các trường đã được cập nhật trước đó bằng inventory.set (ngoại trừ các trường dành riêng cho localinventory). Hãy xem bài viết Di chuyển sang nguồn cấp dữ liệu bổ sung để biết thêm thông tin chi tiết.

  • Sử dụng dịch vụ localinventory mới để cập nhật sản phẩm địa phương.

2. Cập nhật cuộc gọi lê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 yêu cầu gọi để đưa vào tất cả các trường.

  • reviewsUrl đã bị xoá.

  • Trạng thái liên kết inactive đã bị xoá cho adsLinks, googleMyBusinessLink và youtubeChannelLinks.

3. Cập nhật cuộc gọi lên dịch vụ products

  • Thuộc tính tuỳ chỉnh không còn chứa loại và đơn vị nữa. Thay vào đó, các đơn vị phải đượ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 có liên quan đến AdWords sau đây đã đượ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 được trả về theo mặc định.

  • Hiện có sự chậm trễ vài phút trước khi có thể truy xuất sản phẩm được chèn qua products.get hoặc products.list.

  • offerId được trả về không còn đảm bảo giống với offerId đầu vào. Phiên bản 2.1 cắt bỏ khoảng trắng ở đầu và ở cuối trong offerId, đồng thời 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. Chuỗi giá trị chỉ được chứa các ký tự sau: +, -, . và chữ số (tức là 0-9). Dấu phẩy không còn được chấp nhận nữa.

  • 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òn được dùng nữa. Thay vào đó, hãy sử dụng products.get cùng với ProductId để xem thông tin đầy đủ về sản phẩm.

4. Cập nhật cuộc gọi lê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. Giờ đây, productId của mọi sản phẩm sẽ đượ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 approved, disapproved hoặc pending.

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

5. Cập nhật cuộc gọi lê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ị xóa.

6. Cập nhật cuộc gọi lên dịch vụ orders và TestOrders

  • Trong phiên bản 2.1, các lệnh gọi không nên bao gồm 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 ở tiểu bang có Đạo luật công bằng thị trường (MFA) hoặc tương tự, thì các lệnh gọi bao gồm dữ liệu thuế sẽ không thành công. Nếu đơn đặt hàng được thực hiện ở trạng thái không phải là mã xác thực đa yếu tố (MFA), thì mức thuế sẽ được tính dựa trên chế độ cài đặt đã thiết lập 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 lần lượt được thay thế bằng priceAmount và taxAmount. priceAmount có thể là giá 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.

  • Thay thế customer.explicitMarketingPreference 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 sẽ được tính tự động.

  • Xoá CustomBatch.

  • Xoá Refund. 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 v2 đượ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 cuộc gọi lên dịch vụ orderinvoice

  • Các trường amountPretax và amountTax đã được thay thế lần lượt bằng priceAmount và taxAmount. Trường priceAmount có thể là trường 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 lại danh sách sau đây và cập nhật ứng dụng của bạn nếu cần:

  • XML không còn được hỗ trợ nữa. Để biết thêm thông tin về việc 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 mọi lệnh gọi API.

  • Đã xoá tất cả phương thức HTTP BATCH. Sử dụng customBatch thay thế.

  • 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ề việc kiểm thử các thay đổi đối với ứng dụng sau khi chuyển sang phiên bản 2.1, hãy xem phần Kiểm thử việc sử dụng Content API for Shopping. Nếu gặp vấn đề trong khi kiểm thử các bản cập nhật, bạn có thể đăng vấn đề đó lên diễn đàn Content API.

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

Ngoài các thay đổi bắt buộc phải 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 gây ra lỗi:

  • Dịch vụ mới:

    • Dịch vụ localinventory mới cho phép bạn cập nhật sản phẩm cục bộ (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ý chương trình Mua trên Google (trước đây gọi là Mua sắm Trực tiếp) 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 bổ sung đối với dịch vụ products:

    • Các yêu cầu products.insert không còn báo cáo lỗi hoặc 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à cập nhật những lần sau để 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 thực hiện với nguồn cấp dữ liệu được quản lý bên ngoài Content API.

    • Thêm products.update để cho phép bạn cập nhậ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ể áp dụng, hãy xem hướng dẫn.

    • Giá trị không hợp lệ cho các thuộc tính sau không còn kích hoạt lỗi chèn và được dịch vụ productstatus trả về như một phần của itemLevelIssues:

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

    • Các thuộc tính tuỳ chỉnh nay mang tính đệ quy nên bạn không cần phải có các nhóm tuỳ chỉnh.

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