في 4 مايو 2026، أعلنت Google رسميًا عبر مدونتها التقنية عن توفر "خطافات الويب المعتمدة على الأحداث" (Event-driven webhooks) في Gemini API. وبعد يومين، في 6 مايو في تمام الساعة 10 صباحًا (بتوقيت بكين)، وصلت هذه الرسالة من Google AI Studio إلى صناديق بريد المطورين حول العالم، لتعلن عن الإتاحة الكاملة لخطافات الويب الخاصة بـ Gemini API لجميع المستخدمين.
بالنسبة للعديد من الفرق التي تعمل على "البحث العميق" (Deep Research)، أو توليد الفيديوهات الطويلة، أو استدلال الدفعات (Batch inference) واسع النطاق، يمثل هذا التحديث "بنية تحتية" بكل ما تحمله الكلمة من معنى. فهو ليس مجرد نموذج جديد أو معاملات إضافية، بل هو إعادة صياغة جذرية لكيفية "التفاعل مع مهام الذكاء الاصطناعي طويلة الأمد".
تستعرض هذه المقالة، استنادًا إلى مدونة Google الرسمية وGemini Cookbook، أنواع الأحداث في خطافات الويب لـ Gemini API، وطريقتي الإعداد، وآلية التحقق من التوقيع، مع توفير كود برمجي للبدء، بالإضافة إلى مناقشة ما يعنيه هذا للمطورين في المنطقة العربية.
ما هي خطافات الويب لـ Gemini API: فهم الآلية المعتمدة على الأحداث في جملة واحدة
تعد خطافات الويب (webhooks) في Gemini API في جوهرها آلية دفع للأحداث تعتمد على بروتوكول HTTP POST. فعندما تكتمل مهام الدفعات (Batch)، أو مهام توليد الفيديو، أو المحادثات غير المتزامنة، تقوم Gemini API بإرسال إشعار JSON موقع رقميًا إلى عنوان الخادم الذي قمت بتسجيله مسبقًا، بدلاً من إجبارك على إرسال طلبات GET متكررة للاستعلام عن حالة المهمة.
هذا التصميم القائم على "الاستدعاء العكسي" ليس جديدًا في تطوير البرمجيات التقليدية، لكنه يحمل أهمية كبيرة في سيناريوهات استدلال الذكاء الاصطناعي. فخدمات Gemini الحالية مثل البحث العميق (Deep Research)، وتوليد الفيديو الطويل Veo، وBatch API، تستغرق مهامها وقتًا يتراوح بين دقائق وساعات. إذا استمر الاعتماد على الاستعلام الدوري (Polling)، فسيضطر العميل إلى الحفاظ على اتصالات طويلة الأمد، واستخدام مؤقتات، ومنطق لاستعادة الأخطاء، مما يرفع تكاليف التشغيل ويهدر حصص الـ API.
🎯 فهم سريع: خطافات الويب لـ Gemini API تعني تحويل عملية "هل انتهيت؟" من سؤال متكرر من جانب العميل، إلى إشعار استباقي من جانب الخادم. يحتاج المطور فقط إلى إعداد نقطة نهاية (endpoint) للاستجابة، ثم انتظار الإشعارات. يمكن للفرق التي تستخدم خدمات وسيطة مثل APIYI (apiyi.com) للوصول إلى Gemini الاستفادة من هذه الإشعارات لتقليل طلبات الاستعلام عبر الشبكات الدولية، مما يقلل بشكل ملحوظ من زمن الاستجابة واستهلاك النطاق الترددي.
تجدر الإشارة إلى أن خطافات الويب في Gemini API ترسل "حمولة خفيفة" (thin payload)؛ فهي تخبرك بمعرف المهمة، وحالتها، ومؤشر الوصول إلى ملف النتائج (مثل output_file_uri)، دون إدراج فيديوهات بحجم عشرات الميجابايت أو آلاف الأسطر من مخرجات الدفعات مباشرة في جسم طلب POST. هذا تصميم متعمد يهدف إلى تقليل تكاليف البيانات عند إعادة المحاولة، ويجعل التحكم في الصلاحيات أكثر وضوحًا.
لماذا أنهت خطافات الويب (Webhooks) الخاصة بـ Gemini API "عصر الاستطلاع"؟
لفهم قيمة خطافات الويب في Gemini API، يجب أولاً إدراك تكلفة الاستطلاع (Polling). قبل ظهور خطافات الويب، كانت دورة حياة مهمة الدفعات (Batch) المعتادة تبدو كالتالي: إرسال المهمة ← الحصول على معرف العملية (operation ID) ← استخدام setInterval لإجراء طلب GET كل 30 ثانية ← عدم القدرة على إنهاء العمل حتى تتغير الحالة إلى SUCCEEDED. هذه العملية قد تكون مقبولة لمهمة واحدة، لكنها تتدهور بسرعة في بيئة الإنتاج.
يقارن الجدول أدناه بين نمط الاستطلاع ونمط خطافات الويب المعتمد على الأحداث عبر أبعاد متعددة، وهي نقاط الفائدة التي ركزت عليها Google في مدونتها الرسمية:
| بُعد المقارنة | نمط الاستطلاع التقليدي | خطاف الويب المعتمد على الأحداث في Gemini API |
|---|---|---|
| تأخير الإشعار | يعتمد على الفاصل الزمني للاستطلاع (عادة 10-60 ثانية) | مستوى المللي ثانية (يتم الدفع فور انتهاء المهمة) |
| استهلاك حصة API | كل استطلاع يُحسب ضمن حصة القراءة | الدفع يتم من جانب Google، ولا يستهلك حصة العميل |
| تعقيد العميل | يتطلب مؤقتات، آلات حالة، وإعادة محاولة عند الخطأ | يتطلب فقط نقطة نهاية HTTP POST + التحقق من التوقيع |
| التزامن واسع النطاق | عاصفة استطلاع واضحة عند وجود آلاف المهام | تصل عمليات الدفع بشكل مستقل، سهلة التوسع الأفقي |
| استعادة الفشل | يجب على العميل تنفيذها بنفسه | إعادة محاولة تلقائية من جانب الخادم مع تراجع أسي، تصل لـ 24 ساعة |
| السيناريوهات المناسبة | المهام القصيرة، التزامن المنخفض | المهام الطويلة، التزامن العالي، خطوط أنابيب الوكلاء (Agentic) |
من هذا الجدول، يتضح أن خطافات الويب في Gemini API لا تقتصر على "توفير بعض أكواد الاستطلاع" فحسب، بل إنها تنقل مسؤولية "تنسيق المهام" من العميل إلى جانب الخادم بشكل كبير. بالنسبة للفرق التي تدير سير عمل الوكلاء (Agentic workflow)، فإن الجمع بين خطافات الويب وخدمات مثل Cloud Run أو Cloud Functions أو أي خدمات Serverless محلية يتيح تحقيق نظام غير متزامن بالكامل وبدون اتصالات طويلة.
💡 الانتقال من الاستطلاع: إذا كان كودك الحالي يعتمد على
GET /operations، فإن الانتقال إلى نمط خطاف الويب يتطلب فقط استبدال "حلقة الاستطلاع" بـ "مسار رد الاتصال (Callback route)"، مع بقاء منطق العمل دون تغيير تقريباً. عند الوصول إلى Gemini API عبر خدمة وكيل API مثل APIYI (apiyi.com)، يمكن لنقطة نهاية خطاف الويب الاتصال مباشرة بشبكتك الداخلية، مما يحافظ على مزايا النظام المعتمد على الأحداث ويتجنب عدم استقرار الاتصالات العابرة للحدود.
طريقتان لتهيئة خطافات الويب في Gemini API: ثابتة (Static) مقابل ديناميكية (Dynamic)
يدعم Gemini API طريقتين للتسجيل، موجهتين لاحتياجات "الإشعارات الشاملة" و"التوجيه حسب المهمة" على التوالي. فهم الفرق بينهما يحدد بشكل مباشر استراتيجيتك لإدارة المفاتيح والتحقق من التوقيع.
خطاف الويب الثابت (Static Webhook): اشتراك في الأحداث على مستوى المشروع
يتم تسجيل خطاف الويب الثابت مرة واحدة عبر API WebhookService، ويسري على جميع الأحداث المطابقة ضمن ذلك المشروع. وهو مناسب للسيناريوهات التي تتطلب "بث الإشعارات عند اكتمال أي مهمة"، مثل إعادة توجيه جميع أحداث batch.succeeded إلى Slack الخاص بالفريق، أو مزامنة جميع أحداث video.generated إلى نظام إدارة المحتوى (CMS) الخاص بك أو وحدة تخزين الكائنات.
فيما يخص آلية التوقيع، يستخدم خطاف الويب الثابت مفتاح HMAC متماثل. تقوم Google بإرجاع مفتاح التوقيع (signing secret) مرة واحدة فقط عند الإنشاء، ويجب حفظه فوراً في خدمة إدارة المفاتيح، وإلا ستضطر لحذفه وإعادة إنشائه.
خطاف الويب الديناميكي (Dynamic Webhook): توجيه دقيق على مستوى الطلب
يعد خطاف الويب الديناميكي وسيلة "أكثر دقة": حيث تحدد عنوان URL مؤقتاً في حقل webhook_config في كل مرة ترسل فيها مهمة، وستقوم Google بدفع أحداث تلك المهمة المحددة إلى ذلك العنوان. وهو مناسب بشكل خاص لسيناريوهات البرمجيات كخدمة (SaaS) متعددة المستأجرين، حيث يتم دفع مهام العملاء المختلفين إلى نقاط نهاية رد اتصال مختلفة، مما يوفر عزلاً واضحاً للأعمال.
يسمح خطاف الويب الديناميكي أيضاً بتضمين حقل user_metadata في التهيئة (أي أزواج مفتاح-قيمة، مثل {"job_group": "nightly-eval"})، وستقوم Google بإعادة إرسالها كما هي عند الدفع. هذا تصميم عملي جداً يغنيك عن صيانة جدول إضافي لربط "المهمة بسياق العمل".
فيما يخص آلية التوقيع، يستخدم خطاف الويب الديناميكي مفتاحاً عاماً غير متماثل (JWKS / RS256)، وعنوان المفتاح العام هو generativelanguage.googleapis.com/.well-known/jwks.json. عند التحقق، تحتاج خدمتك فقط إلى جلب المفتاح العام، دون الحاجة إلى الاحتفاظ بمفتاح متماثل.
| البُعد | خطاف الويب الثابت | خطاف الويب الديناميكي |
|---|---|---|
| طريقة التسجيل | تسجيل لمرة واحدة عبر API WebhookService |
تحديد مؤقت في كل طلب مهمة |
| نطاق التأثير | المشروع بأكمله | مهمة واحدة فقط |
| خوارزمية التوقيع | مفتاح HMAC متماثل | مفتاح عام JWKS / RS256 |
| إدارة المفاتيح | يُرجع مرة واحدة عند الإنشاء، يجب حفظه | لا حاجة لإدارة مفتاح متماثل، يُجلب من نقطة النهاية |
user_metadata |
غير مدعوم | يدعم تمرير أي أزواج مفتاح-قيمة |
| السيناريوهات النموذجية | إشعارات شاملة، تكامل Slack، أرشفة موحدة | توجيه متعدد المستأجرين، توزيع النتائج حسب المهمة |
| الجمهور الموصى به | الفرق الداخلية الموحدة | منصات SaaS، الخدمات المفتوحة للخارج |
🎯 نصيحة للاختيار: للمعالجة الموحدة داخل فريق واحد، يفضل استخدام خطاف الويب الثابت؛ أما إذا كنت تقدم خدمات للعملاء وتحتاج إلى توجيه حسب المستأجر، فاستخدم خطاف الويب الديناميكي. إذا كنت تستخدم خدمة وكيل API مثل APIYI (apiyi.com) للوصول إلى Gemini API، يمكنك استخدام كلا النمطين بشكل أصلي، حيث تتطابق ترويسات التوقيع وحمولة الأحداث (payload) تماماً مع المواصفات الرسمية، مما يجعل الانتقال سهلاً وبدون عوائق إضافية.
إليك دليل عملي حول كيفية البدء باستخدام خطافات الويب (Webhooks) في Gemini API، مع كود مبسط يتيح لك إعداد النظام في أقل من 10 دقائق.
إنشاء خطاف ويب (Webhook) مدفوع بالأحداث لـ Gemini API باستخدام Python SDK
from google import genai
import os
client = genai.Client()
# إنشاء خطاف ويب للاستماع لأحداث محددة
webhook = client.webhooks.create(
subscribed_events=["batch.succeeded", "video.generated"],
name="prod_global_notify",
uri="https://your-server.example.com/gemini/webhook",
)
# مفتاح التوقيع (signing_secret) يُعرض مرة واحدة فقط، لذا احرص على حفظه فوراً
os.environ["WEBHOOK_SIGNING_SECRET"] = webhook.new_signing_secret
تقوم هذه الشيفرة بمهمتين: الأولى هي تسجيل نقطة نهاية (Endpoint) عالمية تراقب اكتمال الدفعات (Batch) وتوليد الفيديو، والثانية هي تخزين مفتاح التوقيع في متغيرات البيئة. في بيئات الإنتاج، يُنصح بشدة بتخزين هذا المفتاح في خدمات إدارة الأسرار (Secret Manager) أو Vault بدلاً من وضعه في الكود أو سجلات النظام.
استقبال التحقق من التوقيع باستخدام Node.js + Express
import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
const wh = new Webhook(process.env.WEBHOOK_SIGNING_SECRET);
app.post("/gemini/webhook", express.raw({ type: "*/*" }), (req, res) => {
try {
// التحقق من صحة التوقيع
const event = wh.verify(req.body, req.headers);
console.log("الحدث:", event.type, "البيانات:", event.data);
res.status(200).send("ok");
} catch (e) {
res.status(400).send("توقيع غير صالح");
}
});
app.listen(8080);
نقاط هامة: يجب استخدام express.raw للحصول على البيانات الخام (Raw bytes) للتحقق من التوقيع، لأن تحليل JSON قد يفسد التوقيع. يجب أن يتم الرد برمز 2xx خلال ثوانٍ معدودة، وأي عمليات معقدة (مثل الكتابة في قاعدة البيانات) يجب أن تتم بشكل غير متزامن عبر طابور مهام. كما يُنصح برفض الطلبات التي يتجاوز طابعها الزمني (Timestamp) 5 دقائق كإجراء أمني ضد هجمات إعادة التشغيل (Replay attacks).
🚀 نصيحة عملية: إذا كانت خدمتك مستضافة محلياً وتحتاج إلى أن يصل إليها Google مباشرة، يُفضل وضع نقطة النهاية خلف عقدة خارجية أو شبكة توزيع محتوى (CDN). أو يمكنك استخدام خدمة وكيل API مثل APIYI (apiyi.com) التي تدعم استدعاءات Gemini API ووكيل الاستجابات، حيث تستقبل التنبيهات أولاً ثم تعيد توجيهها لشبكتك الداخلية، مما يوفر عليك تعقيدات NAT و SSL.
نظرة عامة على أنواع الأحداث المدعومة في Gemini API
تغطي خطافات الويب في Gemini API حالياً ثلاث فئات رئيسية من المهام الطويلة. يوضح الجدول أدناه الأحداث المعتمدة:
| مجموعة الأحداث | اسم الحدث | توقيت التفعيل | الحقول الرئيسية في Payload |
|---|---|---|---|
| Batch API | batch.succeeded | نجاح مهمة المعالجة | id, output_file_uri |
| Batch API | batch.failed | فشل مهمة المعالجة | id, error |
| Batch API | batch.cancelled | إلغاء المستخدم للمهمة | id |
| Batch API | batch.expired | انتهاء صلاحية المهمة | id |
| Video Generation | video.generated | اكتمال توليد الفيديو | file_id, video_uri |
| Interactions API | interaction.requires_action | انتظار استجابة الأداة | id, required_action |
| Interactions API | interaction.completed | اكتمال الحوار متعدد الجولات | id, output |
| Interactions API | interaction.failed | فشل في أي مرحلة | id, error |
| Interactions API | interaction.cancelled | إلغاء المستخدم للمهمة | id |
تتبع كل حمولة (Payload) هيكلاً موحداً: { "type": "batch.succeeded", "data": { "id": "...", "output_file_uri": "gs://..." } }. هذا التنسيق مثالي لاستخدام "مُوجّه" (Router) لمعالجة الأحداث وتوجيهها لمسارات العمل المناسبة.
📌 نصيحة معمارية: عند التنفيذ، يُنصح باستخدام نقطة نهاية واحدة لخطاف الويب مع ناقل أحداث داخلي (مثل Pub/Sub أو Kafka أو Redis Stream) بدلاً من إنشاء نقطة نهاية لكل حدث. هذا يتماشى مع نمط "الاستجابة السريعة 2xx + المعالجة غير المتزامنة" الذي توصي به Google. عند استخدام APIYI (apiyi.com) لاستدعاء Gemini Batch API أو توليد الفيديو، ستكون أنواع الأحداث متطابقة تماماً مع التوثيق الرسمي، مما يتيح لك إعادة استخدام نفس كود التوجيه.
آليات الأمان وضمانات التسليم في Gemini API webhooks
تتبع آليات الأمان في Gemini API webhooks معيار Standard Webhooks بدقة، وهو معيار تشغيل بيني عبر المنصات تديره المجتمعات التقنية. وهذا يعني أنه إذا سبق لك التعامل مع webhooks لخدمات مثل Stripe أو Svix أو Resend، فستتمكن من إعادة استخدام الكود الخاص بك بسلاسة تامة.
ثلاثة رؤوس HTTP أساسية
| رأس الطلب | الوظيفة | طريقة الاستخدام الموصى بها |
|---|---|---|
| webhook-id | معرف فريد للحدث | استخدامه كمفتاح لضمان التكرار (Idempotency Key) لمنع المعالجة المكررة |
| webhook-timestamp | طابع زمني لإنشاء الحدث (بالثواني) | رفض الطلبات التي تجاوزت 5 دقائق للحماية من هجمات إعادة التشغيل (Replay attacks) |
| webhook-signature | توقيع HMAC أو JWKS | التحقق منه بضغطة زر باستخدام مكتبة standardwebhooks |
استراتيجية التسليم "مرة واحدة على الأقل" وإعادة المحاولة
تلتزم Google بضمان التسليم "مرة واحدة على الأقل": ستتلقى نقطة النهاية (Endpoint) الخاصة بك كل حدث مرة واحدة على الأقل، وقد تتلقاه عدة مرات. لذا، يجب أن تكون أي عمليات كتابة في الأنظمة التابعة مصممة لتكون قابلة للتكرار (Idempotent)، وأفضل ممارسة هي استخدام webhook-id كمفتاح فريد عند الكتابة في قاعدة البيانات أو التخزين المؤقت.
إذا أعادت نقطة النهاية الخاصة بك رمز استجابة غير 2xx، فستقوم Google بإعادة المحاولة بشكل متكرر مع التراجع الأسي (Exponential backoff) خلال نافذة زمنية مدتها 24 ساعة. هذا يعني أن الأحداث لن تضيع حتى لو تعطلت خدمتك لفترة قصيرة، ولكنه يعني أيضاً أنه لا يمكنك الاعتماد على "المعالجة المتزامنة المحظورة" (Synchronous blocking) كاستجابة، حيث سيتم اعتبار الاستجابات البطيئة فشلاً.
تدوير مفاتيح التوقيع
يدعم مفتاح HMAC الخاص بـ Static Webhook نمط REVOKE_PREVIOUS_SECRETS_AFTER_H24، مما يسمح بالتحقق من المفتاحين القديم والجديد في وقت واحد خلال 24 ساعة. هذا أمر حيوي لعملية التبديل التدريجي للمفاتيح في بيئات الإنتاج: يمكنك إنشاء مفتاح جديد ونشره على جميع العقد، وبعد التأكد من قبولها جميعاً للمفتاح الجديد، يمكنك إلغاء صلاحية المفتاح القديم، مما يضمن إتمام عملية التدوير دون انقطاع.
🔐 نصيحة أمنية: يجب أن تمر جميع نقاط نهاية webhook عبر بروتوكول HTTPS، مع فرض التحقق من التوقيع، وتقييد حجم جسم الطلب، وتطبيق مهلة زمنية (Timeout) على الاستدعاءات البطيئة. إذا كنت تستخدم APIYI (apiyi.com) لاستدعاء Gemini API ونماذج أخرى في وقت واحد، فننصح بتجميع جميع نقاط نهاية webhook في خدمة "بوابة أحداث" موحدة، لمعالجة التحقق من التوقيع، وإزالة التكرار، والتوجيه مركزياً، ثم توزيع الأحداث على النماذج في الخلفية، مما يسهل الامتثال للتدقيق وإدارة المفاتيح.
سيناريوهات التطبيق الأساسية لـ Gemini API webhooks
لا تهدف Gemini API webhooks إلى خدمة جميع استدعاءات Gemini؛ فاستدعاءات generateContent المتزامنة التي تعود في أجزاء من الثانية لا تحتاج إليها. تكمن قيمتها الحقيقية في ثلاث فئات من المهام الطويلة، وهي السيناريوهات التي أشارت إليها المدونة الرسمية مباشرة:
الوكيل غير المتزامن لـ Deep Research
غالباً ما تستغرق مهام Deep Research وقتاً يتراوح بين دقائق إلى ساعات، وتتضمن جولات متعددة من البحث، واستدعاء الأدوات، وتلخيص النتائج. يتناسب حدث interaction.requires_action في webhook بشكل طبيعي مع سير العمل متعدد الخطوات هذا، حيث يمكنك تلقي رد اتصال عند كل عقدة إجراء (action node) والمضي قدماً في الخطوة التالية بشكل غير متزامن، بدلاً من استخدام عملية دائمة التشغيل لتتبع الجلسة بأكملها.
الاستدلال بالدفعات (Batch API)
تعد Batch API المدخل الذي أعدته Gemini لـ "آلاف أو حتى مئات الآلاف من الموجهات". بعد الإرسال، يتم إرجاع معرف المهمة (job ID) فوراً، وبمجرد اكتمالها، يتم إخطارك عبر حدث batch.succeeded بـ output_file_uri. في هذا النمط، تظهر ميزة التكلفة لـ webhook بوضوح، حيث إن الاستطلاع التقليدي لآلاف مهام الدفعات سيؤدي إلى استهلاك حصة الـ API بالكامل فوراً.
توليد الفيديوهات الطويلة (Veo)
تستغرق مهام توليد الفيديو الطويل مثل Veo عادةً عدة دقائق، ومن غير المنطقي من حيث تجربة المستخدم إبقاء الواجهة الأمامية في حالة انتظار مستمر. تتيح لك webhook إرجاع استجابة فورية للواجهة الأمامية مثل "جاري التوليد، سيتم إخطارك عند الانتهاء"، وعند اكتمال المهمة فعلياً، يتم إخطار المستخدم عبر نظام الدفع الخاص بك (مثل WebSocket أو APNs أو SSE).
🎯 التكيف مع السيناريوهات المحلية: تهتم فرق تطوير تطبيقات الذكاء الاصطناعي للفيديو محلياً بسؤالين رئيسيين: هل يمكن استدعاء Gemini Veo بشكل مستقر؟ وهل يمكن الحصول على إشعار الاكتمال في الوقت المناسب؟ من خلال قنوات وسيطة مثل APIYI (apiyi.com)، يمكن حل المشكلة الأولى، بينما تحل آلية الأحداث في Gemini API webhooks المشكلة الثانية، والجمع بينهما يشكل خط إنتاج متكامل للفيديوهات الطويلة يمكن تطبيقه محلياً.
توصية القرار: هل يجب عليك الانتقال فوراً إلى خطافات الويب (Webhooks) في Gemini API؟
على الرغم من أن خطافات الويب (Webhooks) تبدو متفوقة بشكل شامل على الاستطلاع (Polling)، إلا أن قرار الانتقال الفوري يعتمد على حجم عملك الحالي. ستساعدك مصفوفة القرار التالية على اتخاذ قرار سريع.
| وضعك الحالي | هل يُنصح بالانتقال إلى خطافات الويب لـ Gemini API؟ |
|---|---|
تستخدم generateContent للاستدعاء المتزامن بشكل أساسي |
لا حاجة (خطافات الويب لا تغطي هذا السيناريو) |
| تستخدم Batch أحياناً، بضع مهام يومياً | اختياري، لكن العائد ليس كبيراً |
| مهام Batch كثيرة، مئات المهام يومياً | يُنصح بشدة، للقضاء على ضغط الاستطلاع |
| تعمل على توليد الفيديو الطويل Veo | يُنصح بشدة، تحسن ملحوظ في التجربة |
| تعمل على Deep Research / سير عمل الوكلاء | يُنصح بشدة، ضروري للعمليات غير المتزامنة |
| منصة SaaS متعددة المستأجرين | يُنصح بشدة، تتوافق تماماً مع Dynamic Webhook |
💡 مسار الانتقال: لا تحتاج إلى نهج "الكل أو لا شيء"؛ يمكنك البدء باستخدام خطافات الويب في المشاريع الجديدة، مع الاحتفاظ بالاستطلاع في المشاريع القديمة، والاستبدال تدريجياً. طريقتان التنفيذ من جوجل تتعايشان معاً، وواجهة برمجة التطبيقات
GET /operationsللعميل لا تزال فعالة. إذا كنت تخطط لاستخدام APIYI (apiyi.com) لاستدعاء نماذج أخرى في نفس الوقت، فنحن ننصح باستغلال هذه الفرصة لتوحيد ناقل الأحداث لجميع المهام غير المتزامنة، مما يقلل من تكاليف صيانة أنظمة الإشعارات المتعددة.
الأسئلة الشائعة حول خطافات الويب (Webhooks) في Gemini API
هل خدمة Webhooks في Gemini API مدفوعة؟
وفقاً للمدونة الرسمية، لا توجد حالياً رسوم إضافية على إرسال إشعارات الـ Webhook بحد ذاتها؛ فأنت تدفع فقط مقابل مهام Gemini API التي ترسلها (مثل عدد الرموز المميزة "Tokens"، مدة توليد الفيديو، أو حجم معالجة الدفعات "Batch"). يتم إرسال إشعارات الـ Webhook من قبل Google مباشرة ولا تستهلك من حصة استدعاءات الـ API الخاصة بك.
هل يمكن للخوادم المحلية (داخل الصين) استقبال إشعارات Gemini API Webhooks مباشرة؟
نعم، بشرط أن يكون نقطة النهاية (Endpoint) الخاصة بك قابلة للوصول من شبكة Google. إذا كانت نقطة النهاية موجودة بالكامل داخل الشبكة المحلية ولا تملك منفذاً عاماً على الإنترنت، فلن تتمكن Google من إرسال الإشعارات. الممارسة الشائعة هي وضع نقطة النهاية على عقدة طرفية (Edge Node) أو بوابة وصول دولية، ثم إعادة توجيه الطلبات إلى الشبكة الداخلية، أو استخدام خدمة مثل APIYI (apiyi.com) التي تدعم وكيل الـ Webhook، حيث يتم استقبال الإشعارات في طبقة الوسيط ثم إعادة توجيهها إلى نظامك الداخلي.
هل ترسل Gemini API Webhooks إشعارات مكررة؟ وكيف يتم التعامل معها؟
نعم. توفر Google آلية تسليم "مرة واحدة على الأقل" (at-least-once)، مما يعني أن أي تذبذب لحظي في الشبكة أو خطأ 5xx من طرفك سيؤدي إلى إعادة المحاولة. الممارسة القياسية هي استخدام webhook-id الموجود في ترويسة الطلب كمفتاح لضمان التكرار (Idempotency Key)، حيث تقوم بالتحقق منه في قاعدة البيانات أو Redis، وإذا تمت معالجته مسبقاً، قم بإرجاع رمز 2xx مباشرة.
هل يمكن استخدام الـ Webhooks الثابتة (Static) والديناميكية (Dynamic) معاً؟
نعم، بل يُنصح بذلك. النمط الشائع هو: استخدام الـ Webhook الثابت كـ "إشعار شامل للطوارئ" (مثل إرسال جميع أحداث الفشل إلى نظام التنبيهات)، بينما تستخدم الـ Webhook الديناميكي في المهام الحرجة كـ "توجيه مخصص" (مثل إرسال نتائج توليد الفيديو لعميل VIP مباشرة إلى نقطة النهاية الخاصة به).
كيف يتم نشر Gemini API Webhooks في بيئة الإنتاج؟
البنية الموصى بها هي: بوابة HTTPS ← وسيط للتحقق من التوقيع ← إرجاع رمز 2xx بسرعة ← طابور رسائل (Message Queue) ← معالجة غير متزامنة عبر Worker خلفي. هذه البنية قادرة على تحمل تدفقات الـ Webhook المفاجئة، وتسهل عليك المراقبة، إعادة التشغيل، والتدقيق. إذا كنت تستخدم بالفعل بوابة استدعاء ذكاء اصطناعي تعتمد على APIYI (apiyi.com)، فإن دمج نقاط نهاية الـ Webhook فيها سيكون أكثر بساطة.
ما العلاقة بين Gemini API Webhooks و Server-Sent Events (SSE)؟
كلاهما يحل مشكلات مختلفة. SSE هو اتصال طويل الأمد "يبدأ من العميل، ويقوم الخادم بدفع المحتوى عبره"، وهو مناسب لتدفق الرموز (Tokens) في الوقت الفعلي. أما الـ Webhook فهو طلب قصير "يبدأ من الخادم، ويدفع الأحداث عبر الخوادم"، وهو مناسب لإشعارات اكتمال المهام. غالباً ما تستخدم تطبيقات الوكلاء (Agentic apps) كلاهما معاً: طبقة تفاعل المستخدم تستخدم SSE، بينما المهام الخلفية الطويلة تستخدم Webhook.
الخلاصة: المعنى الحقيقي لـ Webhooks في Gemini API
تعد Webhooks في Gemini API تحديثاً يسهل الجانب الهندسي، لكنها في جوهرها تمثل موقفاً واضحاً من Google تجاه شكل تطبيقات الذكاء الاصطناعي؛ فهي ترى أن التيار السائد القادم ليس نمط "طلب واحد واستجابة واحدة" (Chat)، بل خطوط أنابيب الوكلاء (Agentic pipelines) التي تتداخل فيها الأبحاث العميقة، الفيديوهات الطويلة، ومعالجة الدفعات. هذه المسارات تتطلب بطبيعتها نظاماً يعتمد على الأحداث (Event-driven)، والـ Webhook هو مجرد نقل لهذا الواقع من تنفيذ المطورين إلى مستوى المنصة.
بالنسبة للمطورين، يحمل إطلاق Gemini API Webhooks معنى إضافياً: فهو يجعل Gemini يتماشى مع القدرات الهندسية لنظرائه مثل OpenAI وAnthropic (اللذين يدعمان آليات مشابهة)، مما يعني أن نموذج تطوير المهام غير المتزامنة يتقارب بغض النظر عن النموذج الذي تختاره. وبالتكامل مع بوابة وسيطة مثل APIYI (apiyi.com)، يمكنك تجميع إشعارات أحداث نماذج Gemini وClaude وGPT في ناقل أحداث واحد، مما يحقق فعلياً "إمكانية تبديل النماذج دون تغيير خط الأنابيب".
إذا كنت تعمل على تطبيقات الفيديو الطويلة، توليد المحتوى بالجملة، أو أتمتة الوكلاء، فالآن هو الوقت الأمثل للانتقال إلى نظام الـ Webhook المعتمد على الأحداث؛ فالتكنولوجيا ناضجة، والوثائق الرسمية مكتملة، والتكلفة الهامشية للتأخير معدومة، بينما الفوائد (إلغاء الاستعلام الدوري، تقليل التأخير، توفير الحصة) فورية.
📚 قراءة إضافية: تشرح المدونة الرسمية خلفية الإصدار بالتفصيل: blog.google؛ للحصول على قائمة الأحداث الكاملة، حقول البيانات، وأمثلة SDK، يرجى الرجوع إلى Gemini Cookbook: github.com/google-gemini/cookbook؛ لمعايير التوقيع، يرجى مراجعة وثائق Standard Webhooks: standardwebhooks. إذا كنت بحاجة إلى قناة وسيطة مستقرة لاستدعاء Gemini API، يمكنك زيارة موقع APIYI: apiyi.com.
الكاتب: فريق APIYI — نركز على الممارسات الهندسية لواجهات برمجة تطبيقات النماذج الكبيرة والبنية التحتية غير المتزامنة، ونقدم خدمة وسيطة موحدة لنماذج Gemini وClaude وGPT، التفاصيل على apiyi.com
