وب هوک ها

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

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

چگونه کار می‌کند؟

به جای اینکه مرتباً از GET /operations برای بررسی اتمام یک کار استفاده کنید، می‌توانید Gemini API Webhooks را طوری پیکربندی کنید که بلافاصله پس از وقوع یک رویداد، یک درخواست HTTP POST به آدرس اینترنتی شنونده شما ارسال کند.

رابط برنامه‌نویسی کاربردی Gemini از دو روش برای پیکربندی وب‌هوک‌ها پشتیبانی می‌کند:

• وب‌هوک‌های استاتیک : نقاط پایانی سطح پروژه که با رابط برنامه‌نویسی Gemini WebhookService پیکربندی شده‌اند. برای یکپارچه‌سازی‌های جهانی (مثلاً اطلاع‌رسانی به Slack، همگام‌سازی پایگاه داده و غیره) مناسب هستند.
• وب‌هوک‌های پویا : سطح درخواست، ارسال یک URL وب‌هوک را در پیکربندی یک فراخوانی شغل خاص لغو می‌کند. ایده‌آل برای مسیریابی مشاغل خاص به نقاط انتهایی اختصاصی.

وب‌هوک‌های استاتیک

وب‌هوک‌های استاتیک برای کل پروژه ثبت می‌شوند و برای هر رویداد منطبق، فعال می‌شوند.

ایجاد یک وب هوک

شما می‌توانید با استفاده از SDK یا REST API، نقاط پایانی (endpoints) ایجاد کنید.

مهم : هنگام ایجاد یک وب‌هوک، API فقط یک بار رمز امضا را برمی‌گرداند. شما باید این را به طور ایمن (مثلاً در متغیرهای محیطی خود) ذخیره کنید تا بعداً امضاها را تأیید کنید. اگر رمز امضا را گم کنید، باید آن را بچرخانید .

from google import genai

client = genai.Client()

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.succeeded", "batch.failed"],
    uri="https://my-api.com/gemini-callback",
)

# Store webhook.new_signing_secret securely
webhook_secret = webhook.new_signing_secret
print(f"Created webhook: {webhook.name}, {webhook.id}")

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function createWebhook() {
  const webhook = await client.webhooks.create({
    name: "MyBatchWebhook",
    subscribed_events: ["batch.succeeded", "batch.failed"],
    uri: "https://my-api.com/gemini-callback",
  });

  // Store webhook.signingSecret securely
  const webhookSecret = webhook.new_signing_secret;
  console.log(`Created webhook: ${webhook.name}, ${webhook.id}`);
}

createWebhook();

curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY"