Google Tasks API และ Webhooks สำหรับผู้ใช้งานขั้นสูง

คุณต้องการให้มีการสร้างงานใน Google Tasks ทุกครั้งที่แบบฟอร์มถูกส่ง หรือส่งข้อความใน Slack เมื่อสมาชิกในทีมทำเสร็จจากรายการงานที่แชร์ หรือสคริปต์ที่รันทุกคืนเพื่อบันทึกงานที่เลยกำหนดลงในสเปรดชีต

Google มี Tasks API และใช้งานได้ แต่ไม่มีเว็บฮุค ดังนั้นการตรวจสอบว่า “เมื่องานเสร็จสิ้น” หมายถึงต้องโพลลิ่งรายการทุกครั้งตามเวลาที่กำหนด มันไม่รู้จักป้ายกำกับ ผู้รับมอบหมาย หรือบอร์ด เพราะ Google Tasks ไม่มีสิ่งเหล่านี้ และทุกสคริปต์ต้องเริ่มต้นด้วยโปรเจกต์ Google Cloud, หน้าตกลงยินยอม OAuth และกระบวนการรีเฟรชโทเคน

ตอนนี้ TasksBoard เปิดให้ใช้ REST API สาธารณะบนข้อมูล Google Tasks ของคุณ พร้อมคีย์ API ส่วนบุคคล เว็บฮุคที่ลงลายเซ็นด้วย HMAC และแอป Zapier คู่มือนี้จะครอบคลุมสิ่งที่มันเสนอ วิธีรับคีย์ เอนด์พอยต์ที่ใช้บ่อยที่สุด วิธีการทำงานของเว็บฮุคและโพลลิ่ง และกลุ่มเป้าหมาย API นี้เป็นส่วนหนึ่งของ แผนทีม

สิ่งที่ TasksBoard API เพิ่มให้กับ Google Tasks

API นี้อ่านและเขียนรายการและงาน Google Tasks เดียวกันที่คุณเห็นใน Gmail และแอป Google Tasks ทุกรายการและรหัสงานคือรหัสของ Google Tasks ดังนั้นสิ่งที่คุณสร้างจะยังคงเข้ากันได้กับ Google Tasks เองและกับเครื่องมืออื่นที่ใช้ API ของ Google

นอกจากนั้น มันยังเปิดเผยสิ่งที่ TasksBoard เพิ่มเข้ามา:

• ป้ายกำกับและผู้รับมอบหมาย เป็นฟิลด์ที่เหมาะสม Google Tasks เก็บเพียงชื่อ หมายเหตุ และวันครบกำหนด TasksBoard เก็บป้ายกำกับและผู้รับมอบหมายไว้ในหมายเหตุ (ป้ายกำกับในบรรทัดแรก ตามด้วย 👤 Assigned to <อีเมล>) API อ่านและเขียนพวกมันเป็น labels และ assignee ดังนั้นข้อความอิสระใน notes คือสิ่งที่ผู้คนเห็นบนบอร์ด
• บอร์ด: รายการที่แต่ละบอร์ด TasksBoard แสดง
• รายการที่แชร์: แฟล็ก shared ในแต่ละรายการ และเหตุการณ์เมื่อผู้ร่วมงานเปลี่ยนงานที่แชร์
• เว็บฮุค สำหรับ task.created, task.updated, task.completed และ task.deleted

URL ฐาน: https://api.tasksboard.com/v1 การตอบกลับเป็น JSON ภายใต้คีย์ data ข้อผิดพลาดมาในรูปแบบ { "error": { "code", "message", "details" } } โดยที่ code มีความเสถียร และ details ระบุฟิลด์ที่ไม่ถูกต้องในกรณี 422

สร้างคีย์ API

คีย์เป็นส่วนบุคคล คีย์จะทำงานเป็นผู้ใช้ที่สร้างมันขึ้นมา: สิ่งที่บุคคลนั้นสามารถทำได้ใน Google Tasks คีย์ก็สามารถทำได้

1. ใน TasksBoard คลิกที่รูปโปรไฟล์ของคุณและเปิด ทีม จากนั้นแท็บ API (หรือไปที่ /team?tab=api โดยตรง)
2. คลิกเพื่อสร้างคีย์ เลือกว่าจะอนุญาตให้ เขียน หรือไม่ คีย์ที่ไม่มีขอบเขตการเขียนจะได้รับ 403 forbidden ทุกครั้งที่พยายามเขียน
3. คัดลอกคีย์ มันเริ่มต้นด้วย tb_live_ และจะแสดงเพียงครั้งเดียว
4. ส่งมันเป็น bearer token ในทุกคำขอ:

curl https://api.tasksboard.com/v1/lists \
  -H "Authorization: Bearer tb_live_…"

แท็บเดียวกันนี้จะแสดงรายการคีย์ของคุณพร้อมขอบเขต อนุญาตให้ยกเลิก และแสดงเว็บฮุคของคุณ ยกเลิกคีย์ทันทีที่อาจมีการรั่วไหล คีย์ใหม่ใช้เวลาเพียงไม่กี่วินาที

เอนด์พอยต์หลัก

ทัวร์สั้นๆ ของทรัพยากร เอกสารอ้างอิงเต็มที่สร้างจากคำจำกัดความ OpenAPI อยู่ในศูนย์ช่วยเหลือ: เอกสารอ้างอิง TasksBoard API

บัญชี

• GET /me: บัญชีที่คีย์เป็นของ แผนการใช้งาน และขอบเขตของคีย์

รายการ

• GET /lists: รายการ Google Tasks ของคุณ พร้อม shared และ boardId
• POST /lists: สร้างรายการ (title)
• GET /lists/{listId}: หนึ่งรายการ

งาน

• GET /lists/{listId}/tasks: งานที่เปิดอยู่โดยค่าเริ่มต้น status=completed หรือ all, updatedAfter, dueBefore, dueAfter, includeDeleted
• POST /lists/{listId}/tasks: สร้างงานด้วย title, notes, due, labels, assignee, parent (ทำให้เป็นงานย่อย), previous (แทรกหลังจากพี่น้อง)
• GET /tasks/{taskId}?listId=: หนึ่งงาน Google ระบุงานด้วยรายการและรหัส ดังนั้นต้องมี listId
• PATCH /tasks/{taskId}: อัปเดตบางส่วน ส่ง null เพื่อล้าง notes, due, labels หรือ assignee; status: "open" เปิดงานที่เสร็จสิ้นแล้วใหม่
• POST /tasks/{taskId}/complete: ทำเครื่องหมายว่าเสร็จสิ้น
• DELETE /tasks/{taskId}?listId=: ลบงาน

บอร์ด

• GET /boards: บอร์ดของคุณและรหัสรายการที่แต่ละบอร์ดแสดง บอร์ดหลักจะอยู่ลำดับแรกเสมอ

เว็บฮุค

• GET, POST /webhooks, และ GET, PATCH, DELETE /webhooks/{webhookId}

การสร้างงานด้วยป้ายกำกับและผู้รับมอบหมายมีลักษณะดังนี้:

curl -X POST https://api.tasksboard.com/v1/lists/LIST_ID/tasks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "ส่งรายงาน Q3", "due": "2026-10-24",
       "labels": ["❗️สำคัญ"], "assignee": "bob@example.com"}'

ผู้รับมอบหมายต้องเป็นผู้ร่วมงานของรายการ (หรือคุณ) เอนด์พอยต์รายการจะคืนค่า meta.nextCursor เมื่อมีข้อมูลเพิ่ม ส่งมันกลับเป็น cursor พร้อมตัวกรองเดียวกัน

เว็บฮุค: รับการแจ้งเตือนเมื่องานเปลี่ยนแปลง

การโพลลิ่งเป็นจุดอ่อนของ Google Tasks API เว็บฮุคแทนที่มัน: TasksBoard จะเรียก URL ของคุณเมื่อมีการสร้าง อัปเดต เสร็จสิ้น หรือลบงาน

1. ลงทะเบียนเว็บฮุคด้วยเหตุการณ์ที่คุณต้องการ:

curl -X POST https://api.tasksboard.com/v1/webhooks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tasksboard",
       "events": ["task.created", "task.completed"]}'

2. บันทึก secret จากคำตอบ มันจะถูกคืนเพียงครั้งเดียวในคำตอบนั้นเท่านั้น คุณยังสามารถระบุของคุณเองได้
3. ตอบกลับทุกการส่งด้วยรหัสสถานะ 2xx ภายใน 10 วินาที

แต่ละการส่งมีสามส่วนหัว: X-TasksBoard-Event (ชื่อเหตุการณ์), X-TasksBoard-Delivery (รหัสการส่ง) และ X-TasksBoard-Signature เนื้อหามีเหตุการณ์, ตราประทับเวลา createdAt, หมายเลขความพยายาม, งานเต็มภายใต้ data.task และ source: api สำหรับการเรียก REST, sync สำหรับการเปลี่ยนแปลงที่มาจากรายการที่แชร์, poll สำหรับการโพลลิ่ง 15 นาทีที่อธิบายด้านล่าง

ตรวจสอบลายเซ็น

ส่วนหัวลายเซ็นมีรูปแบบ t=<วินาทียูนิกซ์>,v1=<hex> โดยที่ v1 คือ HMAC-SHA256 ของ "<t>.<เนื้อหาดิบ>" ด้วย secret ของคุณ คำนวณ HMAC จากเนื้อหาคำขอที่ได้รับอย่างตรงไปตรงมา ก่อนการแยกวิเคราะห์ JSON ใดๆ และปฏิเสธตราประทับเวลาที่เก่าเกินไป:

const crypto = require("crypto")

function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"))
}

การลองใหม่และการปิดการใช้งาน

การส่งที่ล้มเหลวจะลองใหม่สูงสุด 3 ครั้งด้วยการถอยหลัง หลังจากล้มเหลวติดต่อกัน 20 ครั้ง เว็บฮุคจะถูกปิด (active: false) จนกว่าคุณจะเปิดใช้งานอีกครั้งด้วย PATCH /webhooks/{id} และ "active": true แท็บ API ในหน้าทีมจะแสดงแต่ละเว็บฮุคด้วย URL เหตุการณ์ และป้าย Active หรือ Disabled ดังนั้นจุดปลายทางที่ตายแล้วจะสังเกตเห็นได้ง่าย

การโพลลิ่งสำหรับรายการที่ไม่ได้แชร์

เหตุการณ์เว็บฮุคมาจากที่ไหน? จากสามสถานที่: การเขียนของ API เอง การเปลี่ยนแปลงที่แพร่กระจายในรายการที่แชร์ และหากคุณเปิดใช้งาน การโพลลิ่งรายการอื่นของคุณ

ประการสุดท้ายนั้นสำคัญ การเปลี่ยนแปลงที่ทำใน Gmail หรือแอป Google Tasks ในรายการที่ ไม่ได้แชร์ จะไม่ถูกสังเกตโดย TasksBoard เว้นแต่จะมีบางสิ่งดูที่รายการ ในแท็บ API เปิด โพลลิ่งรายการของฉันทุก 15 นาที: TasksBoard จะตรวจสอบรายการเหล่านั้นตามกำหนดเวลาและส่งเหตุการณ์ด้วย source: "poll" หากไม่มีสิ่งนี้ มีเพียงรายการที่แชร์และการเขียน API เท่านั้นที่สร้างเหตุการณ์

หากคุณต้องการเพียงตอบสนองต่อการเปลี่ยนแปลงในรายการที่ทีมของคุณแชร์ ให้ปิดการโพลลิ่ง

Zapier

ไม่ใช่ทุกคนที่ต้องการเขียนโค้ด แอป TasksBoard สำหรับ Zapier รับรองความถูกต้องด้วยคีย์ API ส่วนบุคคลเดียวกันและเสนอ:

• ทริกเกอร์: งานใหม่ งานเสร็จสิ้น ทั้งสองโพลลิ่ง GET /lists/{listId}/tasks ด้วย updatedAfter ซึ่งเป็นรูปแบบเดียวกับที่คุณจะใช้ในสคริปต์ของคุณเอง
• การกระทำ: สร้างงาน เสร็จสิ้นงาน สร้างรายการ

การรวม Zapier กำลังเผยแพร่ เมื่อมันถูกระบุไว้ คุณสามารถค้นหา TasksBoard ใน Zapier วางคีย์ของคุณเมื่อถูกถามและเลือกรายการ จนกว่าจะถึงเวลานั้น REST API และเว็บฮุคครอบคลุมพื้นที่เดียวกัน และทริกเกอร์และการกระทำข้างต้นบอกคุณถึงสิ่งที่คาดหวัง สำหรับตัวเลือกอัตโนมัติที่กว้างขึ้น ดูคู่มือของเราเกี่ยวกับ การรวม Google Tasks

ลองใช้ TasksBoard ทีม

รายการที่แชร์ บทบาท บันทึกกิจกรรมและ REST API พร้อมเว็บฮุค บน Google Tasks ที่คุณใช้อยู่แล้ว หนึ่งบิลสำหรับทั้งทีม

ดูแผน →

กลุ่มเป้าหมาย

API นี้เป็นคุณลักษณะของแผนทีม และเหมาะกับ:

• ทีมที่มีรายการที่แชร์เป็นแหล่งความจริง เว็บฮุคบน task.completed ด้วย source: "sync" จะทำงานเมื่อผู้ร่วมงานใดๆ เสร็จสิ้นงาน ไม่ว่าพวกเขาใช้แอปใด นั่นคือจุดเชื่อมสำหรับข้อความ Slack แถวใน Sheets หรือการอัปเดตตั๋ว
• ผู้ปฏิบัติงานที่เชื่อมต่อเครื่องมือเข้าด้วยกัน แบบฟอร์ม, CRM และระบบช่วยเหลือสามารถสร้างงานด้วยป้ายกำกับและผู้รับมอบหมายในการเรียกครั้งเดียว และงานจะปรากฏบนบอร์ดของบุคคลที่เหมาะสมและในแอป Google Tasks ของพวกเขา
• นักพัฒนาที่ลองใช้ Google Tasks API และหยุดที่การโพลลิ่ง การตั้งค่า OAuth หรือการขาดผู้รับมอบหมาย หนึ่งคีย์ หนึ่งส่วนหัว รหัสของ Google เอง

มันไม่ใช่สำหรับแทนที่ API ของ Google ทั้งหมด หากคุณต้องการเพียงงานของคุณเองในสคริปต์ส่วนบุคคลและมีไคลเอนต์ OAuth อยู่แล้ว API ของ Google ฟรีและทำงานได้ คู่มือ การส่งออก Google Tasks ของเราครอบคลุมกรณีใช้ครั้งเดียว

คำถามที่พบบ่อย

สรุป

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

สร้างคีย์ในแท็บ API ของหน้าทีม ทำการเรียก GET /lists ครั้งเดียว และส่วนที่เหลือตามมาจาก เอกสารอ้างอิง API