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à 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 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

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 những thay đổi mang tính đột phá đượ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 v2.1

Để thực hiện các 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 các điểm cuối mới của phiên bản 2.1.

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 toàn bộ thông tin 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 có thể gây lỗi được giới thiệu trong phiên bản 2.1. Xem lại các phần sau và cập nhật ứng dụng của bạn (nếu cần).

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

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

  • Sử dụng Nguồn cấp dữ liệu bổ sung mới hoặc products.update để 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 cả tất cả các trường đã được cập nhật trước đó bằng inventory.set (ngoại trừ những 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 tại địa phương.

2. Cập nhật 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ẽ hoàn toàn ghi đè 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 tất cả các trường vào.

  • reviewsUrl đã bị xoá.

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

3. Cập nhật 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 đó, các đơ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

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

  • Giờ đây, sẽ 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. v2.1 cắt bỏ 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ờ đây, giá đượ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 v2 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 đầy đủ thông tin sản phẩm.

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

  • Thuộc tính product đã bị xoá, 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.

  • Tham số includeInvalidInsertedItems đã bị xoá. 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 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

  • Đã xoá những nguồn cấp dữ liệu có contentType = "product inventory update".

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

  • Trong phiên bản 2.1, các lệnh gọi không được bao gồm dữ liệu thuế vì dữ liệu thuế được tính toán tự động. Nếu đơn đặt hàng được thực hiện ở một tiểu bang có Đạo luật công bằng của trang web thương mại (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 áp dụng MFA, thì thuế sẽ được tính dựa trên chế độ cài đặt mà bạn đã thiết lập trong Merchant Center. Nếu bạn không định cấu hình, thuế được tính sẽ 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à 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 di chuyển đến 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.

  • Xoá CustomBatch.

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

  • Đã xoá trường paymentMethod.

  • Các phương thức orders.returnlineitem và orders.refund 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 lệnh gọi đến dịch vụ orderinvoice

  • Các trường amountPretax và amountTax đã được thay thế bằng priceAmount và taxAmount. Trường priceAmount có thể là giá trước thuế hoặc giá 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 phiên bản 2.1. Xem xét 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.

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

  • Tất cả phương thức HTTP BATCH đều đã 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 phần Kiểm thử các trường hợp sử dụng Content API for Shopping. Nếu gặp vấn đề trong khi kiểm thử 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 cần 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à thay đổi không làm gián đoạn:

  • Dịch vụ mới:

    • Dịch vụ localinventory mới cho phép bạn cập nhật sản phẩm tại đị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ý 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ý việc trả lại hàng 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 dữ liệu 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 cảnh báo hoặc lỗi 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 nội dung 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 những nguồn cấp dữ liệu được quản lý bên ngoài Content API.

    • products.update đã được thêm để bạn có thể 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ác trường hợp sử dụng có thể, hãy xem hướng dẫn.

    • Các giá trị không hợp lệ cho những thuộc tính sau đây sẽ 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 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. Bạn phải đặt đúng một trong các trường.