کاهش اصطکاک و تأخیر در پردازش‌های طولانی‌مدت با استفاده از Webhooks در Gemini API

هم‌زمان با تغییر مسیر Gemini به‌سوی گردش‌کارهای عامل‌محور و پردازش‌های با حجم بالا مانند تحقیق عمیق، تولید ویدئوهای طولانی یا پردازش هزاران پرامپت از طریق Batch API، عملیات‌ها ممکن است حتی ساعت‌ها به طول بینجامد. تا پیش‌ازاین، توسعه‌دهندگان ناگزیر بودند برای بررسی تکمیل یک پردازش، بر سرکشی مداوم (به‌عنوان مثال، فراخوانی مکرر عملیات‌های GET) تکیه کنند.

اکنون، Gemini API قادر است دقیقاً در لحظه پایان‌یافتن یک وظیفه، یک‌بار داده از نوع HTTP POST را به‌صورت لحظه‌ای به سرور شما ارسال (push) کند.

این قابلیت با درنظرگرفتن دو اصل قابلیت اطمینان و امنیت توسعه داده شده است. پیاده‌سازی گوگل به طور دقیق از مشخصات استاندارد Webhook پیروی می‌کند. هر درخواست با استفاده از عنوان‌های webhook-signature، webhook-id و webhook-timestamp مشخص می‌شود که از حملات بازپخش جلوگیری می‌کند. همچنین گوگل تحویلِ «حداقل یک‌بار» (at-least-once delivery) با تلاش‌های مجدد و خودکار تا سقف ۲۴ ساعت تضمین می‌کنید.

می‌توان Webhookها را به‌صورت سراسری در سطح پروژه (با ایمن‌سازی از طریق HMAC) پیکربندی کرد یا آن‌ها را به‌صورت پویا و بر مبنای هر درخواست، برای مسیریابی پردازش‌های خاص بازنویسی کرد (با ایمن‌سازی از طریق JWKS).

در ادامه یک مثال از نحوه پیکربندی پویای یک Webhook برای یک وظیفه دسته‌ای با استفاده از Python SDK آورده شده است:

این قابلیت هم‌اکنون برای تمامی توسعه‌دهندگانی که از Gemini API استفاده می‌کنند، در دسترس است:

from google import genai
from google.genai import types

client = genai.Client()

file_batch_job = client.batches.create(
    model="gemini-3-flash-preview",
    src=inline_requests,
    config={
        "display_name": "My Setup",
        "webhook_config": {
            "uris": ["https://my-api.com/gemini-webhook-dynamic"],
            "user_metadata": {"job_group": "nightly-eval", "priority": "high"},
        },
    },
)

print(f"Created batch job: {file_batch_job.name}")

• مطالعه راهنما: به‌منظور بررسی کاتالوگ کامل رویدادها و یادگیری نحوه ایمن‌سازی نقاط انتهایی خود، مستندات Webhook را مطالعه کنید.
• تمرین عملی: گوگل یک کتابچه راهنمای جامع (Cookbook) نیز تهیه کرده تا در ساخت یک فرایند یکپارچه‌سازی سرتاسری با Webhookها کمک‌کننده باشد.