ขีดจำกัดการใช้งาน

ตั้งแต่วันที่ 1 พฤษภาคม 2026 เป็นต้นไป ขีดจำกัดการใช้งานสำหรับ API นี้ได้รับการอัปเดตแล้ว โปรเจ็กต์ Google Cloud ที่ใช้ API นี้ระหว่างเดือนพฤศจิกายน 2025 ถึงเมษายน 2026 จะยังคงใช้โควต้าการใช้งานที่ตั้งไว้ก่อนหน้านี้ต่อไป โปรเจ็กต์ที่อยู่ในระบบคลาวด์ที่สร้างขึ้นตั้งแต่วันที่ 1 พฤษภาคม 2026 เป็นต้นไปจะขึ้นอยู่กับโควต้า API ใหม่

ดูข้อมูลเพิ่มเติม รวมถึงไทม์ไลน์ได้ที่โมเดลมาตรฐานของ Google Workspace สำหรับเครื่องมือและ API ของ Agent

โปรดดูประกาศฉบับเต็มที่หัวข้อเครื่องมือ Agent และการอัปเดตความปลอดภัยสำหรับนักพัฒนาแอป Google Workspace

Google ปฏิทิน API มีโควต้าเพื่อให้มั่นใจว่าผู้ใช้ทุกคนจะใช้งานได้อย่างเป็นธรรม ข้อจำกัดสำคัญ 3 ประการที่ควรพิจารณาเมื่อใช้ Calendar API มีดังนี้

• โควต้าการใช้งาน API: บังคับใช้ต่อโปรเจ็กต์และต่อผู้ใช้ โปรดดูข้อมูลเพิ่มเติมที่หัวข้อประเภทโควต้าการใช้งาน Calendar API

• ขีดจำกัดการใช้งาน Google ปฏิทินทั่วไป: Google Calendar API เป็นบริการที่ใช้ร่วมกันซึ่งมีข้อจำกัดเพื่อปกป้องประสิทธิภาพโดยรวมของระบบ Google Workspace ดูข้อมูลเพิ่มเติมได้ที่หัวข้อหลีกเลี่ยงขีดจำกัดการใช้งานปฏิทิน

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

โควต้า Calendar API

ระบบจะบังคับใช้โควต้า 2 ประเภท ได้แก่

• ต่อนาทีต่อโปรเจ็กต์: จำนวนคำขอที่โปรเจ็กต์ Google Cloud ส่งได้ใน 1 นาที

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

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

ตารางต่อไปนี้แสดงรายละเอียดขีดจำกัดเหล่านี้

ประเภทขีดจำกัดการใช้งาน	ขีดจำกัด
ต่อนาทีต่อโปรเจ็กต์	คำขอ 10,000 รายการ
ต่อนาทีต่อผู้ใช้ต่อโปรเจ็กต์	คำขอ 600 รายการ

เกณฑ์การเรียกเก็บเงินรายวัน

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

การใช้งานที่ต่ำกว่าเกณฑ์นี้จะไม่ทำให้เกิดค่าใช้จ่ายเพิ่มเติม และระบบจะไม่เรียกเก็บเงินจากบัญชี Google Cloud ของคุณ เราจะแชร์รายละเอียดการเรียกเก็บเงินทั้งหมดในภายหลังในปี 2026 โดยจะแจ้งให้ทราบล่วงหน้าอย่างน้อย 90 วันก่อนที่การเปลี่ยนแปลงจะมีผล

คุณไม่สามารถขอเพิ่มเกณฑ์รายวันนี้ได้

ตารางต่อไปนี้แสดงรายละเอียดขีดจำกัด

ประเภทเกณฑ์การชำระเงิน	ขีดจำกัด
ต่อวันต่อโปรเจ็กต์	คำขอ 1,000,000 รายการ

ดูข้อมูลเพิ่มเติมได้ที่โมเดลมาตรฐานของ Google Workspace สำหรับเครื่องมือและ API ของ Agent

แก้ไขข้อผิดพลาดเกี่ยวกับโควต้าตามเวลา

สำหรับข้อผิดพลาดที่อิงตามเวลาทั้งหมด (คำขอสูงสุด N รายการต่อ X นาที) เราขอแนะนำให้โค้ดของคุณตรวจจับข้อยกเว้นและใช้ Truncated Exponential Backoff เพื่อให้แน่ใจว่าอุปกรณ์จะไม่สร้างภาระงานมากเกินไป

Exponential Backoff เป็นกลยุทธ์การจัดการข้อผิดพลาดมาตรฐานสำหรับแอปพลิเคชันเครือข่าย อัลกอริทึม Exponential Backoff จะลองส่งคำขออีกครั้งโดยใช้เวลารอที่เพิ่มขึ้นแบบทวีคูณระหว่างคำขอแต่ละรายการ จนถึงเวลา Backoff สูงสุด หากคำขอยังคงไม่สำเร็จ คุณต้องเพิ่มความล่าช้าระหว่างคำขอเมื่อเวลาผ่านไปจนกว่าคำขอจะสำเร็จ

ตัวอย่างอัลกอริทึม

อัลกอริทึม Exponential Backoff จะลองส่งคำขอซ้ำแบบทวีคูณ โดยเพิ่มเวลารอระหว่างการลองใหม่จนถึงเวลา Backoff สูงสุด เช่น

1. ส่งคำขอไปยัง Google ปฏิทิน API
2. หากคำขอล้มเหลว ให้รอ 1 + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
3. หากคำขอล้มเหลว ให้รอ 2 + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
4. หากคำขอล้มเหลว ให้รอ 4 + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
5. และอื่นๆ จนถึงครั้งที่ maximum_backoff
6. รอต่อไปและลองใหม่จนกว่าจะถึงจำนวนครั้งสูงสุดที่อนุญาต แต่ไม่ต้องเพิ่มระยะเวลารอระหว่างการลองใหม่แต่ละครั้ง

โดยที่

• เวลารอคือ min(((2^n)+random_number_milliseconds), maximum_backoff) โดย n จะเพิ่มขึ้น 1 สำหรับการทำซ้ำ (คำขอ) แต่ละครั้ง
• random_number_milliseconds คือจำนวนมิลลิวินาทีแบบสุ่มที่น้อยกว่าหรือเท่ากับ 1,000 ซึ่งจะช่วยหลีกเลี่ยงกรณีที่ไคลเอ็นต์จำนวนมากซิงค์ข้อมูลตามสถานการณ์บางอย่างและลองใหม่ทั้งหมดพร้อมกัน โดยส่งคำขอเป็นคลื่นที่ซิงค์ข้อมูล ระบบจะคำนวณค่าของ random_number_milliseconds ใหม่หลังจากคำขอให้ลองอีกครั้งแต่ละรายการ
• maximum_backoff มักจะมีความยาว 32 หรือ 64 วินาที ค่าที่เหมาะสมจะขึ้นอยู่กับกรณีการใช้งาน

ไคลเอ็นต์จะลองอีกครั้งได้หลังจากถึงเวลา maximum_backoff การลองใหม่หลังจากจุดนี้ไม่จำเป็นต้องเพิ่มเวลา Backoff ต่อไป ตัวอย่างเช่น หากไคลเอ็นต์ใช้เวลา maximum_backoff 64 วินาที หลังจากถึงค่านี้แล้ว ไคลเอ็นต์จะลองใหม่ได้ทุกๆ 64 วินาที เมื่อถึงจุดหนึ่ง คุณควรป้องกันไม่ให้ไคลเอ็นต์ลองใหม่ไปเรื่อยๆ อย่างไม่มีที่สิ้นสุด

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

ราคา

การใช้งาน Google ปฏิทิน API แบบมาตรฐานทั้งหมดจะไม่มีค่าใช้จ่ายเพิ่มเติม เราวางแผนที่จะเรียกเก็บเงินจากบัญชีสำหรับการเรียกเก็บเงินใน Google Cloud ของคุณในภายหลังในปี 2026 หากคำขอเกินขีดจำกัดโควต้า ดูข้อมูลเพิ่มเติมได้ที่โมเดลมาตรฐานของ Google Workspace สำหรับเครื่องมือและ API ของ Agent

ขอเพิ่มโควต้า

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

โปรเจ็กต์ทั้งหมดมีโควต้าไม่เท่ากัน เมื่อคุณใช้ Google Cloud มากขึ้นเรื่อยๆ คุณอาจต้องเพิ่มค่าโควต้า หากคาดว่าการใช้งานจะเพิ่มขึ้นอย่างเห็นได้ชัดในอนาคต คุณสามารถขอปรับโควต้าล่วงหน้าได้จากหน้าโควต้าและขีดจำกัดของระบบในคอนโซล Google Cloud

ดูข้อมูลเพิ่มเติมได้ที่แหล่งข้อมูลต่อไปนี้

• เกี่ยวกับการปรับโควต้า
• ดูการใช้งานและขีดจำกัดโควต้า
• ขอเพิ่มขีดจำกัดโควต้า

แก้ปัญหา

หากเกินโควต้าอย่างใดอย่างหนึ่ง ระบบจะจำกัดอัตราคำขอและคุณจะได้รับรหัสสถานะ 403 usageLimits หรือรหัสสถานะ 429 usageLimits ในการตอบกลับคำค้นหา

หากเกิดเหตุการณ์นี้ขึ้น คุณสามารถลองทำดังนี้

1. โปรดปฏิบัติตามแนวทางปฏิบัติแนะนำทั้งหมด ซึ่งได้แก่ ใช้ Exponential Backoff, สุ่มรูปแบบการเข้าชม และใช้ข้อความ Push

2. หากโปรเจ็กต์ของคุณเติบโตขึ้นและมีผู้ใช้มากขึ้น คุณสามารถขอเพิ่มโควต้าได้

3. หากถึงขีดจำกัดโควต้าต่อผู้ใช้ คุณจะทำสิ่งต่อไปนี้ได้

   • หากใช้บัญชีบริการ ให้จัดสรรภาระงานให้กับผู้ใช้หรือแบ่งภาระงานระหว่างบัญชีบริการหลายบัญชี

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

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

สุ่มรูปแบบการจราจร

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

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

ใช้ข้อความ Push

กรณีการใช้งานที่พบบ่อยคือการดำเนินการเมื่อมีการเปลี่ยนแปลงในปฏิทินของผู้ใช้ รูปแบบที่ไม่ควรทำในที่นี้คือการสำรวจปฏิทินที่สนใจซ้ำๆ ซึ่งจะใช้โควต้าทั้งหมดของคุณอย่างรวดเร็ว ตัวอย่างเช่น หากแอปพลิเคชันของคุณมีผู้ใช้ 5,000 คนและทำการสำรวจปฏิทินของผู้ใช้แต่ละคนนาทีละครั้ง แอปพลิเคชันนี้จะต้องมีโควต้าต่อนาทีอย่างน้อย 5,000 รายการ แม้ว่าจะยังไม่มีการดำเนินการใดๆ ก็ตาม

แอปพลิเคชันฝั่งเซิร์ฟเวอร์สามารถลงทะเบียนรับข้อความ Push ซึ่งช่วยให้เราแจ้งให้คุณทราบเมื่อมีสิ่งน่าสนใจเกิดขึ้นได้ ซึ่งต้องใช้เวลาในการตั้งค่ามากกว่า แต่ช่วยให้ใช้โควต้าได้อย่างมีประสิทธิภาพมากขึ้นอย่างมาก และมอบประสบการณ์ของผู้ใช้ที่ดียิ่งขึ้น ตรวจสอบว่าคุณระบุ eventType ที่ต้องการรับการแจ้งเตือน ดูข้อมูลเพิ่มเติมได้ที่ข้อความ Push

การจัดสรรที่เหมาะสมด้วยบัญชีบริการ

หากแอปพลิเคชันของคุณส่งคำขอโดยใช้การมอบสิทธิ์ทั่วทั้งโดเมน โดยค่าเริ่มต้น ระบบจะเรียกเก็บเงินจากบัญชีบริการตามโควต้า "ต่อนาทีต่อผู้ใช้ต่อโปรเจ็กต์" ไม่ใช่ผู้ใช้ที่คุณกำลังแอบอ้าง ซึ่งหมายความว่าบัญชีบริการมีแนวโน้มที่จะใช้โควต้าจนหมดและถูกจำกัดอัตราคำขอ แม้ว่าอาจทำงานในปฏิทินของผู้ใช้หลายคนก็ตาม

คุณหลีกเลี่ยงปัญหานี้ได้โดยใช้พารามิเตอร์ของ URL quotaUser (หรือส่วนหัว HTTP x-goog-quota-user) เพื่อระบุสตริงที่กำหนดเอง (สูงสุด 40 อักขระ) ซึ่งระบุผู้ใช้แต่ละรายโดยไม่ซ้ำกัน Calendar API จะใช้ค่านี้สำหรับการคำนวณโควต้าเท่านั้น

หากต้องการใช้ quotaUser เพื่อบังคับใช้ขีดจำกัดอัตราคำขอต่อผู้ใช้กับผู้ใช้ที่แตกต่างกัน คำขอของคุณต้องเป็นไปตามข้อกำหนดต่อไปนี้

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

• ละเว้นส่วนหัว X-Goog-User-Project: อย่าส่งส่วนหัว HTTP X-Goog-User-Project ในคำขอที่ใช้ quotaUser การระบุโปรเจ็กต์ของผู้ใช้จะลบล้างคีย์ API สำหรับการระบุแหล่งที่มาของโควต้า ดังนั้น Calendar API จะละเว้น quotaUser

ดูข้อมูลเพิ่มเติมได้ที่การจำกัดคำขอต่อผู้ใช้

ทดสอบการจัดการขีดจำกัดโควต้า

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

หากต้องการทดสอบโดยไม่รบกวนการใช้งานแอปพลิเคชันจริง เราขอแนะนำให้ลงทะเบียนโปรเจ็กต์ทดสอบแยกต่างหากในคอนโซล Google Cloud แล้วกำหนดค่าหน้าจอขอความยินยอม OAuth ในลักษณะที่คล้ายกับโปรเจ็กต์เวอร์ชันที่ใช้งานจริง จากนั้นคุณสามารถตั้งค่าขีดจำกัดโควต้าต่ำเกินจริงสำหรับโปรเจ็กต์นี้และสังเกตลักษณะการทำงานของแอปพลิเคชันได้

โควต้าเซิร์ฟเวอร์ MCP ของปฏิทิน

เซิร์ฟเวอร์ MCP ของปฏิทินใช้เมตริกการจัดสรรต้นทุนการค้นหา ตารางต่อไปนี้แสดงรายละเอียดค่าใช้จ่ายในการค้นหาสำหรับเมธอดเซิร์ฟเวอร์ MCP ของปฏิทินแต่ละเมธอดตามส่วนต่างๆ

โควต้า MCP ของปฏิทิน

ระบบจะบังคับใช้โควต้า 2 ประเภท ได้แก่

• ต่อนาทีต่อโปรเจ็กต์: ค่าใช้จ่ายในการค้นหาสำหรับโปรเจ็กต์ Google Cloud เป็นเวลา 1 นาที

• ต่อนาทีต่อผู้ใช้ต่อโปรเจ็กต์: ค่าใช้จ่ายในการค้นหาต่อโปรเจ็กต์ Google Cloud เป็นเวลา 1 นาทีที่ผู้ใช้รายใดรายหนึ่งใช้ได้

ตารางต่อไปนี้แสดงรายละเอียดโควต้าเหล่านี้

ประเภทขีดจำกัดการใช้งาน	ค่าใช้จ่ายในการค้นหา
ต่อนาทีต่อโปรเจ็กต์	10,000
ต่อนาทีต่อผู้ใช้ต่อโปรเจ็กต์	600

โควต้าชุดเครื่องมือ MCP ของปฏิทิน

ตารางต่อไปนี้แสดงรายละเอียดค่าใช้จ่ายในการค้นหาสำหรับชุดเครื่องมือ calendarmcp.googleapis.com แต่ละชุด

ปลายทาง	เครื่องมือ	ค่าใช้จ่ายในการค้นหา
/mcp/v1	create_event	1
	delete_event	10
	get_event	1
	list_events	1
	respond_to_event	1
	search_events	1
	update_event	1
	suggest_time	1
	list_calendars	1

ดูข้อมูลเพิ่มเติมได้ที่เอกสารอ้างอิง API ของ MCP สำหรับปฏิทิน

หัวข้อที่เกี่ยวข้อง

• ส่งคำขอแบบกลุ่ม
• เคล็ดลับด้านประสิทธิภาพ
• หลีกเลี่ยงขีดจำกัดการใช้งานปฏิทิน