Gemini Webhooks API

تتيح Webhooks لواجهة Gemini API إرسال إشعارات في الوقت الفعلي إلى الخادم عند اكتمال العمليات غير المتزامنة أو العمليات الطويلة الأمد (LRO). يحلّ ذلك محل الحاجة إلى طلب البيانات من واجهة برمجة التطبيقات لمعرفة آخر الأخبار، ما يقلّل من وقت الاستجابة والجهد.

عرض بتنسيق Markdown عرض مواصفات OpenAPI

CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks

لإنشاء Webhook جديد.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

subscribed_events array (enum (string))  (مطلوبة)

الحقل مطلوب. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

uri string  (مطلوب)

الحقل مطلوب. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

create_time string  (اختياري)

النتائج فقط. الطابع الزمني لوقت إنشاء خطاف الويب

id string  (اختياري)

النتائج فقط. معرّف webhook.

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

new_signing_secret string  (اختياري)

النتائج فقط. المفتاح السرّي الجديد للتوقيع الخاص بخدمة الويب. تتم تعبئة هذا الحقل عند الإنشاء فقط.

signing_secrets array (SigningSecret)  (اختيارية)

النتائج فقط. تمثّل هذه السمة أسرار التوقيع المرتبطة بخطاف الويب هذا.

تمثّل هذه السمة مفتاح توقيع سريًا يُستخدَم للتحقّق من حمولات الويب هوك.

الحقول

expire_time string  (اختياري)

النتائج فقط. تمثّل هذه السمة تاريخ انتهاء صلاحية مفتاح التوقيع السري.

truncated_secret string  (اختياري)

النتائج فقط. تمثّل هذه السمة النسخة المختصرة من سر التوقيع.

state enum (string)  (اختياري)

النتائج فقط. تمثّل هذه السمة حالة الويب هوك.

القيم المحتملة:

  • enabled

    تم تفعيل Webhook.

  • disabled

    أوقف المستخدم خدمة Webhook.

  • disabled_due_to_failed_deliveries

    تم إيقاف Webhook بسبب تعذُّر عمليات التسليم.

subscribed_events array (enum (string))  (اختياري)

الحقل مطلوب. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

update_time string  (اختياري)

النتائج فقط. الطابع الزمني لآخر تعديل على الويب هوك.

uri string  (اختياري)

الحقل مطلوب. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.

مثال

مثال على الردّ

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

PingWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

يرسل حدث ping إلى Webhook.

مَعلمات المسار / طلب البحث

id string  (مطلوبة)

الحقل مطلوب. رقم تعريف خدمة الويب التي سيتم إرسال إشارة إليها التنسيق: `{webhook_id}`

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

الردّ

إذا كانت الاستجابة ناجحة، ستكون فارغة.

مثال

RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

تنشئ هذه الطريقة سر توقيع جديدًا لخدمة Webhook.

مَعلمات المسار / طلب البحث

id string  (مطلوبة)

الحقل مطلوب. رقم تعريف خطاف الويب الذي سيتم إنشاء سرّ توقيع له. التنسيق: `{webhook_id}`

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

revocation_behavior enum (string)  (اختياري)

اختياريّ. سلوك الإبطال لأسرار التوقيع السابقة

القيم المحتملة:

  • revoke_previous_secrets_after_h24

    أنشئ سر توقيع جديدًا وأبطِل جميع الأسرار السابقة بعد مرور 24 ساعة. الخيار التلقائي والأكثر أمانًا لعمليات نقل البيانات

  • revoke_previous_secrets_immediately

    إبطال جميع الأسرار السابقة على الفور يجب توخّي الحذر عند استخدام هذا الخيار لأنّه قد يؤدي إلى مقاطعة الإشعارات الجارية.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

secret string  (اختياري)

النتائج فقط. المفتاح السرّي للتوقيع الذي تم إنشاؤه حديثًا

مثال

مثال على الردّ

{
  "secret": "string"
}

ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks

تعرض هذه الطريقة جميع Webhooks.

مَعلمات المسار / طلب البحث

page_size integer  (اختيارية)

اختياريّ. الحد الأقصى لعدد خطافات الويب المطلوب عرضها. قد تعرض الخدمة عددًا أقل من هذه القيمة. إذا لم يتم تحديدها، سيتم عرض 50 خطاف ويب على الأكثر. الحد الأقصى للقيمة هو 1,000.

page_token string  (اختياري)

اختياريّ. رمز مميّز للصفحة تم استلامه من طلب `ListWebhooks` سابق. يجب تقديم هذا الرمز لاسترداد الصفحة التالية.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

next_page_token string  (اختياري)

رمز مميّز يمكن إرساله كـ `page_token` لاسترداد الصفحة التالية. في حال حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

webhooks مصفوفة (Webhook)  (اختيارية)

الويب هوك

مثال

مثال على الردّ

{
  "next_page_token": "string",
  "webhooks": [
    {
      "create_time": "string",
      "id": "string",
      "name": "string",
      "new_signing_secret": "string",
      "signing_secrets": [
        {
          "expire_time": "string",
          "truncated_secret": "string"
        }
      ],
      "state": "enabled",
      "subscribed_events": [
        "batch.succeeded"
      ],
      "update_time": "string",
      "uri": "string"
    }
  ]
}

GetWebhook

get https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

تعرض هذه الطريقة Webhook محدّدًا.

مَعلمات المسار / طلب البحث

id string  (مطلوبة)

الحقل مطلوب. معرّف Webhook المطلوب استرداده.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

create_time string  (اختياري)

النتائج فقط. الطابع الزمني لوقت إنشاء خطاف الويب

id string  (اختياري)

النتائج فقط. معرّف webhook.

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

new_signing_secret string  (اختياري)

النتائج فقط. المفتاح السرّي الجديد للتوقيع الخاص بخدمة الويب. تتم تعبئة هذا الحقل عند الإنشاء فقط.

signing_secrets array (SigningSecret)  (اختيارية)

النتائج فقط. تمثّل هذه السمة أسرار التوقيع المرتبطة بخطاف الويب هذا.

تمثّل هذه السمة مفتاح توقيع سريًا يُستخدَم للتحقّق من حمولات الويب هوك.

الحقول

expire_time string  (اختياري)

النتائج فقط. تمثّل هذه السمة تاريخ انتهاء صلاحية مفتاح التوقيع السري.

truncated_secret string  (اختياري)

النتائج فقط. تمثّل هذه السمة النسخة المختصرة من سر التوقيع.

state enum (string)  (اختياري)

النتائج فقط. تمثّل هذه السمة حالة الويب هوك.

القيم المحتملة:

  • enabled

    تم تفعيل Webhook.

  • disabled

    أوقف المستخدم خدمة Webhook.

  • disabled_due_to_failed_deliveries

    تم إيقاف Webhook بسبب تعذُّر عمليات التسليم.

subscribed_events array (enum (string))  (اختياري)

الحقل مطلوب. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

update_time string  (اختياري)

النتائج فقط. الطابع الزمني لآخر تعديل على الويب هوك.

uri string  (اختياري)

الحقل مطلوب. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.

مثال

مثال على الردّ

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

UpdateWebhook

patch https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

تعديل Webhook حالي

مَعلمات المسار / طلب البحث

id string  (مطلوبة)

الحقل مطلوب. رقم تعريف الويب هوك المطلوب تعديله.

update_mask string  (اختياري)

اختياريّ. قائمة الحقول التي سيتم تعديلها.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

state enum (string)  (اختياري)

اختياريّ. تمثّل هذه السمة حالة الويب هوك.

القيم المحتملة:

  • enabled

    تم تفعيل Webhook.

  • disabled

    أوقف المستخدم خدمة Webhook.

  • disabled_due_to_failed_deliveries

    تم إيقاف Webhook بسبب تعذُّر عمليات التسليم.

subscribed_events array (enum (string))  (اختياري)

اختياريّ. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

uri string  (اختياري)

اختياريّ. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.

الردّ

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

create_time string  (اختياري)

النتائج فقط. الطابع الزمني لوقت إنشاء خطاف الويب

id string  (اختياري)

النتائج فقط. معرّف webhook.

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

new_signing_secret string  (اختياري)

النتائج فقط. المفتاح السرّي الجديد للتوقيع الخاص بخدمة الويب. تتم تعبئة هذا الحقل عند الإنشاء فقط.

signing_secrets array (SigningSecret)  (اختيارية)

النتائج فقط. تمثّل هذه السمة أسرار التوقيع المرتبطة بخطاف الويب هذا.

تمثّل هذه السمة مفتاح توقيع سريًا يُستخدَم للتحقّق من حمولات الويب هوك.

الحقول

expire_time string  (اختياري)

النتائج فقط. تمثّل هذه السمة تاريخ انتهاء صلاحية مفتاح التوقيع السري.

truncated_secret string  (اختياري)

النتائج فقط. تمثّل هذه السمة النسخة المختصرة من سر التوقيع.

state enum (string)  (اختياري)

النتائج فقط. تمثّل هذه السمة حالة الويب هوك.

القيم المحتملة:

  • enabled

    تم تفعيل Webhook.

  • disabled

    أوقف المستخدم خدمة Webhook.

  • disabled_due_to_failed_deliveries

    تم إيقاف Webhook بسبب تعذُّر عمليات التسليم.

subscribed_events array (enum (string))  (اختياري)

الحقل مطلوب. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

update_time string  (اختياري)

النتائج فقط. الطابع الزمني لآخر تعديل على الويب هوك.

uri string  (اختياري)

الحقل مطلوب. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.

مثال

مثال على الردّ

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

DeleteWebhook

delete https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

يحذف هذا الإجراء Webhook.

مَعلمات المسار / طلب البحث

id string  (مطلوبة)

الحقل مطلوب. معرّف الويب هوك المطلوب حذفه. التنسيق: `{webhook_id}`

الردّ

إذا كانت الاستجابة ناجحة، ستكون فارغة.

مثال

الموارد

ويب هوك

أحد موارد Webhook.

الحقول

create_time string  (اختياري)

النتائج فقط. الطابع الزمني لوقت إنشاء خطاف الويب

id string  (اختياري)

النتائج فقط. معرّف webhook.

name string  (اختياري)

اختياريّ. اسم webhook الذي يقدّمه المستخدم.

new_signing_secret string  (اختياري)

النتائج فقط. المفتاح السرّي الجديد للتوقيع الخاص بخدمة الويب. تتم تعبئة هذا الحقل عند الإنشاء فقط.

signing_secrets array (SigningSecret)  (اختيارية)

النتائج فقط. تمثّل هذه السمة أسرار التوقيع المرتبطة بخطاف الويب هذا.

تمثّل هذه السمة مفتاح توقيع سريًا يُستخدَم للتحقّق من حمولات الويب هوك.

الحقول

expire_time string  (اختياري)

النتائج فقط. تمثّل هذه السمة تاريخ انتهاء صلاحية مفتاح التوقيع السري.

truncated_secret string  (اختياري)

النتائج فقط. تمثّل هذه السمة النسخة المختصرة من سر التوقيع.

state enum (string)  (اختياري)

النتائج فقط. تمثّل هذه السمة حالة الويب هوك.

القيم المحتملة:

  • enabled

    تم تفعيل Webhook.

  • disabled

    أوقف المستخدم خدمة Webhook.

  • disabled_due_to_failed_deliveries

    تم إيقاف Webhook بسبب تعذُّر عمليات التسليم.

subscribed_events array (enum (string))  (اختياري)

الحقل مطلوب. الأحداث التي تم الاشتراك في إشعاراتها عبر رابط الويب. الأحداث المتاحة: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

القيم المحتملة:

  • batch.succeeded

    اكتملت المعالجة على دفعات بنجاح.

  • batch.expired

    لم تتم معالجة الدفعة خلال الإطار الزمني البالغ 48 ساعة.

  • batch.failed

    تعذّرت مهمة الدفعات.

  • interaction.requires_action

    يتطلّب التفاعل اتّخاذ إجراء (مثل استدعاء دالة).

  • interaction.completed

    اكتمل التفاعل بنجاح.

  • interaction.failed

    تعذّر التفاعل.

  • video.generated

    اكتملت عملية إنشاء الفيديو.

update_time string  (اختياري)

النتائج فقط. الطابع الزمني لآخر تعديل على الويب هوك.

uri string  (اختياري)

الحقل مطلوب. معرّف الموارد المنتظم الذي سيتم إرسال أحداث Webhook إليه.