การรวมคำขอ Google Analytics API เป็นกลุ่ม

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

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

ภาพรวม

การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์ทำให้มีโอเวอร์เฮดจำนวนหนึ่ง Google Analytics API รองรับการทำงานแบบกลุ่ม เพื่อให้ไคลเอ็นต์ของคุณรวมการเรียก API หลายรายการไว้ในคำขอ HTTP รายการเดียว

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

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

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

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

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

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

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

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

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

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

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

ตัวอย่างการตอบกลับเป็นกลุ่ม

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

ไลบรารีของไคลเอ็นต์

ใช้คำแนะนำสำหรับไลบรารีไคลเอ็นต์ต่อไปนี้เพื่อดูวิธีใช้งาน แบบกลุ่มในภาษาของคุณ

โควต้าแบบกลุ่มและ Google Analytics

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

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

ขีดจำกัดการค้นหา 1.5 รายการต่อวินาที (QPS) ต่อรหัสบัญชีจะมีผลกับคำขอเขียน API การจัดการและคำขอเขียนของ API การจัดสรร ดังนั้น การรวมคำขอเขียนเหล่านี้เป็นกลุ่มอาจไม่ได้ช่วยปรับปรุงประสิทธิภาพ