จัดการการจัดกลุ่มตามภูมิภาค

ภูมิภาค Merchant API แสดงถึงภูมิภาคทางภูมิศาสตร์ที่คุณใช้เป็นเป้าหมายที่เกี่ยวข้องกับทรัพยากร accounts.products.regionalInventories ได้ คุณสามารถกำหนดภูมิภาคเป็นคอลเล็กชันของรหัสไปรษณีย์ หรือในบางประเทศ ให้ใช้การกำหนดเป้าหมายตามภูมิศาสตร์ที่กำหนดไว้ล่วงหน้า ดูข้อมูลเพิ่มเติมได้ที่ตั้งค่า ภูมิภาค

Merchant API มีปลายทางแบบกลุ่มสำหรับการจัดการภูมิภาค ซึ่งช่วยให้คุณสร้าง อัปเดต และลบภูมิภาคได้สูงสุด 100 ภูมิภาคในการเรียก API ครั้งเดียว วิธีนี้เหมาะสำหรับผู้ขายที่จัดการความพร้อมจำหน่ายสินค้าและการกำหนดราคาระดับภูมิภาค (RAAP) ในวงกว้าง ซึ่งช่วยเพิ่มประสิทธิภาพและลดความซับซ้อนในการผสานรวม

ภาพรวม

Batch API ช่วยให้คุณทำสิ่งต่อไปนี้ได้ด้วยวิธีที่เกี่ยวข้อง

  • สร้างภูมิภาคหลายภูมิภาค ในคำขอเดียว: regions:batchCreate
  • ลบภูมิภาคหลายภูมิภาค พร้อมกัน: regions:batchDelete
  • อัปเดตภูมิภาคหลายภูมิภาค พร้อมกัน: regions:batchUpdate

ข้อกำหนดเบื้องต้น

คำขอแบบกลุ่มทั้งหมดต้องมีบทบาทผู้ใช้ผู้ดูแลระบบ สำหรับการตรวจสอบสิทธิ์

สร้างภูมิภาคหลายภูมิภาค

ตัวอย่างนี้แสดงวิธีสร้างภูมิภาคใหม่ 2 ภูมิภาค โดยภูมิภาคหนึ่งกำหนดโดยรหัสไปรษณีย์ และอีกภูมิภาคหนึ่งกำหนดโดยการกำหนดเป้าหมายตามภูมิศาสตร์ ในการเรียก BatchCreateRegions ครั้งเดียว

ส่งคำขอ

สร้าง URL คำขอได้ดังนี้

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate

เนื้อหาของคำขอมีรายการ requests ซึ่งแต่ละออบเจ็กต์จะระบุ regionId และข้อมูล region ที่จะสร้าง

{
  "requests": [
    {
      "regionId": "seattle-area-98340",
      "region": {
        "displayName": "Seattle Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98340"
            }
          ]
        }
      }
    },
    {
      "regionId": "co-de-states",
      "region": {
        "displayName": "Colorado and Delaware",
        "geoTargetArea": {
          "geotargetCriteriaIds": [
            "21138",
            "21141"
          ]
        }
      }
    }
  ]
}

การตอบกลับ

คำขอที่สำเร็จจะแสดงรายการออบเจ็กต์ region ใหม่

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
      "displayName": "Seattle Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98340"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
      "displayName": "Colorado and Delaware",
      "geotargetArea": {
        "geotargetCriteriaIds": [
          "21138",
          "21141"
        ]
      },
      "regionalInventoryEligible": false,
      "shippingEligible": false
    }
  ]
}

อัปเดตภูมิภาคหลายภูมิภาค

ตัวอย่างนี้แสดงวิธีใช้ BatchUpdateRegions เพื่ออัปเดต displayName และ postalCodeArea สำหรับภูมิภาคที่มีอยู่ 2 ภูมิภาค คุณต้องระบุ region.name เพื่ออัปเดตภูมิภาคเป้าหมาย

ส่งคำขอ

สร้าง URL คำขอได้ดังนี้

POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate

เนื้อหาของคำขอมีรายการ requests แต่ละออบเจ็กต์ต้องระบุข้อมูล region ที่จะอัปเดต ช่อง region.name ต้องมีรหัสของภูมิภาคที่จะอัปเดต เช่น "98005" ระบุทรัพยากรเป็น name แทนที่จะเป็น accounts/{ACCOUNT_ID}/regions/name. การใส่ updateMask เพื่อระบุช่องที่จะเปลี่ยนแปลงเป็นตัวเลือก

{
  "requests": [
    {
      "region": {
        "name": "98005",
        "displayName": "Seattle Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98330"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    },
    {
      "region": {
        "name": "07086",
        "displayName": "NewYork Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "11*"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    }
  ]
}

การตอบกลับ

คำขอที่สำเร็จจะแสดงรายการออบเจ็กต์ region ที่อัปเดต

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/98005",
      "displayName": "Seattle Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98330"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/07086",
      "displayName": "NewYork Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "11*"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    }
  ]
}

ลบภูมิภาคหลายภูมิภาค

คุณสามารถลบภูมิภาคหลายภูมิภาคในการเรียกครั้งเดียว

ส่งคำขอ

ตัวอย่างนี้แสดงวิธีใช้ BatchDeleteRegions เพื่อลบภูมิภาค 2 ภูมิภาคในการเรียกครั้งเดียว

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete

เนื้อหาของคำขอมีรายการ requests ซึ่งแต่ละออบเจ็กต์จะระบุ name (ไม่มี "accounts/{ACCOUNT_ID}/regions/") ของภูมิภาคที่จะลบ

{
  "requests":
   [
    {
      "name": "98005"
    },
    {
      "name": "07086"
    }
   ]
}

การตอบกลับ

คำขอที่สำเร็จจะแสดงเนื้อหาการตอบกลับที่ว่างเปล่า ซึ่งบ่งบอกว่าภูมิภาคที่ระบุถูกลบแล้ว (หรือไม่มีอยู่)

{}

ข้อจำกัด

โปรดทราบกฎต่อไปนี้ก่อนเริ่มต้น

  • การดำเนินการแบบอะตอมมิก: คำขอแบบกลุ่มเป็นการดำเนินการแบบอะตอมมิก หากการดำเนินการใดการดำเนินการหนึ่ง ในกลุ่มไม่สำเร็จ (เช่น สร้างภูมิภาคหนึ่งไม่สำเร็จ) กลุ่มทั้งหมดจะไม่สำเร็จ และจะไม่มีการเปลี่ยนแปลงใดๆ API จะแสดงข้อผิดพลาดที่ระบุสาเหตุของความล้มเหลว
  • ขีดจำกัดของกลุ่ม: คำขอแบบกลุ่มแต่ละรายการสามารถมีการดำเนินการกับภูมิภาคได้สูงสุด 100 รายการ
  • โควต้า: ปลายทางเหล่านี้ใช้กลุ่มโควต้าเดียวกับปลายทางที่มี การดำเนินการเดียว (regions.create, regions.delete, regions.update)

ข้อผิดพลาดและปัญหาที่พบได้ทั่วไป

ต่อไปนี้คือข้อผิดพลาดที่พบบ่อยและวิธีแก้ไข

"จำนวนคำขอในกลุ่มมีมากเกินไป"

ข้อผิดพลาดนี้เกิดขึ้นหากจำนวนการดำเนินการในอาร์เรย์คำขอเกินขีดจำกัดที่ 100 รายการ

"error":
  {
    "code": 400,
    "message": "The number of requests in a batch is too large.",
    "status": "INVALID_ARGUMENT"
  }

หากต้องการแก้ไข ให้แบ่งการดำเนินการออกเป็นคำขอแบบกลุ่มหลายรายการที่มีการดำเนินการไม่เกิน 100 รายการ

ไม่มีข้อมูลในช่องที่ต้องระบุ

ข้อผิดพลาดนี้เกิดขึ้นเมื่อไม่มีข้อมูลในช่องที่ต้องระบุ ข้อความแสดงข้อผิดพลาดจะระบุพารามิเตอร์ที่ขาดหายไป

ข้อความแสดงข้อผิดพลาดมีดังนี้

  • สำหรับ batchCreate: [regionId] Required parameter: regionId
  • สำหรับ batchUpdate: [region.name] Required field not provided.
  • สำหรับ batchDelete: [name] Required parameter: name

หากต้องการแก้ไข ให้ตรวจสอบว่ามีข้อมูลในช่องที่ต้องระบุทั้งหมดในการดำเนินการแต่ละรายการ เช่น ทุกรายการในคำขอ batchUpdate ต้องมี region.name การโพสต์คำขอต่อไปนี้จะทำให้เกิดข้อผิดพลาด

{
  "requests":
  [
    {
      "region":
        {
          "displayName": "An update without a region name"
        },
        "updateMask": "displayName"
    }
  ]
}

"มีภูมิภาคที่มีรหัสที่ระบุอยู่แล้ว"

ข้อผิดพลาดจะเกิดขึ้นหากคุณพยายามสร้างภูมิภาคที่มี regionId ที่มีอยู่แล้ว

ข้อความแสดงข้อผิดพลาดคือ [regionId] Region with specified id already exists.

หากต้องการแก้ไข ให้ตรวจสอบว่าค่า regionId ทั้งหมดไม่ซ้ำกันภายในกลุ่มและไม่ขัดแย้งกับภูมิภาคที่มีอยู่

"พบค่าที่ซ้ำกันสำหรับช่อง region.name หรือพบ regionId"

ข้อผิดพลาดจะเกิดขึ้นหากคุณพยายามสร้างหรืออัปเดตภูมิภาคหลายภูมิภาคที่มีรหัสเดียวกันภายในคำขอแบบกลุ่มเดียว

ข้อความแสดงข้อผิดพลาดคือ Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}.

หากต้องการแก้ไข ให้ตรวจสอบว่าค่า regionId ทั้งหมด (สำหรับ batchCreate) หรือ region.name (สำหรับ batchUpdate) ไม่ซ้ำกันภายในคำขอแบบกลุ่มเดียว

"ไม่พบรายการ"

เมื่อใช้ batchUpdate หากภูมิภาคใดภูมิภาคหนึ่งที่ระบุในคำขอไม่มีอยู่ กลุ่มทั้งหมดจะไม่สำเร็จและแสดงข้อผิดพลาด 404 NOT_FOUND ซึ่งแตกต่างจาก batchDelete ที่จะสำเร็จสำหรับภูมิภาคที่ไม่มีอยู่

"error": {
    "code": 404,
    "message": "item not found",
    "status": "NOT_FOUND"
}

หากต้องการแก้ไข ให้ตรวจสอบว่าภูมิภาคทั้งหมดที่คุณพยายามอัปเดตมีอยู่ก่อนที่จะส่งคำขอ

ก่อนหน้า
Create and update regions
ถัดไป
Manage Merchant Center email preferences