Semak dokumentasi
Rujukan API
Terima, nyahduplikasi dan sahkan pemberitahuan penyelesaian untuk tugasan async, kelompok dan Bulk.
Pada halaman ini
Konfigurasikan callback_url
Bekalkan callback_url HTTPS awam pada port 443 (sehingga 2,048 aksara, tanpa kelayakan atau serpihan URL) semasa menghantar pertanyaan async, item kelompok atau tugasan Bulk. Abaikan callback_url, atau hantar null atau rentetan kosong, untuk melumpuhkan pemberitahuan.
Untuk permintaan async dan kelompok (POST /v1/queries dan POST /v1/queries/batch), letakkan callback_url pada peringkat atas objek pertanyaan, di luar params. Untuk tugasan Bulk (POST /v2/bulk-jobs), letakkan callback_url pada peringkat atas, di luar options.
{
"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
}
}URL panggilan balik disimpan berbanding callback_url setiap permintaan
Management API turut mendedahkan URL panggilan balik tersimpan yang diuruskan konsol di bawah /v2/delivery/webhooks (cookieSession + csrfToken) untuk menyimpan destinasi boleh guna semula dan menghantar muatan ujian melalui POST /v2/delivery/webhooks/{webhookId}/test. Integrasi API berprogram hendaklah menghantar callback_url secara terus pada setiap penyerahan.
Muatan acara dan pengepala
Pemberitahuan mengesahkan tugasan mencapai completed atau failed (atau manifes Bulk telah diterbitkan). Muatan tidak pernah mengandungi hasil pertanyaan, fail media atau kunci API anda. Nyahduplikasi penghantaran menggunakan delivery_id (turut dihantar dalam pengepala X-Delivery-Id).
| Medan | Maksud |
|---|---|
delivery_id | Pengecam penghantaran stabil untuk penyahduplikasian idempoten; sepadan dengan pengepala X-Delivery-Id. |
| id | Pengecam tugasan atau tugasan Bulk. Padankan dengan resit yang disimpan semasa penyerahan. |
| source | Sumber data yang diminta (contohnya google_search atau youtube_download). |
| status | Keadaan akhir: completed atau failed untuk async/kelompok; completed untuk Bulk selepas penerbitan manifes. |
| links | Pautan status dan hasil Management API yang disahkan. Sentiasa sahkan melalui API sebelum mengambil hasil. |
{
"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"
}
]
}Cubaan semula, pengesahan dan keselamatan penerima
Penghantaran dicuba sehingga lapan kali secara keseluruhan, termasuk cubaan pertama, dengan backoff eksponen. Pulangkan respons 2xx dengan segera selepas menyimpan delivery_id.
Acara webhook tidak ditandatangani. Jangan sekali-kali mempercayai URL muatan secara membuta tuli atau menghubungi hos sebarangan: padankan id dan source dengan resit simpanan anda, sahkan status melalui GET /v2/jobs/{id} atau GET /v2/bulk-jobs/{bulkId} dengan X-API-Key, dan kekalkan tinjauan status sebagai sandaran.
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);