# Bir uygulama için arama ekleyin

Bir çalışma arama formu oluşturun, API anahtarını arkanızda tut ve aynı arama fonksiyonunu bir ajan aracında yeniden kullanın.

Canonical referans: https://flashdata.dev/tr/docs/guides/search-in-an-app
İnceleme: 2026-11-05 Tarafından FlashData

<a id="prepare"></a>

## Ne inşa edeceksin

Listelenen bağlantılar, parçalar ve kredi kullanımı ile yerel bir arama formu. Node.js 22+, google_search izni ve mevcut kredilerle bir anahtar. npm paketleri gereklidir. Seçmeli ajan bölümü aynı arka uç fonksiyonunu yeniden kullanır.

| flashdata-search-demo'da Kaydet | Amaç |
| --- | --- |
| search.mjs | FlashData'u arkadan çağırın; form ve ajan aracı tarafından paylaşılan. |
| server.mjs | Yerel sayfa ve GET /search uç noktası servis eder. |
| index.html | Ekran kaynakları, boş sonuçlar ve hatalar. |

### Bash veya PowerShell · proje oluşturmak

```bash
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo
```

- [Uygulamayı çalıştırın](https://flashdata.dev/tr/docs/guides/search-in-an-app/reference.md#output)
- [Bir ajandadaki işlevi kullanın](https://flashdata.dev/tr/docs/guides/search-in-an-app/reference.md#tool)
- [API'a yeni mi?](https://flashdata.dev/tr/docs/guides/http-quickstart/reference.md)

<a id="authenticate"></a>

### API anahtarını ayarlayın

Reuse FLASHDATA_API_KEY zaten ayarlandığında. Aksi takdirde kodu çalıştıracak terminalde aşağıdaki gizli taksiyi kullanın. Bir ajan gizli mağazasından aynı değişkeni yükleyebilir.

#### Bash

##### Anahtarı ayarlayın

```bash
# 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
```


#### PowerShell 7

##### Anahtarı ayarlayın

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [API anahtarları](https://flashdata.dev/app/api-keys)
- [Ajan denemesi ve hesap bağlama](https://flashdata.dev/tr/docs/guides/agent-onboarding/reference.md)

<a id="run"></a>

## 1. Arama fonksiyonunu oluşturun

search.mjs olarak proje klasörünüzde tasarruf edin. Bir çağrı beş web sonuçlarına geri döner, URLs ve gerçek kullanımları. İşlev girişini doğrular, sonuç siparişini korur, URLs'u tekrarlar ve geri dönen verilerin anahtarı tutar. 500-character limiti bir uygulama seçimidir.

### search.mjs

```javascript
// 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() };
}
```


<a id="endpoint"></a>

## 2. Yerel bir geri dönüş ekleyin

server.mjs'un yanında search.mjs olarak tasarruf edin. GET /search?q=... işlevi çağırır; GET / bir sonraki yaratacağınız formda hizmet eder. Sunucu sadece 127.0.0.1'da dinliyor.

### server.mjs

```javascript
// 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"));
```


<a id="display"></a>

## 3. Uygulamanızda Ekran sonuçları

Aynı klasörde index.html olarak tasarruf edin. Bu form yükleme, boş sonuçlar ve hatalarla ilgilidir. Geri dönüşlerinizi ve parçalarınızı metin olarak adlandırıyor, bu yüzden API anahtarı ne de dış HTML sayfaya ulaşıyor.

### index.html

```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>
```


<a id="output"></a>

## 4. İlk aramanızı çalıştırın

Anahtarı belirlediğiniz terminalde flaşda arama-demo'dan hareket edin. URL'u açın ve bir kez Search'e tıklayın. Her bir teklif ücretli bir sorgu yapar; sayfayı açın veya girişin düzenlenmesi hiçbir şey yapmaz. Tamamlandığında yerel sunucuyu durdurun.

1. Belirli bir konu girin, batarya geri dönüşüm oranları gibi.
2. Tanık başlıklar, parçalar ve krediler usage.credits'da geri döndü. Sonuçlar değişir; sıfır kaynaklar geçerli tamamlanmış bir aramadır.

### Flashdatasearch-demo · Bu terminali çalıştırmaya devam edin

```bash
node server.mjs
```

### Tarayıcınızda açık

```text
http://127.0.0.1:8787
```

- [İlişkiyi geliştirmek](https://flashdata.dev/tr/docs/guides/google-search-guide/reference.md)
- [Check request date](https://flashdata.dev/app/jobs)

<a id="expected"></a>

### Sonuç uygulamanızın aldığı sonuç

Abbreviated şekli; URLs ve aşağıdaki kullanımlar açıklayıcıdır. Bir arama parçaları ve bağlantıları döndürür. özelliğinizin tam sayfa metnine ihtiyaç duyduğunda bir sayfa okuyucuyu kullanın.

#### GET /search?q=...

```json
{
  "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"
}
```


<a id="tool"></a>

## Bir ajan aracında Yeniden arama

Seçmeli: search-tool.mjs'u search.mjs'nun yanında kurtarın. koşucu sadece search_web ve onun sorguyu kabul ediyor. Görev başına bir koşucu oluşturun ve bu görevin modeline devam edin; maxCalls limitleri başarısız girişimler de dahil olmak üzere aramalar denedi. Bir kredi harcama limiti ayarlamaz.

### flashdata-search-demo/search-tool.mjs

```javascript
// 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);
  };
}
```

- [Aracı doğrudan deneyin](https://flashdata.dev/tr/docs/guides/search-in-an-app/reference.md#tool-test)
- [Modelinizi Bağlayın](https://flashdata.dev/tr/docs/guides/search-in-an-app/reference.md#model-loop)
- [Zaten bir MCP host kullanıyor mu?](https://flashdata.dev/tr/docs/integrations/mcp-clients/reference.md)

<a id="tool-test"></a>

### Aracı doğrudan deneyin

tool-demo.mjs'u flashdata-search-demo'da kurtarın, o klasörden aynı API anahtarı ile kumandan. Bu Seçmeli kontrol, bir model aramadan bir FlashData sorgu yapar. JSON'u sorgu, kaynaklar, kullanım ve retrievedAt ile bekleyin - aynı sonuç şekli olarak.

#### flashdata-search-demo/tool-demo.mjs

```javascript
// 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));
```

#### Bir kez flaşdata-search-demo

```bash
node tool-demo.mjs "battery recycling research"
```


<a id="model-loop"></a>

### Onu modelinize bağlayın

demo, araç fonksiyonunu öğretir. Çerçeveniz model bağlantı ve mesaj döngüsü sağlar. Arama bağlantıları ve parçaları döndürür; bir cevapta tam içeriklerini kullanmadan önce seçilmiş sayfaları okuyun. özgeçmiş veya dağıtılmış görevler için, girişim sayısını ve sonuçları ID ile devam ettirin.

1. Kayıt searchTool.name, açıklama ve inputSchema framework'in araç-tafinans formatını kullanarak. API anahtarını arka uç ortamda tut.
2. Görev başlangıcında, createSearchToolRunner({ maxCalls: 2 }) arayın. Her model araç çağrısı için, JSON argümanlarını parlayın ve adını ve aynı koşucuya itiraz edin. Reject, JSON'u önceden devre dışı bıraktı.
3. JSON sonucu, orijinal çağrı ID ile bir araç sonucu olarak modele döndürür. sources[].url'u alıntılar için koruyun. Eğer infaz başarısız olursa veya sınıra ulaşırsa, hatayı döndürür; yeniden denemesi için yeni bir koşucu yaratmaz.

- [Görev kayıtlarının Yeniden Alınması](https://flashdata.dev/tr/docs/guides/recurring-tasks/reference.md)
- [Bağlamalarla Araştırma](https://flashdata.dev/tr/docs/guides/google-youtube-research/reference.md)

<a id="verify"></a>

## Başarısızlık ve gemile

Dağıtım için, uygulamanızın işaretinin ve kullanıcı sınırlarınızın arkasındaki /search'u hareket ettirin. API anahtarını sunucu yapılandırmasında tutun, istekle kullanın ve metin olarak dış içerik sağlayın. Realtime bu interaktif form için uygundur; arka plan çalışması için birsen kullanın.

| Durum durumu | App davranışı |
| --- | --- |
| ERR_MODULE_NOT_FOUND / ENOENT | Flashdata-search-demo'daki tüm dosyaları tut ve bu klasörden çalıştırın. Sayfayı açmadan önce index.html'u kurtarın. |
| EADDRINUSE | Port 8787 meşgul. Daha önceki demo sürecinizi başka bir başlangıç yapmadan durdurun. |
| Arama çağrısı limiti ulaştı | Görev izin verilen girişimleri kullandı. Toplanan kanıtlarla bitirin veya sınırı rapor edin; yeni bir koşucu oluşturmak, sayıyı sıfırlayacaktı. |
| Boş sonuçlar | Boş bir devlet göster ve kullanıcının sorguyu düzeltmesine izin verin; otomatik olarak yeniden denemeyin. |
| 401 / 403 / 402 | Sunucu anahtarını kontrol edin, google_search izin ve hesap kredilerini kontrol edin. |
| 429 | Retry-After için bekleyin; FlashData aramadan önce kullanıcı başına limit talepler. |
| Timeout / ağ hatası | belirsiz bir sonuç göster. Inspect History, aynı ücretli sorguyu tekrar göndermeden önce. |

- [Realtime veya birsen?](https://flashdata.dev/tr/docs/reference/realtime-and-async/reference.md#choose)
- [Batch istekleri](https://flashdata.dev/tr/docs/reference/batch-and-bulk/reference.md#batch)
- [Hata kodları ve retries](https://flashdata.dev/tr/docs/errors/reference.md#retries)
- [Prodüksiyon dağıtım](https://flashdata.dev/tr/docs/guides/production-deployment/reference.md)
