Chuyển đến nội dung
VI
Lấy khóa API
Duyệt tài liệu

Hướng dẫn

Thêm tìm kiếm vào ứng dụng

Xây dựng một hình thức tìm kiếm làm việc, giữ API Chìa khóa trên backend của bạn, và sử dụng lại chức năng tìm kiếm tương tự trong một công cụ tác nhân.

Trên trang này

Những gì bạn sẽ xây dựng

Một đơn tìm kiếm cục bộ với các liên kết xếp hạng, trích đoạn và sử dụng tín dụng. Yêu cầu Node.js 22+, một phím với google_search Cho phép và tín dụng sẵn có. Không cần gói npm. Phần tác nhân tùy chọn tái sử dụng chức năng backend tương tự.

Lưu vào tự động kiểm tra dữ liệuMục đích
search.mjsCuộc gọi FlashData từ backend, được chia sẻ bởi hình thức và công cụ tác nhân.
server.mjsPhục vụ trang địa phương và GET /search điểm cuối.
index.htmlHiển thị nguồn, kết quả và lỗi trống.
Bash hay PowerShell * Tạo ra dự án
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Đặt khóa API

Dùng lại FLASHDATA_API_KEY nếu đã cài đặt. Nếu không, hãy dùng dấu nhắc ẩn bên dưới trong thiết bị cuối để chạy mã. Một tác nhân có thể tải cùng một biến số từ cửa hàng bí mật của nó.

Đặt phím
# 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. Tạo hàm tìm kiếm

Lưu dạng search.mjs trong thư mục dự án của anh. Một cuộc gọi trở lại kết quả năm trang web, của họ URLs và sử dụng thực tế. Hàm xác nhận nhập, bảo tồn thứ tự kết quả, loại bỏ bản sao URLs Và giữ chìa khóa trong dữ liệu được trả lại. Hạt 500- Giới hạn từ xa là lựa chọn ứng dụng.

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. Thêm một backend cục bộ

Lưu dạng server.mjs bên cạnh search.mjs. GET /search?q=... gọi hàm; GET / phục vụ hình thức bạn sẽ tạo ra tiếp theo. Máy phục vụ chỉ lắng nghe 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. Hiển thị kết quả trong ứng dụng của bạn

Lưu dạng index.html trong cùng một thư mục. Hình thức này xử lý tải, kết quả và lỗi trống. Nó gọi backend của bạn và chèn các trích đoạn là văn bản, vì vậy cả hai API Phím cũng không phải bên ngoài HTML đến trang đó.

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. Chạy tìm kiếm đầu tiên

Chạy từ đèn flashdata-demo trong thiết bị cuối nơi bạn đặt chìa khóa. Mở URL và click Tìm kiếm một lần. Mỗi đệ trình cung cấp một yêu cầu được trả tiền; mở trang hoặc sửa đổi dữ liệu nhập vào thì không làm gì. Dừng máy phục vụ cục bộ bằng Ctrl+C khi hoàn tất.

  1. Nhập một chủ đề cụ thể, chẳng hạn như tỷ lệ phục hồi lại pin.
  2. Mong đợi các tiêu đề liên kết, trích đoạn và các tín dụng được trả lại ở usage.credits. Kết quả khác nhau; không nguồn nào là một tìm kiếm hoàn tất hợp lệ.
Trong flashdata-demo # giữ cho thiết bị cuối này hoạt động
node server.mjs
Mở trong trình duyệt
http://127.0.0.1:8787

Kết quả ứng dụng của bạn nhận được

Hình dạng đã được viết tắt; URLs và sử dụng bên dưới là hình ảnh hoá. Tìm kiếm các đoạn trích và liên kết. Dùng độc giả trang khi tính năng của bạn cần toàn bộ câu Kinh Thánh.

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

Dùng lại tìm kiếm trong một công cụ tác vụ

Tùy chọn: search-tool.mjs bên cạnh search.mjs. Người chạy đua chỉ chấp nhận search_web và câu hỏi của nó. Tạo ra một người chạy mỗi nhiệm vụ và giữ cho nó trên các mô hình chuyển đổi của nhiệm vụ; maxCalls giới hạn cố tìm kiếm, bao gồm việc cố gắng thất bại. Nó không đặt ra giới hạn tín dụng.

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);
  };
}

Thử trực tiếp công cụ

Lưu tool-demo.mjs trong flashdata-demo, sau đó chạy lệnh bên dưới thư mục đó với cùng một lệnh API Chìa khóa. Kiểm tra này tùy chọn làm cho thêm một bổ sung FlashData Hỏi mà không gọi người mẫu. Mong đợi JSON với truy vấn, nguồn, sử dụng và retrievedAt- cùng hình dạng với hình dạng.

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));
Chạy một lần từ flashdata-emo
node tool-demo.mjs "battery recycling research"

Kết nối nó với mô hình của bạn

Các bản thử nghiệm các chức năng công cụ. Cơ sở của bạn cung cấp cho các mô hình kết nối và thông điệp. Tìm kiếm liên kết trở lại và trích đoạn; đọc các trang đã chọn trước khi dùng nội dung đầy đủ của chúng để trả lời. Để tiếp tục hoặc phân phối, hãy kiên trì kiểm tra và kết quả công việc ID.

  1. Đăng ký searchTool.name, mô tả và inputSchema bằng cách sử dụng định dạng xác định công cụ của bạn. Giữ lại API Chìa khóa trong môi trường backend.
  2. Bắt đầu nhiệm vụ, gọi createSearchToolRunner({ maxCalls: 2 }). Đối với mỗi mô hình công cụ gọi, phân tích của nó JSON tham số và chuyển tên và phân tích đối tượng cho cùng một người chạy. Từ chối không hợp lệ JSON trước khi gửi thông điệp.
  3. Trả lại JSON kết quả cho mô hình như là một kết quả công cụ với cuộc gọi gốc ID. Bảo tồn sources[].url cho những câu trích dẫn. Nếu việc thực hiện bị lỗi hoặc đạt đến giới hạn, hãy trả lại lỗi; đừng tạo một trình chạy mới để thử lại nó.

Xử lý thất bại và vận chuyển nó

Để triển khai, đi /search đằng sau giới hạn đăng ký và người truy cập của cô. Giữ lại API Phím trong cấu hình máy phục vụ, giữ lại sử dụng với yêu cầu và giải quyết nội dung bên ngoài dạng văn bản. Realtime là phù hợp với hình thức tương tác này; sử dụng mộtsync cho công việc nền.

Tình trạngỨng xử thích hợp
ERR_MODULE_NOT_FOUND / ENOENTGiữ mọi tập tin trong thư mục tìm kiếm nhanh và chạy từ thư mục đó. Lưu index.html trước khi mở trang này.
EADDRINUSECổng 8787 đã bị chiếm. Dừng quá trình thử nghiệm trước đó trước khi bắt đầu một quy trình khác.
Tới hạn cuộc gọiCông việc này đã dùng những nỗ lực của nó. Kết thúc với các bằng chứng thu thập hoặc báo cáo giới hạn; tạo ra một người chạy đua mới sẽ khởi động lại số đếm.
Kết quả trốngHiển thị một trạng thái trống và cho phép người dùng tinh luyện các yêu cầu; đừng thử lại tự động.
401 / 403 / 402Kiểm tra khóa máy chủ, google_search Cho phép và tài khoản.
429Đợi Retry-After khi được cung cấp; giới hạn yêu cầu mỗi người dùng trước khi gọi FlashData.
Lỗi quá giờ/ mạngHãy cho thấy một kết quả không chắc chắn. Kiểm tra History Trước khi gửi cùng một truy vấn được trả tiền.