ส่งคําขอแบบกลุ่ม

แนวทางหนึ่งในการเข้าถึงกลุ่มโดยเฉพาะ นั่นคือปลายทาง HTTP กลุ่มทั่วโลก (www.googleapis.com/batch) ได้ปิดตัวลงในวันที่ 12 สิงหาคม 2020 ตามที่ประกาศไว้ในบล็อก Google Developers วิธีอื่นๆ ในการจัดกลุ่มยังคงทํางานอยู่ ตามที่ระบุไว้ในเอกสารอื่นๆ ในหน้านี้ หากโค้ดใช้ปลายทางกลุ่มการดําเนินการของ HTTP ทั่วโลก ให้ดูบล็อกโพสต์สําหรับคําแนะนําเกี่ยวกับการเปลี่ยนเพื่อใช้วิธีการอื่นๆ เช่น ปลายทางกลุ่ม HTTP เฉพาะสําหรับ API (www.googleapis.com/batch/API/VERSION)

เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เพื่อลดจํานวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง

เอกสารนี้เน้นเกี่ยวกับการส่งคําขอแบบกลุ่มโดยการส่งคําขอ HTTP แต่หากคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคําขอแบบกลุ่ม โปรดดูที่ไลบรารีของไคลเอ็นต์'

ภาพรวม

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

ตัวอย่างของสถานการณ์ที่คุณอาจต้องการใช้กลุ่ม

• คุณเพิ่งเริ่มต้นใช้ API และคุณมีข้อมูลที่จะอัปโหลดมากมาย
• ผู้ใช้มีการเปลี่ยนแปลงข้อมูลขณะที่แอปพลิเคชันของคุณออฟไลน์ (ยกเลิกการเชื่อมต่อจากอินเทอร์เน็ต) ดังนั้นแอปพลิเคชันของคุณจะต้องซิงค์ข้อมูลในเครื่องของตนกับเซิร์ฟเวอร์โดยส่งการอัปเดตและการลบจํานวนมาก

ในแต่ละกรณี คุณจะจัดกลุ่มคําขอเหล่านั้นเป็นคําขอ HTTP รายการเดียวแทนที่จะส่งการเรียกแต่ละครั้งแยกกันได้ คําขอภายในทั้งหมดต้องไปที่ Google API เดียวกัน

คุณจะโทรได้ไม่เกิน 1,000 ครั้งในคําขอกลุ่มเดียว หากต้องการโทรออกมากกว่านั้น ให้ใช้คําขอแบบกลุ่มหลายรายการ

หมายเหตุ: ระบบกลุ่มสําหรับ API รายงานประสบการณ์ใช้งานโฆษณา Google ใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่มข้อมูล แต่ความหมายจะแตกต่างกัน

รายละเอียดแบบกลุ่ม

คําขอแบบกลุ่มประกอบด้วยการเรียก API จํานวนมากที่รวมเป็นคําขอ HTTP รายการเดียว ซึ่งจะส่งไปยัง batchPath ที่ระบุไว้ในเอกสารการค้นพบ API เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้จะอธิบายไวยากรณ์ของกลุ่มโดยละเอียด และมีตัวอย่างในภายหลัง

หมายเหตุ: ชุดคําขอ n ที่จัดกลุ่มเข้าด้วยกันจะนับเป็นขีดจํากัดการใช้งานเป็นคําขอ n ไม่ใช่คําขอ 1 รายการ คําขอแบบกลุ่มจะแยกออกเป็นชุดคําขอก่อนประมวลผล

รูปแบบคําขอแบบกลุ่ม

คําขอแบบกลุ่มคือคําขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก API รายงานประสบการณ์ใช้งานโฆษณา Google หลายรายการ โดยใช้ประเภทเนื้อหา multipart/mixed คําขอ HTTP หลักคําขอแต่ละรายการคําขอแต่ละรายการจะมีคําขอ HTTP ที่ฝังอยู่

แต่ละส่วนเริ่มต้นด้วยส่วนหัว HTTP ของ Content-Type: application/http ของตัวเอง นอกจากนี้ยังอาจมีส่วนหัว Content-ID ที่ไม่บังคับด้วย อย่างไรก็ตาม ส่วนหัวของส่วนมีไว้เพื่อทําเครื่องหมายจุดเริ่มต้นของส่วนเท่านั้น แยกจากคําขอที่ซ้อนกัน หลังจากที่เซิร์ฟเวอร์แยกคําขอแบบกลุ่มออกเป็นคําขอที่แยกต่างหาก ระบบจะไม่สนใจส่วนหัวของส่วน

ตัวข้อมูลแต่ละส่วนเป็นคําขอ HTTP ที่สมบูรณ์ในตัวเอง โดยมีกริยา, URL, ส่วนหัว และเนื้อหาของตัวเอง คําขอ HTTP ต้องมีเฉพาะส่วนเส้นทางของ URL ไม่อนุญาตให้ใช้ URL แบบเต็มในคําขอแบบกลุ่ม

ส่วนหัว HTTP สําหรับคําขอแบบกลุ่มด้านนอก มีผลกับคําขอทุกรายการในกลุ่ม ยกเว้นส่วนหัว Content- เช่น Content-Type หากคุณระบุส่วนหัว HTTP หนึ่งๆ ทั้งในคําขอภายนอกและการเรียกใช้แต่ละครั้ง ค่าของส่วนหัวการโทรแต่ละครั้งจะลบล้างค่าของคําขอกลุ่มนอก' ส่วนหัวสําหรับการโทรแต่ละครั้งมีผลกับการโทรนั้นเท่านั้น

ตัวอย่างเช่น หากคุณระบุส่วนหัว "การให้สิทธิ์" สําหรับการโทรหนึ่งๆ ส่วนหัวดังกล่าวจะมีผลกับการโทรนั้นเท่านั้น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับคําขอภายนอก ส่วนหัวดังกล่าวจะมีผลกับการเรียกแต่ละรายการทั้งหมด เว้นแต่ส่วนหัวเหล่านั้นจะลบล้างด้วยส่วนหัวการให้สิทธิ์ของตนเอง

เมื่อเซิร์ฟเวอร์ได้รับคําขอแบบกลุ่ม เซิร์ฟเวอร์จะใช้พารามิเตอร์การค้นหาและส่วนหัวด้านนอก (ที่เหมาะสม) กับแต่ละส่วน แล้วจัดการแต่ละส่วนเสมือนว่าเป็นคําขอ HTTP คนละรายการ

การตอบกลับคําขอแบบกลุ่ม

การตอบกลับของเซิร์ฟเวอร์คือการตอบกลับ HTTP มาตรฐานเดียวที่มีประเภทเนื้อหา multipart/mixed โดยแต่ละส่วนคือการตอบกลับหนึ่งในคําขอในคําขอแบบกลุ่มตามลําดับเดียวกันกับคําขอ

คําขอแต่ละรายการมีการตอบสนอง HTTP ที่สมบูรณ์ ซึ่งรวมถึงส่วนต่างๆ ในคําขอ เช่น รหัสสถานะ ส่วนหัว และเนื้อหา และเหมือนกับส่วนในคําขอ ส่วนหัวการตอบกลับแต่ละรายการจะมีส่วนหัว Content-Type ที่เป็นตัวทําเครื่องหมายตอนต้นของส่วน

หากส่วนหนึ่งๆ ของคําขอมีส่วนหัว Content-ID ส่วนที่เกี่ยวข้องของการตอบกลับจะมีส่วนหัว Content-ID ที่ตรงกัน โดยมีค่าเดิมนําหน้าด้วยสตริง response- ดังที่แสดงในตัวอย่างต่อไปนี้

หมายเหตุ: เซิร์ฟเวอร์อาจทําการโทรตามลําดับใดก็ได้ โปรดอย่านับการดําเนินการตามลําดับที่คุณระบุ หากต้องการมั่นใจได้ว่าจะมีการโทร 2 ครั้งตามลําดับที่กําหนด คุณจะส่งพร้อมกันในคําขอเดียวไม่ได้ แต่ให้ส่งการโทรครั้งแรกไปเองแทน จากนั้นรอให้คําตอบแรกก่อนที่จะส่งลําดับที่ 2

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้แบบกลุ่มกับ Google Ad Experience Report API

ตัวอย่างคําขอแบบกลุ่ม

  POST /batch/v1?key=key HTTP/1.1
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: id1

  GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1

  --batch_aer
  Content-Type: application/http
  Content-ID: id2

  GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1

  --batch_aer--
  

ตัวอย่างการตอบกลับแบบกลุ่ม

นี่คือการตอบกลับคําขอตัวอย่างในส่วนก่อนหน้า

  HTTP/1.1 200 OK
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id1

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site1",
    "mobileSummary": {
      "lastChangeTime": "2019-02-05T09:46:26.521747Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2019-02-07T23:07:29.017206Z",
      "betterAdsStatus": "FAILING",
      "enforcementTime": "2018-02-15T15:00:00Z",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
      "filterStatus": "ON"
    }
  }

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id2

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site2",
    "mobileSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
      "filterStatus": "OFF"
    }
  }

  --batch_aer--