تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

الأدلة

يضاف البحث إلى الطلب

بناء استمارة بحث عمل، وإبقاء مفتاح API على ظهرك، وإعادة استخدام وظيفة البحث نفسها في أداة وكيل.

في هذه الصفحة

ما ستبنيه

- استمارة بحث محلية ذات وصلات مرتبة، ودماغات، وإستخدامات ائتمانية. Requires Node.js 22+, a key with google_search permission and available credits. ولا توجد حاجة إلى أي حزمة من طراز npm. ويعيد فرع الوكيل الاختياري استخدام نفس وظيفة المساندة.

انقذوا في "مجلة "البحث عن البياناتالغرض
search.mjsيدعو FlashData من الخلف؛ متقاسمة مع الشكل وأداة العميل.
server.mjsويعمل في الصفحة المحلية وفي نقطة نهاية GET /search.
index.htmlيصور المصادر، النتائج الفارغة والأخطاء.
Bash or PowerShell · create the project
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

جهزوا API المفتاح

إعادة استخدام FLASHDATA_API_KEY إذا تم تحديده بالفعل. وإلا استخدم العجلة المخفية أسفل في المحطة التي ستدير الرمز. يمكن للعميل أن يحمل نفس المتغير من متجره السري

حدد المفتاح
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

1. إنشاء وظيفة البحث

انقذوا search.mjs في ملف مشروعك نداء واحد يعود إلى خمسة نتائج على الشبكة URLs و الاستخدام الفعلي. وتتحقق هذه الوظيفة من صحة المدخلات، وتحافظ على نظام النتائج، وتزيل تكراراً للرقم URLs، وتبقي المفتاح خارج البيانات المعادة. The 500-حدّد المُنتجات هو خيار التُطبّق .

search.mjs
// search.mjs — server only; Node.js 22+
export async function searchWeb(query) {
  if (typeof query !== "string" || !query.trim() || query.length > 500) {
    throw Object.assign(new Error("Enter a query of 1–500 characters."), { status: 400 });
  }
  const apiKey = process.env.FLASHDATA_API_KEY;
  if (!apiKey) throw new Error("Set FLASHDATA_API_KEY on the server.");
  let response;
  try {
    response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
      method: "POST", redirect: "error", signal: AbortSignal.timeout(70000),
      headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
      body: JSON.stringify({ source: "google_search", query: query.trim(),
        params: { num: 5, gl: "us", hl: "en" } }),
    });
  } catch {
    throw new Error("Search outcome unknown. Check FlashData History before retrying.");
  }
  if (!response.ok) {
    throw Object.assign(new Error("Search failed: HTTP " + response.status), {
      status: response.status, retryAfter: response.headers.get("retry-after"),
    });
  }
  const data = await response.json();
  if (data.status !== "done" || !Array.isArray(data.results)) {
    throw new Error("Search did not finish. Check FlashData History.");
  }
  const seen = new Set();
  const sources = [];
  for (const [index, item] of (data.results[0]?.organic ?? []).entries()) {
    let url;
    try { url = new URL(item.link); } catch { continue; }
    if (!["https:", "http:"].includes(url.protocol) || seen.has(item.link)) continue;
    seen.add(item.link);
    sources.push({ rank: item.position ?? index + 1, title: item.title ?? item.link,
      url: item.link, snippet: item.snippet ?? "" });
  }
  return { query: query.trim(), sources, usage: data.usage,
    retrievedAt: new Date().toISOString() };
}

2. يضاف الدعم المحلي

انقذوا server.mjs بجانبك search.mjs. GET /search?q=... GET / يخدم الشكل الذي سوف تخلقه بعد ذلك. الخادم يستمع فقط على 127.0.0.1.

server.mjs
// server.mjs — local demo; keep your existing app's authentication in production.
import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import { searchWeb } from "./search.mjs";

createServer(async (req, res) => {
  const url = new URL(req.url, "http://127.0.0.1:8787");
  res.setHeader("Cache-Control", "no-store");
  try {
    if (req.method === "GET" && url.pathname === "/") {
      const html = await readFile(new URL("./index.html", import.meta.url));
      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
      return res.end(html);
    }
    if (req.method !== "GET" || url.pathname !== "/search") {
      res.writeHead(404); return res.end("Not found");
    }
    const result = await searchWeb(url.searchParams.get("q"));
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(result));
  } catch (error) {
    if (error.retryAfter) res.setHeader("Retry-After", error.retryAfter);
    res.writeHead(error.status ?? 502, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: error.message }));
  }
}).listen(8787, "127.0.0.1", () => console.log("Open http://127.0.0.1:8787"));

3. نتائج التلاعب في تطبيقك

انقذوا index.html في نفس الملف ويعالج هذا الشكل التحميل، والنتائج الفارغة، والأخطاء. إنها تنادي بظهرك وتدرج الدمى كنص، لذا لا يصل إلى الصفحة مفتاح API ولا إلى خارج HTML.

index.html
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Web search</title>
<h1>Search the web</h1>
<form id="search">
  <label>Query <input name="q" required maxlength="500" value="battery recycling research"></label>
  <button>Search</button>
</form>
<p id="status" role="status"></p>
<ol id="results"></ol>
<script type="module">
const form = document.querySelector("#search");
const status = document.querySelector("#status");
const results = document.querySelector("#results");
form.addEventListener("submit", async (event) => {
  event.preventDefault();
  form.querySelector("button").disabled = true;
  results.replaceChildren(); status.textContent = "Searching…";
  try {
    const q = new FormData(form).get("q");
    const response = await fetch("/search?q=" + encodeURIComponent(q));
    const data = await response.json();
    if (!response.ok) {
      const retryAfter = response.headers.get("Retry-After");
      throw new Error(data.error + (retryAfter ? " · Retry-After: " + retryAfter : ""));
    }
    for (const source of data.sources) {
      const li = document.createElement("li");
      const link = document.createElement("a");
      link.href = source.url; link.textContent = source.title;
      const excerpt = document.createElement("p");
      excerpt.textContent = source.snippet;
      li.append(link, excerpt); results.append(li);
    }
    const credits = data.usage?.credits ?? "not reported";
    status.textContent = (data.sources.length
      ? data.sources.length + (data.sources.length === 1 ? " source" : " sources")
      : "No matching pages. Try a broader query.") + " · Credits used: " + credits;
  } catch (error) { status.textContent = error.message; }
  finally { form.querySelector("button").disabled = false; }
});
</script>
</html>

4. أجري بحثك الأول

اهرب من "البحث عن البيانات" في المحطة حيث وضعت المفتاح افتح URL ونضغط البحث مرة واحدة. ويُجري كل طلب استفساراً مدفوعاً؛ ولا يُعد فتح الصفحة أو تحرير المدخلات أي إجراء. اوقف الخادم المحلي مع (كاترل + سي) عندما تنتهي

  1. أدخل موضوعاً محدداً، مثل معدلات إعادة تدوير البطاريات.
  2. توقّع عناوين مرتبطة ومقتطفات والرصيد العائد في usage.credits. تختلف النتائج؛ وعدم وجود مصادر نتيجة صالحة لبحث مكتمل.
في الباحثة عن البيانات - ديمو - إبقاء هذه المحطة تعمل
node server.mjs
افتحي فمكِ
http://127.0.0.1:8787

النتيجة التي تلقاها تطبيقك

(أ) الشكل المختصر؛ والرقم القياسي URLs والرقم الوارد أدناه توضيحي. البحث يعيد الدمى و الوصلات استخدم قارئ صفحتك عندما تحتاج سمتك إلى النص الكامل للصفحة

GET /search?q=...
{
  "query": "battery recycling research",
  "sources": [
    {
      "rank": 1,
      "title": "Example source",
      "url": "https://example.org/research",
      "snippet": "A returned search excerpt."
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "retrievedAt": "2026-11-04T00:00:00.000Z"
}

إعادة البحث في أداة عميل

Optional: save search-tool.mjs beside search.mjs. ويقبل الهارب فقط search_web وسؤاله. اصنعوا راكب واحد لكل مهمة وابقوه في طريق نموذج تلك المهمة maxCalls (ب) الحد من محاولات التفتيش، بما في ذلك المحاولات الفاشلة. ولا يحدد حداً للإنفاق على الائتمانات.

flashdata-search-demo/search-tool.mjs
// search-tool.mjs — one runner per task, reused across its model turns.
import { searchWeb } from "./search.mjs";

export const searchTool = {
  name: "search_web",
  description: "Find ranked web URLs and snippets for a focused query.",
  inputSchema: {
    type: "object", additionalProperties: false,
    properties: { query: { type: "string", minLength: 1, maxLength: 500 } },
    required: ["query"],
  },
};
export function createSearchToolRunner({ maxCalls = 2 } = {}) {
  if (!Number.isSafeInteger(maxCalls) || maxCalls < 1) {
    throw new Error("maxCalls must be a positive integer.");
  }
  let attempts = 0;
  return async function runTool(name, args) {
    if (name !== searchTool.name) throw new Error("Unknown tool: " + name);
    if (!args || typeof args !== "object" || Array.isArray(args) ||
        Object.keys(args).some(key => key !== "query") ||
        typeof args.query !== "string" || !args.query.trim() || args.query.length > 500) {
      throw new Error("Expected only query: a string of 1–500 characters.");
    }
    if (attempts >= maxCalls) throw new Error("Search call limit reached for this task.");
    attempts++; // Reserve before awaiting; a failed attempt still counts.
    return searchWeb(args.query);
  };
}

جرب الأداة مباشرة

احفظ tool-demo.mjs في flashdata-search-demo، ثم شغّل الأمر أدناه من ذلك المجلد بمفتاح API نفسه. يجري هذا الفحص الاختياري استعلام FlashData إضافيًا واحدًا دون استدعاء نموذج. توقّع JSON يحوي query وsources وusage وretrievedAt، بالشكل نفسه الذي يعيده النموذج في الصفحة.

flashdata-search-demo/tool-demo.mjs
// tool-demo.mjs — one direct tool call; no model-provider dependency.
import { createSearchToolRunner, searchTool } from "./search-tool.mjs";

if (process.argv.length !== 3) {
  console.error('Usage: node tool-demo.mjs "your search query"');
  process.exit(1);
}
const runTool = createSearchToolRunner({ maxCalls: 1 });
const result = await runTool(searchTool.name, { query: process.argv[2] });
console.log(JSON.stringify(result, null, 2));
تشغيل مرة واحدة من فلاشداتا - سيرك - ديمو
node tool-demo.mjs "battery recycling research"

إربطها بنموذجك

يُمارسُ الطبقاتُ التجريبيةُ مهمةَ الأداةَ. إطارك يزود حلقة الإتصال و الرسائل النموذجية ويعود البحث إلى الوصلات والقناص؛ ويقرأ صفحات مختارة قبل استخدام مضمونها الكامل في إجابة. أما بالنسبة للمهام المستأنفة أو الموزعة، فيستمر العد المحاولات ويسفر عن المهمة ID.

  1. السجل searchTool.nameالوصف inputSchema باستخدام استمارة تحديد أدوات إطارك. حافظ على API المفتاح في البيئة الخلفية
  2. وفي بداية المهمة، يرجى الاتصال برقم createSearchToolRunner({ maxCalls: 2 }). بالنسبة لكل نداء نموذجي، تُسجِّل حججها الخاصة بـ JSON، وتُنقل الاسم والاعتراض المُقَدَّم إلى ذلك الراكب نفسه. الرفض غير صحيح JSON قبل الإرسال.
  3. (أ) إعادة الـ (زكس كيزوك (JSON إلى النموذج كنتيجة للأداة مع النداء الأصلي (ID. Preserve sources[].url for citations. وإذا فشل التنفيذ أو وصل إلى الحد، كرر الخطأ؛ ولا تخلق راكبا جديدا لإعادة فحصه.

الفشل اليدوي وشحنه

عند النشر، ضع /search خلف تسجيل الدخول إلى تطبيقك وحدود كل مستخدم. احتفظ بمفتاح API في إعداد الخادم، وسجّل الاستخدام مع الطلب، واعرض المحتوى الخارجي كنص. يناسب Realtime هذا النموذج التفاعلي؛ واستخدم async للعمل في الخلفية.

الحالةسلوك التطبيق
ERR_MODULE_NOT_FOUND / ENOENTأبقوا جميع الملفات في "مجلة البحّار" وهربوا من ذلك الملف. انقذوا index.html قبل فتح الصفحة.
EADDRINUSEالميناء 8787 مشغولة اوقف عملية اداءك السابقة قبل ان تبدأ عملية اخرى
الحد الأقصى لمكالمة التفتيشاستهلكت المهمة محاولاتها المسموح بها. أنهِ العمل بالأدلة المجموعة أو أبلغ عن الحد؛ فإنشاء برنامج تشغيل جديد سيعيد ضبط العداد.
نتائج فارغةأظهري حالة فارغة ودع المستعمل يصقل الاستفسار ولا تعودي تلقائياً
401 / 403 / 402تحقق من مفتاح الخادم، إذن من شركة google_search وحسابات الائتمان.
429انتظر Retry-After عند تقديم الطلب؛ الحد من الطلبات لكل مستخدم قبل الاتصال FlashData.
الوقت/خطأ الشبكةأظهر نتائج غير مؤكدة Inspect History قبل إرسال نفس السؤال المدفوع مرة أخرى.