Gemini Webhooks API

وب‌هوک‌ها به API مربوط به Gemini اجازه می‌دهند تا هنگام تکمیل عملیات ناهمزمان یا عملیات طولانی‌مدت (LRO) اعلان‌های بلادرنگ را به سرور شما ارسال کند. این امر جایگزین نیاز به نظرسنجی از API برای به‌روزرسانی وضعیت می‌شود و تأخیر و سربار را کاهش می‌دهد.

مشاهده به صورت markdown مشاهده مشخصات OpenAPI

ایجاد وب‌هوک

ارسال به آدرس https://generativelanguage.googleapis.com/v1beta/webhooks

یک وب‌هوک جدید ایجاد می‌کند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

آرایه subscribed_events (enum (string)) (الزامی)

رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته uri (الزامی)

الزامی. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.

پاسخ

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

رشته‌ی create_time (اختیاری)

فقط خروجی. مهر زمانی که وب‌هوک ایجاد شده است.

رشته شناسه (اختیاری)

فقط خروجی. شناسه وب هوک.

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

رشته new_signing_secret (اختیاری)

فقط خروجی. رمز امضای جدید برای وب‌هوک. فقط در هنگام ایجاد، مقداردهی می‌شود.

آرایه signing_secrets (SigningSecret) (اختیاری)

فقط خروجی. اسرار امضای مرتبط با این وب‌هوک.

نشان‌دهنده‌ی یک رمز امضا است که برای تأیید بارهای داده‌ی وب‌هوک استفاده می‌شود.

فیلدها

رشته expire_time (اختیاری)

فقط خروجی. تاریخ انقضای رمز امضا.

رشته truncated_secret (اختیاری)

فقط خروجی. نسخه کوتاه‌شده‌ی رمز امضا.

شمارشگر وضعیت (رشته) (اختیاری)

فقط خروجی. وضعیت وب‌هوک.

مقادیر ممکن:

  • enabled

    وب هوک فعال شده است.

  • disabled

    وب هوک توسط کاربر غیرفعال شده است.

  • disabled_due_to_failed_deliveries

    به دلیل ارسال ناموفق، وب‌هوک غیرفعال است.

آرایه subscribed_events (enum (رشته)) (اختیاری)

رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته‌ی update_time (اختیاری)

فقط خروجی. نشانگر زمانی آخرین به‌روزرسانی وب‌هوک.

رشته uri (اختیاری)

الزامی. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.

مثال

پاسخ نمونه 

{
  "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"
}

پینگ‌وب‌هوک

ارسال https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

یک رویداد پینگ را به یک وب‌هوک ارسال می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

الزامی. شناسه وب‌هوک برای پینگ. فرمت: `{webhook_id}`

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

پاسخ

در صورت موفقیت، پاسخ خالی است.

مثال

چرخش امضای مخفی

ارسال https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

یک رمز امضای جدید برای یک وب‌هوک ایجاد می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

الزامی. شناسه وب‌هوک که برای آن یک رمز امضا ایجاد می‌شود. قالب: `{webhook_id}`

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

تابع شمارشی revocation_behavior (رشته‌ای) (اختیاری)

اختیاری. رفتار ابطال برای رمزهای امضای قبلی.

مقادیر ممکن:

  • revoke_previous_secrets_after_h24

    یک رمز امضای جدید ایجاد کنید و تمام رمزهای قبلی را پس از ۲۴ ساعت لغو کنید. گزینه پیش‌فرض و امن‌ترین گزینه برای مهاجرت‌ها.

  • revoke_previous_secrets_immediately

    فوراً تمام اسرار قبلی را لغو کنید. با احتیاط استفاده کنید زیرا این کار می‌تواند اعلان‌های جاری را مختل کند.

پاسخ

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

رشته مخفی (اختیاری)

فقط خروجی. رمز امضای تازه تولید شده.

مثال

پاسخ نمونه 

{
  "secret": "string"
}

لیست وب هوک ها

دریافت https://generativelanguage.googleapis.com/v1beta/webhooks

تمام وب‌هوک‌ها را فهرست می‌کند.

پارامترهای مسیر/پرس‌وجو

عدد صحیح page_size (اختیاری)

اختیاری. حداکثر تعداد وب‌هوک‌هایی که باید برگردانده شوند. سرویس ممکن است کمتر از این مقدار را برگرداند. در صورت عدم تعیین، حداکثر ۵۰ وب‌هوک برگردانده خواهد شد. حداکثر مقدار ۱۰۰۰ است.

رشته‌ی page_token (اختیاری)

اختیاری. یک توکن صفحه، که از فراخوانی قبلی `ListWebhooks` دریافت شده است. این را برای بازیابی صفحه بعدی ارائه دهید.

پاسخ

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

رشته‌ی next_page_token (اختیاری)

یک توکن، که می‌تواند به عنوان `page_token` برای بازیابی صفحه بعدی ارسال شود. اگر این فیلد حذف شود، صفحات بعدی وجود نخواهند داشت.

آرایه وب هوک‌ها ( 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

دریافت کنید https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

یک وب‌هوک خاص دریافت می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

الزامی. شناسه‌ی وب‌هوک مورد نظر برای بازیابی.

پاسخ

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

رشته‌ی create_time (اختیاری)

فقط خروجی. مهر زمانی که وب‌هوک ایجاد شده است.

رشته شناسه (اختیاری)

فقط خروجی. شناسه وب هوک.

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

رشته new_signing_secret (اختیاری)

فقط خروجی. رمز امضای جدید برای وب‌هوک. فقط در هنگام ایجاد، مقداردهی می‌شود.

آرایه signing_secrets (SigningSecret) (اختیاری)

فقط خروجی. اسرار امضای مرتبط با این وب‌هوک.

نشان‌دهنده‌ی یک رمز امضا است که برای تأیید بارهای داده‌ی وب‌هوک استفاده می‌شود.

فیلدها

رشته expire_time (اختیاری)

فقط خروجی. تاریخ انقضای رمز امضا.

رشته truncated_secret (اختیاری)

فقط خروجی. نسخه کوتاه‌شده‌ی رمز امضا.

شمارشگر وضعیت (رشته) (اختیاری)

فقط خروجی. وضعیت وب‌هوک.

مقادیر ممکن:

  • enabled

    وب هوک فعال شده است.

  • disabled

    وب هوک توسط کاربر غیرفعال شده است.

  • disabled_due_to_failed_deliveries

    به دلیل ارسال ناموفق، وب‌هوک غیرفعال است.

آرایه subscribed_events (enum (رشته)) (اختیاری)

رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته‌ی update_time (اختیاری)

فقط خروجی. نشانگر زمانی آخرین به‌روزرسانی وب‌هوک.

رشته uri (اختیاری)

الزامی. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.

مثال

پاسخ نمونه 

{
  "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"
}

به‌روزرسانی وب‌هوک

وصله https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

یک وب‌هوک موجود را به‌روزرسانی می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

الزامی. شناسه‌ی وب‌هوک مورد نظر برای به‌روزرسانی.

رشته update_mask (اختیاری)

اختیاری. لیست فیلدهایی که باید به‌روزرسانی شوند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

شمارشگر وضعیت (رشته) (اختیاری)

اختیاری. وضعیت وب‌هوک.

مقادیر ممکن:

  • enabled

    وب هوک فعال شده است.

  • disabled

    وب هوک توسط کاربر غیرفعال شده است.

  • disabled_due_to_failed_deliveries

    به دلیل ارسال ناموفق، وب‌هوک غیرفعال است.

آرایه subscribed_events (enum (رشته)) (اختیاری)

اختیاری. رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته uri (اختیاری)

اختیاری. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.

پاسخ

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

رشته‌ی create_time (اختیاری)

فقط خروجی. مهر زمانی که وب‌هوک ایجاد شده است.

رشته شناسه (اختیاری)

فقط خروجی. شناسه وب هوک.

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

رشته new_signing_secret (اختیاری)

فقط خروجی. رمز امضای جدید برای وب‌هوک. فقط در هنگام ایجاد، مقداردهی می‌شود.

آرایه signing_secrets (SigningSecret) (اختیاری)

فقط خروجی. اسرار امضای مرتبط با این وب‌هوک.

نشان‌دهنده‌ی یک رمز امضا است که برای تأیید بارهای داده‌ی وب‌هوک استفاده می‌شود.

فیلدها

رشته expire_time (اختیاری)

فقط خروجی. تاریخ انقضای رمز امضا.

رشته truncated_secret (اختیاری)

فقط خروجی. نسخه کوتاه‌شده‌ی رمز امضا.

شمارشگر وضعیت (رشته) (اختیاری)

فقط خروجی. وضعیت وب‌هوک.

مقادیر ممکن:

  • enabled

    وب هوک فعال شده است.

  • disabled

    وب هوک توسط کاربر غیرفعال شده است.

  • disabled_due_to_failed_deliveries

    به دلیل ارسال ناموفق، وب‌هوک غیرفعال است.

آرایه subscribed_events (enum (رشته)) (اختیاری)

رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته‌ی update_time (اختیاری)

فقط خروجی. نشانگر زمانی آخرین به‌روزرسانی وب‌هوک.

رشته uri (اختیاری)

الزامی. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.

مثال

پاسخ نمونه 

{
  "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"
}

حذف وب‌هوک

https://generativelanguage.googleapis.com/v1beta/webhooks/{id} را حذف کنید

یک وب‌هوک را حذف می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

الزامی. شناسه وب‌هوک مورد نظر برای حذف. فرمت: `{webhook_id}`

پاسخ

در صورت موفقیت، پاسخ خالی است.

مثال

منابع

وب‌هوک

یک منبع وب‌هوک.

فیلدها

رشته‌ی create_time (اختیاری)

فقط خروجی. مهر زمانی که وب‌هوک ایجاد شده است.

رشته شناسه (اختیاری)

فقط خروجی. شناسه وب هوک.

رشته نام (اختیاری)

اختیاری. نام وب‌هوک که توسط کاربر ارائه شده است.

رشته new_signing_secret (اختیاری)

فقط خروجی. رمز امضای جدید برای وب‌هوک. فقط در هنگام ایجاد، مقداردهی می‌شود.

آرایه signing_secrets (SigningSecret) (اختیاری)

فقط خروجی. اسرار امضای مرتبط با این وب‌هوک.

نشان‌دهنده‌ی یک رمز امضا است که برای تأیید بارهای داده‌ی وب‌هوک استفاده می‌شود.

فیلدها

رشته expire_time (اختیاری)

فقط خروجی. تاریخ انقضای رمز امضا.

رشته truncated_secret (اختیاری)

فقط خروجی. نسخه کوتاه‌شده‌ی رمز امضا.

شمارشگر وضعیت (رشته) (اختیاری)

فقط خروجی. وضعیت وب‌هوک.

مقادیر ممکن:

  • enabled

    وب هوک فعال شده است.

  • disabled

    وب هوک توسط کاربر غیرفعال شده است.

  • disabled_due_to_failed_deliveries

    به دلیل ارسال ناموفق، وب‌هوک غیرفعال است.

آرایه subscribed_events (enum (رشته)) (اختیاری)

رویدادهایی که وب‌هوک در آنها مشترک می‌شود. رویدادهای موجود: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

مقادیر ممکن:

  • batch.succeeded

    پردازش دسته‌ای با موفقیت به پایان رسید.

  • batch.expired

    دسته در بازه زمانی ۴۸ ساعته پردازش نشده است.

  • batch.failed

    کار دسته‌ای ناموفق بود.

  • interaction.requires_action

    تعامل نیازمند عمل است (مثلاً فراخوانی تابع).

  • interaction.completed

    تعامل با موفقیت انجام شد.

  • interaction.failed

    تعامل ناموفق بود.

  • video.generated

    تولید ویدیو به پایان رسید.

رشته‌ی update_time (اختیاری)

فقط خروجی. نشانگر زمانی آخرین به‌روزرسانی وب‌هوک.

رشته uri (اختیاری)

الزامی. آدرس اینترنتی (URI) که رویدادهای وب‌هوک به آن ارسال می‌شوند.