Khu vực

Chúng tôi muốn giới thiệu phiên bản beta của API Người bán. Đây là phiên bản mới của Content API for Shopping và trong tương lai.

Để biết thông tin về cách API Merchant Center có thể cải thiện quá trình tích hợp của bạn và cách bạn có thể giúp định hình tương lai, hãy xem nội dung Công bố bản beta API Merchant Center.

Dịch vụ regions cho phép bạn tạo và quản lý các khu vực địa lý mà bạn có thể sử dụng làm mục tiêu bằng cả dịch vụ regionalinventory và shippingsettings. Bạn có thể xác định các khu vực dưới dạng tập hợp mã bưu chính hoặc ở một số quốc gia, bằng cách sử dụng các mục tiêu địa lý được xác định trước. Hướng dẫn này cung cấp các ví dụ về cách xác định từng loại khu vực, cũng như cách tạo cơ chế ghi đè giá theo khu vực. Để biết thêm thông tin về dịch vụ regions, bao gồm tất cả các phương thức và tham số có sẵn, hãy xem tài liệu tham khảo.

Lưu ý: Mỗi định nghĩa về khu vực chỉ có thể chứa mã bưu chính hoặc mục tiêu địa lý, chứ không thể chứa cả hai.

Điều kiện theo khu vực

Khi bạn tạo một khu vực, dịch vụ khu vực sẽ xác định xem bạn có thể sử dụng khu vực đó với các dịch vụ Content API khác hay không. Đối tượng phản hồi được trả về cho một lệnh gọi regions.create thành công bao gồm 2 trường boolean là regionalInventoryEligible và shippingEligible. Các trường này cho biết liệu bạn có thể sử dụng khu vực tương ứng với dịch vụ regionalinventory và shippingsettings hay không.

regionalInventoryEligible

Để đủ điều kiện sử dụng dịch vụ regionalinventory, khu vực phải đáp ứng các tiêu chí sau:

• regionId mà bạn chỉ định khi tạo khu vực chỉ được chứa chữ số và phải có ít nhất 6 chữ số.
• Khu vực này phải đáp ứng các yêu cầu tối thiểu về kích thước đối với khu vực địa lý và dân số trực tuyến.

shippingEligible

Để đủ điều kiện sử dụng dịch vụ shippingsettings, khu vực phải đáp ứng các tiêu chí sau:

• Bạn phải xác định khu vực bằng mã bưu chính.
• Khu vực này phải thuộc một quốc gia được dịch vụ shippingsettings hỗ trợ.

Mẫu

Dưới đây là mã mẫu đầy đủ mà bạn có thể sử dụng để tạo một khu vực mới trong Java:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package shopping.content.v2_1.samples.regions;

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.services.content.model.Region;
import com.google.api.services.content.model.RegionPostalCodeArea;
import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import shopping.content.v2_1.samples.ContentSample;

/**
 * Creates a region. The region created here can be used with the regional inventory service.
 * Regional availability and pricing lets you provide product availability and variable pricing
 * based on your business presence and the location of your customer base. Regional availability and
 * pricing is available for products advertised through Shopping ads on Google Search, and listed in
 * free listings on the Shopping tab.
 */
public class RegionCreateSample extends ContentSample {
  public RegionCreateSample(String[] args) throws IOException {
    super(args);
  }

  @Override
  public void execute() throws IOException {
    checkNonMCA();

    // Creates a List of Postal Code Area Postal Code Ranges.
    // This allows you to flexibly define regions as combinations of postal code
    // ranges. Each postal code range in the list has its own start and end zip code.
    List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges =
        new ArrayList<RegionPostalCodeAreaPostalCodeRange>();

    // Creates a new postal code range from two postal code values.
    // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)
    RegionPostalCodeAreaPostalCodeRange postalCodeRange =
        new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925");

    // Adds the NY State postal code range into the list of postal code ranges that a postal
    // code area accepts.
    postalCodeRanges.add(postalCodeRange);

    // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code
    // ranges, and the US CLDR territory/country code that the postal code ranges applies to.
    RegionPostalCodeArea postalCodeArea =
        new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US");

    // Creates a region with example values for displayName and postalCodeArea
    Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea);

    // Tries to create the region, and catches any exceptions
    try {
      System.out.println("Creating region");
      Region result =
          content
              .regions()
              .create(this.config.getMerchantId().longValue(), region)
              .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits
              .execute();
      System.out.println("Listing succesfully created region");
      System.out.println(result);
    } catch (GoogleJsonResponseException e) {
      checkGoogleJsonResponseException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    new RegionCreateSample(args).execute();
  }
}

Tạo khu vực bằng mã bưu chính

Bạn có thể sử dụng phương thức regions.create để tạo một khu vực được xác định là tập hợp các mã bưu chính. Ví dụ dưới đây sẽ tạo một khu vực mới cho tiểu bang Arizona của Hoa Kỳ bằng cách chỉ định một phạm vi mã bưu chính.

Để tạo khu vực, hãy gửi yêu cầu POST với URL sau đây và nội dung yêu cầu:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

Lưu ý: Nếu gặp lỗi "quota/too_many_region" (hạn mức/quá_nhiều_khu vực), tức là bạn đã hết bộ nhớ trong tài khoản dành cho các khu vực.

Mỗi tài khoản Merchant Center có giới hạn cố định là 2 MB dữ liệu đối với regions và shippingsettings. Chế độ cài đặt về thông tin vận chuyển và khu vực được sao chép nội bộ từ MCA sang tất cả các tài khoản phụ của tài khoản đó. Vì vậy, đối với những MCA lớn hơn, bạn có thể nhanh chóng đạt đến hạn mức bộ nhớ. Trong trường hợp này, có một giải pháp là quản lý regions và shippingsettings ở cấp mã người bán. Không có cách nào để tăng hạn mức khu vực của bạn vượt quá giới hạn 2 MB.

Tạo khu vực bằng cách sử dụng các mục tiêu địa lý

Đối với các khu vực ở Brazil và Nga, bạn cũng có thể sử dụng phương thức regions.create để tạo một khu vực được xác định là tập hợp các mục tiêu địa lý, là các khu vực địa lý được xác định trước. Ví dụ về các loại mục tiêu địa lý bao gồm quốc gia, tiểu bang, thành phố, vùng lân cận và sân bay. Tuy nhiên, dịch vụ regions hiện chỉ hỗ trợ loại "Tiểu bang" tại Brazil và loại "Khu vực" tại Nga. Để tải tệp csv của tất cả mã mục tiêu địa lý, bao gồm cả những mục tiêu địa lý có thể dùng với dịch vụ regions, hãy xem phần Mục tiêu địa lý. Ví dụ dưới đây sẽ tạo một khu vực mới bằng cách cung cấp mã mục tiêu địa lý của 3 tiểu bang ở Brazil.

Để tạo khu vực, hãy gửi yêu cầu POST bằng URL sau đây và nội dung yêu cầu:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

Sử dụng các khu vực để tạo thông tin thay thế về giá theo khu vực

Khi bạn tạo một khu vực, dịch vụ regions sẽ trả về một đối tượng phản hồi có chứa regionId và hai trường trạng thái đủ điều kiện. Nếu giá trị regionalInventoryEligible là true, bạn có thể sử dụng dịch vụ regionaliventory để tạo cơ chế ghi đè để đặt mức giá khác cho khu vực. Ví dụ bên dưới sẽ tạo cơ chế ghi đè giá theo khu vực bằng cách sử dụng khu vực dựa trên mã bưu chính đã tạo trong ví dụ ở trên, khu vực này có regionId là "456789".

Để tạo chế độ ghi đè, hãy đưa ra yêu cầu POST bằng cách sử dụng URL và nội dung yêu cầu sau:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory

{
  “regionId”: "456789"
  “price”: {
    value: “10”
    currency: “USD”
  },
  “availability”: “in stock”
}