Вебхуки

Веб-хуки позволяют API Gemini отправлять на ваш сервер уведомления в режиме реального времени о завершении асинхронных операций или длительных операций (LRO). Это избавляет от необходимости опрашивать API для получения обновлений статуса, снижая задержку и накладные расходы.

Веб-хуки доступны для таких операций, как пакетная обработка заданий, взаимодействие с пользователями и генерация видео .

Как это работает

Вместо того чтобы многократно опрашивать GET /operations для проверки завершения задания, вы можете настроить веб-перехватчики API Gemini таким образом, чтобы они отправляли HTTP POST-запрос на ваш URL-адрес прослушивателя сразу после срабатывания события.

API Gemini поддерживает два способа настройки веб-хуков:

• Статические веб-хуки : конечные точки на уровне проекта, настраиваемые с помощью API Gemini WebhookService . Подходят для глобальной интеграции (например, уведомления Slack, синхронизация базы данных и т. д.).
• Динамические веб-хуки : переопределение на уровне запроса, позволяющее передавать URL-адрес веб-хука в конфигурационном пакете вызова конкретного задания. Идеально подходит для маршрутизации конкретных заданий к выделенным конечным точкам.

Статические веб-хуки

Статические веб-хуки регистрируются для всего проекта и срабатывают при любом соответствующем событии.

Создайте веб-перехватчик

Вы можете создавать конечные точки, используя SDK или REST API.

ВАЖНО : При создании веб-хука 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" \
  -d '{
    "name": "MyBatchWebhook",
    "uri": "https://my-api.com/gemini-callback",
    "subscribed_events": ["batch.succeeded", "batch.failed"]
  }'

Подробную информацию о настройке сервера для приема данных см. в разделе «Обработка запросов веб-перехватчика» .

Получите веб-хук

Получить подробную информацию о конкретном веб-перехватчике по его имени ресурса.

from google import genai

client = genai.Client()

webhook = client.webhooks.get(id="<your_webhook_id>")

print(f"Webhook: {webhook.name}")
print(f"URI: {webhook.uri}")
print(f