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à tương lai.

Để biết thông tin về cách Merchant API có thể cải thiện quá trình tích hợp của bạn, cũng như cách bạn có thể giúp định hình tương lai, hãy xem phần Thông báo bản thử nghiệm API Merchant Center.

Dịch vụ regions giúp bạn tạo và quản lý những khu vực địa lý mà bạn có thể sử dụng làm mục tiêu với cả regionalinventory và shippingsettings luôn miễn phí. Bạn có thể xác định các khu vực là tập hợp mã bưu chính hoặc theo một số quốc gia, sử dụng mã định sẵn mục tiêu địa lý. 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 một khu vực ghi đè giá. Để 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ý – không phải 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 cùng với các dịch vụ Content API khác. Đố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 hai trường boolean, regionalInventoryEligible và shippingEligible, cho biết liệu bạn có thể sử dụng khu vực với các dịch vụ regionalinventory và shippingsettings, .

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 sẽ chỉ được chứa và phải chứa í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à môi trường trực tuyến tổng số người dùng.

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 quốc gia được 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 regions.create để tạo một khu vực được xác định là một tập hợp các mã bưu chính. Ví dụ dưới đây tạo ra 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 kèm theo URL dưới đây và yêu cầu nội dung:

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_regional" thì tức là bạn đã hết bộ nhớ trong tài khoản của bạn ở các khu vực.

Có giới hạn cố định là 2 MB dữ liệu cho regions và shippingsettings cho mỗi tài khoản Merchant Center. Chế độ cài đặt 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ụ, do đó, để MCA, bạn có thể nhanh chóng đạt đến hạn mức bộ nhớ. Trong trường hợp này, giải pháp tạm thời là để quản lý regions và shippingsettings ở cấp mã người bán. Không có giúp tăng hạn mức khu vực của bạn vượt quá giới hạn 2MB.

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ý, khu vực địa lý. 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. Người nhận tải xuống tệp csv của tất cả ID mục tiêu địa lý, bao gồm cả những mục tiêu địa lý có thể được sử dụng cùng với dịch vụ regions, hãy xem Mục tiêu địa lý. Ví dụ bên dưới 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 ba tiểu bang của Brazil.

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

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 bao gồm regionId và hai trường trạng thái đủ điều kiện. Nếu Giá trị của regionalInventoryEligible là true, bạn có thể dùng regionaliventory để tạo cơ chế ghi đè để đặt một mức giá khác cho khu vực. Chiến lược phát hành đĩa đơn ví dụ bên dưới sẽ tạo cơ chế ghi đè giá theo khu vực bằng cách sử dụng thông tin dựa trên mã bưu chính khu vực được tạo trong ví dụ ở trên, có regionId là "456789".

Để tạo chế độ ghi đè, hãy gửi một yêu cầu POST bằng URL sau và nội dung yêu cầu:

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

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