Webhooki

Webhooki umożliwiają interfejsowi Gemini API wysyłanie powiadomień w czasie rzeczywistym na Twój serwer po zakończeniu operacji asynchronicznych lub długotrwałych. Eliminuje to konieczność sondowania interfejsu API w celu uzyskania aktualizacji stanu, co zmniejsza opóźnienia i obciążenie.

Webhooki są dostępne w przypadku operacji takich jak zadania zbiorcze, interakcje i generowanie filmów.

Jak to działa

Zamiast wielokrotnie sondować GET /operations, aby sprawdzić, czy zadanie zostało zakończone, możesz skonfigurować webhooki Gemini API tak, aby natychmiast po wywołaniu zdarzenia wysyłały żądanie HTTP POST na adres URL odbiornika.

Interfejs Gemini API obsługuje 2 sposoby konfigurowania webhooków:

• Webhooki statyczne: punkty końcowe na poziomie projektu skonfigurowane za pomocą interfejsu Gemini WebhookService API. Nadają się do integracji globalnych (np. powiadamiania Slacka, synchronizowania bazy danych itp.).
• Webhooki dynamiczne: zastąpienia na poziomie żądania, które przekazują adres URL webhooka w ładunku konfiguracji konkretnego wywołania zadania. Idealne do kierowania konkretnych zadań do dedykowanych punktów końcowych.

Webhooki statyczne

Webhooki statyczne są rejestrowane dla całego projektu i są wywoływane w przypadku każdego pasującego zdarzenia.

Tworzenie webhooka

Punkty końcowe możesz tworzyć za pomocą pakietu SDK lub interfejsu REST API.

WAŻNE: podczas tworzenia webhooka interfejs API zwraca obiekt tajny podpisywania tylko raz. Aby później weryfikować podpisy, musisz go bezpiecznie przechowywać (np. w zmiennych środowiskowych). Jeśli utracisz obiekt tajny podpisywania, musisz go zmienić.

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"]
  }'

Więcej informacji o konfigurowaniu serwera do odbierania danych znajdziesz w sekcji Obsługa żądań webhooka.

Pobieranie webhooka

Pobierz szczegóły konkretnego webhooka według jego nazwy zasobu.

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