Belgeleri incele
API başvurusu
Eşzamansız, toplu ve Bulk tamamlanma bildirimlerini alın, tekilleştirin ve doğrulayın.
Bu sayfada
callback_url yapılandırma
Eşzamansız sorgu, toplu işlem öğesi veya Bulk işi gönderirken 443 numaralı bağlantı noktasında herkese açık bir HTTPS callback_url belirtin (en fazla 2.048 karakter, kimlik bilgisi veya URL parçası olmadan). Bildirimleri kapatmak için callback_url alanını atlayın ya da null veya boş dize gönderin.
Eşzamansız ve toplu isteklerde (POST /v1/queries ve POST /v1/queries/batch) callback_url alanını params dışındaki üst düzey sorgu nesnesine koyun. Bulk işlerinde (POST /v2/bulk-jobs) callback_url alanını options dışındaki üst düzeye yerleştirin.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://example.com/webhooks/flashdata"
}{
"source": "youtube_metadata",
"callback_url": "https://example.com/webhooks/flashdata",
"options": {
"include_formats": false
}
}Kayıtlı geri çağrı URL'leri ve istek başına callback_url
Management API ayrıca yeniden kullanılabilir hedefleri kaydetmek ve POST /v2/delivery/webhooks/{webhookId}/test üzerinden test yükleri göndermek için konsoldan yönetilen /v2/delivery/webhooks (cookieSession + csrfToken) uç noktalarını sunar. Programatik API entegrasyonları her gönderimde callback_url değerini doğrudan iletmelidir.
Olay yükleri ve üstbilgiler
Bildirimler, bir işin completed veya failed durumuna ulaştığını (veya bir Bulk manifestosunun yayımlandığını) onaylar. Yükler hiçbir zaman sorgu sonuçlarını, medya dosyalarını veya API anahtarınızı içermez. Teslimatları delivery_id (X-Delivery-Id üstbilgisinde de gönderilir) ile tekilleştirin.
| Alan | Açıklama |
|---|---|
delivery_id | Eşetkili tekilleştirme için sabit teslimat kimliği; X-Delivery-Id üstbilgisiyle eşleşir. |
| id | İş veya Bulk iş kimliği. Gönderim sırasında kaydedilen makbuzla eşleştirin. |
| source | İstenen veri kaynağı (örneğin google_search veya youtube_download). |
| status | Son durum: eşzamansız/toplu için completed veya failed; manifesto yayımlandıktan sonra Bulk için completed. |
| links | Kimlik doğrulamalı Management API durum ve sonuç bağlantıları. Sonuçları almadan önce daima API üzerinden doğrulayın. |
{
"delivery_id": "dlv_01JEXAMPLE0000000000000000",
"id": "job_01JEXAMPLE0000000000000000",
"source": "google_search",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000/results",
"method": "GET"
}
]
}{
"delivery_id": "dlv_01JEXAMPLE0000000000000001",
"id": "bulk_01JEXAMPLE0000000000000000",
"source": "youtube_metadata",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000",
"method": "GET"
},
{
"rel": "manifest",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000/manifest",
"method": "GET"
}
]
}Yeniden denemeler, doğrulama ve alıcı güvenliği
Teslimat, ilk deneme dahil olmak üzere üstel geri çekilme ile toplamda en fazla sekiz kez denenir. delivery_id kaydedildikten hemen sonra 2xx yanıtı döndürün.
Web kancası olayları imzasızdır. Yük içindeki URL'lere körü körüne güvenmeyin ve rastgele ana bilgisayarlara istek atmayın: id ve source alanlarını kayıtlı makbuzunuzla eşleştirin, X-API-Key ile GET /v2/jobs/{id} veya GET /v2/bulk-jobs/{bulkId} üzerinden durumu doğrulayın ve yedek olarak durum yoklamasını koruyun.
import http from "node:http";
const seen = new Set(); // Replace with durable database storage in production.
http.createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/webhooks/flashdata") {
res.writeHead(404).end();
return;
}
const chunks = [];
req.on("data", chunk => chunks.push(chunk));
req.on("end", () => {
const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));
const deliveryId = String(req.headers["x-delivery-id"] ?? event.delivery_id ?? "");
if (!deliveryId || seen.has(deliveryId)) {
res.writeHead(200).end("ok");
return;
}
seen.add(deliveryId);
// Queue background verification against https://api.flashdata.dev/v2/jobs/{id}
// or /v2/bulk-jobs/{id} with X-API-Key; ignore unverified URLs in event.links.
res.writeHead(200).end("accepted");
});
}).listen(3000);