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

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

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

ภาพรวม

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

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

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

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

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

หมายเหตุ: ระบบการประมวลผลแบบกลุ่มสำหรับ Google Ad Experience Report API ใช้ไวยากรณ์เดียวกับระบบการประมวลผลแบบกลุ่ม OData แต่ความหมายจะแตกต่างกัน

รายละเอียดแบทช์

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

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

รูปแบบของคำขอแบบกลุ่ม

คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียกใช้ Google Ad Experience Report API หลายรายการ โดยใช้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 รายการในคำขอเดียวไม่ได้ แต่ให้ส่งการเรียกใช้รายการแรกแยกต่างหาก จากนั้นรอการตอบกลับการเรียกใช้รายการแรกก่อนที่จะส่งการเรียกใช้รายการที่ 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--