İçeriğe geç
TR
API anahtarı al
Belgeleri incele

API başvurusu

Tamamlanma web kancaları

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.

callback_url içeren eşzamansız sorgu
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
callback_url içeren Bulk işi
{
  "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.

AlanAçıklama
delivery_idEş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).
statusSon durum: eşzamansız/toplu için completed veya failed; manifesto yayımlandıktan sonra Bulk için completed.
linksKimlik doğrulamalı Management API durum ve sonuç bağlantıları. Sonuçları almadan önce daima API üzerinden doğrulayın.
Eşzamansız / toplu tamamlanma olayı
{
  "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"
    }
  ]
}
Bulk tamamlanma olayı
{
  "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.

Minimal Node.js web kancası alıcısı
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);