واجهة Google Tasks API وWebhooks وZapier للمحترفين

تريد إنشاء مهمة في Google Tasks في كل مرة يتم فيها إرسال نموذج. أو رسالة Slack عندما يكمل زميل في الفريق مهمة في قائمة الإطلاق المشتركة. أو برنامج ليلي يحفظ المهام المتأخرة في جدول بيانات.

يوجد واجهة برمجة تطبيقات (API) لـ Google Tasks وهي تعمل. لكنها لا تحتوي على webhooks، لذا فإن “عند اكتمال المهمة” يعني الاستطلاع الدوري لكل قائمة على مؤقت زمني. لا تعرف شيئًا عن التصنيفات أو المكلفين أو اللوحات، لأن Google Tasks لا يحتوي عليها. وكل برنامج يبدأ بمشروع Google Cloud، وشاشة موافقة OAuth، وإجراء تحديث للرمز.

تعرض TasksBoard الآن واجهة برمجة تطبيقات REST عامة فوق بيانات Google Tasks الخاصة بك، مع مفاتيح API شخصية، وwebhooks موقعة بـ HMAC، وتطبيق Zapier. يغطي هذا الدليل ما تقدمه، وكيفية الحصول على مفتاح، والنقاط الأساسية التي ستستخدمها، وكيف تعمل webhooks والاستطلاع، ولمن هذا مخصص. تعد واجهة برمجة التطبيقات جزءًا من خطة الفريق.

ما تضيفه واجهة TasksBoard API إلى Google Tasks

تقرأ واجهة برمجة التطبيقات وتكتب نفس قوائم ومهام Google Tasks التي تراها في Gmail وتطبيق Google Tasks. كل معرف قائمة ومهمة هو معرف Google Tasks، لذا فإن أي شيء تقوم ببنائه يظل متوافقًا مع Google Tasks نفسه ومع الأدوات الأخرى التي تستخدم واجهة برمجة التطبيقات من Google.

علاوة على ذلك، تكشف عما تضيفه TasksBoard:

• التصنيفات والمكلفون كحقول مناسبة. يحتفظ Google Tasks فقط بعنوان وملاحظات وتاريخ استحقاق؛ تحتفظ TasksBoard بالتصنيفات والمكلف داخل الملاحظات (التصنيفات في السطر الأول، ثم 👤 مكلف إلى <بريد إلكتروني>). تقرأ واجهة برمجة التطبيقات وتكتبها كـ labels و assignee، لذا فإن النص الحر في notes هو ما يراه الأشخاص على اللوحة.
• اللوحات: القوائم التي تظهرها كل لوحة TasksBoard.
• القوائم المشتركة: علامة shared على كل قائمة، وأحداث عندما يقوم متعاون بتغيير مهمة مشتركة.
• Webhooks لـ 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. أرسله كرمز حامل في كل طلب:

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

تعرض علامة التبويب نفسها مفاتيحك مع نطاقها، وتتيح لك إلغاء واحد، وتظهر webhooks الخاصة بك. قم بإلغاء المفتاح في اللحظة التي قد يكون قد تسرب فيها؛ يستغرق المفتاح الجديد بضع ثوانٍ.

النقاط الأساسية

جولة سريعة على الموارد. المرجع الكامل، المولد من تعريف 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: لوحاتك ومعرفات القوائم التي تظهرها كل واحدة. تكون اللوحة الرئيسية دائمًا في المقدمة.

Webhooks

• 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": "إرسال تقرير الربع الثالث", "due": "2026-10-24",
       "labels": ["❗️مهم"], "assignee": "bob@example.com"}'

يجب أن يكون المكلف متعاونًا في القائمة (أو أنت). تعيد نقاط نهاية القائمة meta.nextCursor عندما يكون هناك المزيد؛ قم بإعادته كـ cursor مع نفس الفلاتر.

Webhooks: احصل على إشعار عند تغيير المهمة

الاستطلاع هو نقطة الضعف في واجهة برمجة تطبيقات Google Tasks. يحل webhook محله: يتصل TasksBoard بعنوان URL الخاص بك عند إنشاء مهمة أو تحديثها أو إكمالها أو حذفها.

1. سجل webhook بالأحداث التي تريدها:

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>.<raw body>" مع سرك. احسب 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 فشلًا متتاليًا، يتم إيقاف webhook (active: false) حتى تعيد تمكينه بـ PATCH /webhooks/{id} و "active": true. تظهر علامة تبويب API في صفحة الفريق كل webhook مع عنوان URL الخاص به، والأحداث، وشارة نشط أو معطل، لذا من السهل اكتشاف نقطة نهاية ميتة.

الاستطلاع للقوائم غير المشتركة

من أين تأتي أحداث webhook؟ من ثلاثة أماكن: الكتابات الخاصة بواجهة برمجة التطبيقات، والتغييرات المنقولة على القوائم المشتركة، وإذا قمت بتشغيله، استطلاع لقوائمك الأخرى.

هذا الأخير مهم. التغيير الذي تم في Gmail أو تطبيق Google Tasks على قائمة غير مشتركة لا يلاحظه TasksBoard إلا إذا نظر شيء ما إلى القائمة. في علامة تبويب API، قم بتشغيل استطلاع قوائمي كل 15 دقيقة: يقوم TasksBoard بعد ذلك بفحص تلك القوائم على هذا الجدول الزمني ويصدر أحداثًا بـ source: "poll". بدونه، تنتج القوائم المشتركة وكتابات API فقط الأحداث.

إذا كنت تحتاج فقط إلى الرد على التغييرات في القوائم التي يشاركها فريقك، اترك الاستطلاع معطلاً.

Zapier

لا يريد الجميع كتابة التعليمات البرمجية. يستخدم تطبيق TasksBoard لـ Zapier نفس مفتاح API الشخصي ويقدم:

• المحفزات: مهمة جديدة، مهمة مكتملة. كلاهما يستطلع GET /lists/{listId}/tasks مع updatedAfter، نفس الأسلوب الذي ستستخدمه في البرنامج النصي الخاص بك.
• الإجراءات: إنشاء مهمة، إكمال مهمة، إنشاء قائمة.

يتم نشر تكامل Zapier. بمجرد إدراجه، يمكنك البحث عن TasksBoard في Zapier، ولصق مفتاحك عند الطلب واختيار قائمة. حتى ذلك الحين، تغطي واجهة برمجة تطبيقات REST و webhooks نفس الأرضية، وتخبرك المحفزات والإجراءات أعلاه بما يمكن توقعه. للحصول على نظرة أوسع على خيارات الأتمتة، راجع دليلنا لـ تكاملات Google Tasks.

جرب TasksBoard Team

قوائم مشتركة، أدوار، سجل نشاط وواجهة برمجة تطبيقات REST مع webhooks، فوق Google Tasks الذي تستخدمه بالفعل. فاتورة واحدة للفريق بأكمله.

عرض الخطط →

لمن هذا مخصص

واجهة برمجة التطبيقات هي ميزة خطة الفريق، والملاءمة محددة:

• الفرق التي لديها قائمة مشتركة كمصدر للحقيقة. ينطلق webhook على task.completed مع source: "sync" عندما يكمل أي متعاون مهمة، بغض النظر عن التطبيق الذي استخدمه. هذا هو الخطاف لرسالة Slack، صف في Sheets أو تحديث تذكرة.
• أشخاص العمليات الذين يربطون الأدوات معًا. يمكن للنماذج وأنظمة CRM ومكاتب الدعم إنشاء مهام بتصنيف ومكلف في مكالمة واحدة، وتظهر المهمة على لوحة الشخص المناسب وفي تطبيق Google Tasks الخاص به.
• المطورون الذين جربوا واجهة برمجة تطبيقات Google Tasks وتوقفوا عند الاستطلاع، إعداد OAuth أو عدم وجود مكلفين. مفتاح واحد، رأس واحد، معرفات Google الخاصة.

ليس لاستبدال واجهة برمجة تطبيقات Google بالجملة. إذا كنت تحتاج فقط إلى مهامك في برنامج نصي شخصي ولديك بالفعل عميل OAuth، فإن واجهة برمجة تطبيقات Google مجانية وتقوم بالمهمة. يغطي دليلنا دليل تصدير Google Tasks الحالات لمرة واحدة.

الأسئلة الشائعة

الخلاصة

يحتوي Google Tasks على واجهة برمجة تطبيقات، لكن بدون webhooks، أو تصنيفات أو مكلفين، وتكلفة إعداد توقف معظم الأتمتات الصغيرة قبل أن تبدأ. تحتفظ واجهة TasksBoard API بمعرفات Google وتضيف القطع المفقودة: مفتاح شخصي تقوم بإنشائه في دقيقة، نقاط نهاية للقوائم والمهام واللوحات، webhooks يمكنك التحقق منها، استطلاع اختياري للقوائم غير المشتركة، وتطبيق Zapier في الطريق.

قم بإنشاء مفتاح في علامة تبويب API في صفحة الفريق، وقم بإجراء مكالمة GET /lists واحدة، والباقي يتبع من مرجع API.