Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

Ajouter la recherche à une application

Créez un formulaire de recherche fonctionnel, gardez la clé API sur votre serveur et réutilisez la même fonction dans un outil d’agent.

Sur cette page

Ce que vous allez créer

Un formulaire de recherche local avec des liens classés, des extraits et la consommation de crédits. Nécessite Node.js 22+, une clé disposant de la permission google_search et des crédits disponibles. Aucun package npm n’est nécessaire. La section facultative sur les agents réutilise la même fonction serveur.

Fichier à enregistrer dans flashdata-search-demoRôle
search.mjsAppelle FlashData côté serveur ; utilisé par le formulaire et l’outil d’agent.
server.mjsSert la page locale et l’endpoint GET /search.
index.htmlAffiche les sources, les résultats vides et les erreurs.
Bash ou PowerShell · créer le projet
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Définir votre clé API

Réutilisez FLASHDATA_API_KEY si elle est déjà définie. Sinon, utilisez la saisie masquée ci-dessous dans le terminal qui exécutera le code. Un agent peut charger cette même variable depuis son stockage de secrets.

Définir la clé
# 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. Créer la fonction de recherche

Enregistrez le code dans search.mjs, dans le dossier du projet. Un appel renvoie jusqu’à cinq résultats web, leurs URL et la consommation réelle. La fonction valide la saisie, préserve l’ordre des résultats, supprime les URL en double et exclut la clé des données renvoyées. La limite de 500 caractères est un choix propre à cette application.

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. Ajouter un serveur local

Enregistrez le code dans server.mjs, à côté de search.mjs. GET /search?q=... appelle la fonction ; GET / sert le formulaire que vous allez créer ensuite. Le serveur écoute uniquement sur 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. Afficher les résultats dans votre application

Enregistrez le code dans index.html, dans le même dossier. Ce formulaire gère le chargement, les résultats vides et les erreurs. Il appelle votre serveur et insère les extraits sous forme de texte : ni la clé API ni du HTML externe ne sont transmis à la page.

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. Lancer votre première recherche

Depuis flashdata-search-demo, utilisez le terminal dans lequel vous avez défini la clé. Ouvrez l’URL et cliquez une fois sur Search. Chaque envoi déclenche une requête payante ; ouvrir la page ou modifier la saisie n’en déclenche aucune. Arrêtez le serveur local avec Ctrl+C lorsque vous avez terminé.

  1. Saisissez un sujet précis, par exemple les taux de récupération des matériaux lors du recyclage des batteries.
  2. Vous devez voir des titres cliquables, des extraits et les crédits renvoyés dans usage.credits. Les résultats varient ; une recherche terminée sans source est un résultat valide.
Dans flashdata-search-demo · laisser ce terminal ouvert
node server.mjs
Ouvrir dans votre navigateur
http://127.0.0.1:8787

Résultat reçu par votre application

Structure abrégée ; les URL et la consommation ci-dessous sont illustratives. Une recherche renvoie des extraits et des liens. Utilisez un outil de lecture de pages si votre fonctionnalité nécessite leur texte complet.

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

Réutiliser la recherche dans un outil d’agent

Facultatif : enregistrez search-tool.mjs à côté de search.mjs. L’exécuteur accepte uniquement search_web et son paramètre query. Créez un exécuteur par tâche et conservez-le entre les échanges de cette tâche avec le modèle ; maxCalls limite les tentatives de recherche, y compris celles en échec. Il ne définit pas de plafond de dépenses en crédits.

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

Tester directement l’outil

Enregistrez tool-demo.mjs dans flashdata-search-demo, puis lancez la commande ci-dessous depuis ce dossier avec la même clé API. Cette vérification facultative effectue une requête FlashData supplémentaire sans appeler de modèle. Le JSON attendu contient query, sources, usage et retrievedAt, comme le résultat du formulaire.

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));
Exécuter une fois depuis flashdata-search-demo
node tool-demo.mjs "battery recycling research"

Connecter l’outil à votre modèle

La démonstration teste la fonction de l’outil. Votre framework fournit la connexion au modèle et la boucle de messages. La recherche renvoie des liens et des extraits ; lisez les pages sélectionnées avant d’utiliser leur contenu complet dans une réponse. Pour les tâches reprises ou distribuées, conservez le nombre de tentatives et les résultats avec l’identifiant de tâche.

  1. Enregistrez searchTool.name, description et inputSchema selon le format de définition d’outils de votre framework. Gardez la clé API dans l’environnement du serveur.
  2. Au début de la tâche, appelez createSearchToolRunner({ maxCalls: 2 }). Pour chaque appel d’outil du modèle, analysez ses arguments JSON et transmettez le nom de l’outil et l’objet obtenu à ce même exécuteur. Rejetez tout JSON invalide avant l’appel.
  3. Renvoyez le JSON au modèle comme résultat d’outil, avec l’identifiant d’appel d’origine. Préservez sources[].url pour les citations. En cas d’échec ou de limite atteinte, renvoyez l’erreur ; ne créez pas de nouvel exécuteur pour réessayer.

Gérer les erreurs et déployer

Pour le déploiement, protégez /search avec l’authentification et les limites par utilisateur de votre application. Gardez la clé API dans la configuration du serveur, conservez la consommation avec la requête et affichez le contenu externe sous forme de texte. Le mode temps réel convient à ce formulaire interactif ; utilisez le mode asynchrone pour les tâches en arrière-plan.

SituationComportement de l’application
ERR_MODULE_NOT_FOUND / ENOENTConservez tous les fichiers dans flashdata-search-demo et exécutez les commandes depuis ce dossier. Enregistrez index.html avant d’ouvrir la page.
EADDRINUSELe port 8787 est occupé. Arrêtez le processus de démonstration précédent avant d’en lancer un autre.
Limite d’appels de recherche atteinteLa tâche a utilisé toutes ses tentatives autorisées. Terminez avec les éléments recueillis ou signalez la limite ; créer un nouvel exécuteur remettrait le compteur à zéro.
Résultats videsAffichez l’absence de résultats et laissez l’utilisateur affiner sa requête ; ne réessayez pas automatiquement.
401 / 403 / 402Vérifiez la clé du serveur, la permission google_search et les crédits du compte.
429Respectez Retry-After lorsqu’il est fourni ; limitez les requêtes par utilisateur avant d’appeler FlashData.
Délai dépassé / erreur réseauSignalez que le résultat est incertain. Consultez History avant d’envoyer à nouveau la même requête payante.