Semak dokumentasi
Mula di sini
biaya pemeriksaan , menyimpan catatan setiap percobaan dan membaca hasil yang disimpan tanpa panggilan API lain.
Pada halaman ini
Sebelum kau mulai
Guna proyek tersebut, terpasang SDK dan FLASHDATA_API_KEY dari SDK quickstart anda. Pilih satu bahasa di bawah ini. Setiap direktori run baru mewakili satu pencarian yang dimaksudkan; menggunakan kembali direktori yang ada berhenti sebelum membuat permintaan apapun.
1. Periksa akses dan biaya saat ini
Simpan dan jalankan cek untuk SDK. Ia membaca izin, keseimbangan dan harga satu Google Search. Hanya dilanjutkan setelah pemeriksaan Access lulus; pemeriksaan ini tidak mengajukan kredit kueri atau cadangan yang telah dibayar.
import os
import sys
from flashdata import FlashData, APIError
def main():
key = os.environ.get("FLASHDATA_API_KEY", "").strip()
if not key:
raise RuntimeError("Set FLASHDATA_API_KEY in this terminal.")
with FlashData(api_key=key) as client:
access = client.account.access()
if "google_search" not in access["sources"]:
raise RuntimeError("This key needs google_search permission.")
balance = client.account.balance()
pricing = client.account.pricing(source="google_search", request_count=1)
price = next((p for p in pricing["prices"]
if p["source"] == "google_search" and p["available"]), None)
cost = price.get("estimatedCredits") if price else None
if cost is None:
raise RuntimeError("No current price is available; stop here.")
available = balance["availableCredits"]
print(f"Available credits: {available}")
print(f"One search: {cost} credits")
if available < cost:
raise RuntimeError("Insufficient credits. Review Billing.")
print("Access check passed. No paid query submitted.")
if __name__ == "__main__":
try:
main()
except APIError as error:
print(f"HTTP {error.status_code}; code={error.code}; "
f"request_id={error.request_id}; Retry-After={error.retry_after}",
file=sys.stderr)
sys.exit(1)
except Exception as error:
print(f"{type(error).__name__}: {error}", file=sys.stderr)
sys.exit(1).venv/bin/python check_access.py.\.venv\Scripts\python.exe check_access.pyimport { FlashData, APIError } from '@flashdata-dev/sdk';
try {
const apiKey = process.env.FLASHDATA_API_KEY?.trim();
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY in this terminal.');
const client = new FlashData({ apiKey });
const access = await client.account.access();
if (!access.sources.includes('google_search')) {
throw new Error('This key needs google_search permission.');
}
const balance = await client.account.balance();
const pricing = await client.account.pricing({ source: 'google_search', request_count: 1 });
const price = pricing.prices.find(p => p.source === 'google_search' && p.available);
const cost = price?.estimatedCredits;
if (cost == null) throw new Error('No current price is available; stop here.');
console.log('Available credits:', balance.availableCredits);
console.log('One search:', cost, 'credits');
if (balance.availableCredits < cost) throw new Error('Insufficient credits. Review Billing.');
console.log('Access check passed. No paid query submitted.');
} catch (error) {
if (error instanceof APIError) {
console.error('HTTP', error.statusCode, 'code:', error.code,
'request_id:', error.requestId, 'Retry-After:', error.retryAfter);
} else {
console.error(error instanceof Error ? error.message : String(error));
}
process.exitCode = 1;
}node check-access.mjsBuat cmd/check dan simpan berkas ini disana.
package main
import (
"context"
"fmt"
"log"
"os"
"slices"
"time"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
key := os.Getenv("FLASHDATA_API_KEY")
if key == "" {
log.Fatal("Set FLASHDATA_API_KEY in this terminal.")
}
client, err := flashdata.New(flashdata.Options{APIKey: key})
if err != nil {
log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
identity, err := client.Account.Identity(ctx)
if err != nil {
log.Fatal(err)
}
if identity.Access != "ready" || !slices.Contains(identity.Scopes, flashdata.SourceGoogleSearch) {
log.Fatal("This key is not ready for google_search. Check its status and permissions.")
}
balance, err := client.Account.Balance(ctx)
if err != nil {
log.Fatal(err)
}
pricing, err := client.Account.Pricing(ctx, flashdata.PricingParams{
Source: flashdata.SourceGoogleSearch, RequestCount: 1,
})
if err != nil {
log.Fatal(err)
}
if len(pricing.Prices) != 1 || pricing.Prices[0].Source != "google_search" ||
!pricing.Prices[0].Available || pricing.Prices[0].EstimatedCredits == nil {
log.Fatal("A current Google Search price is unavailable. Do not submit yet.")
}
cost := *pricing.Prices[0].EstimatedCredits
fmt.Printf("Account: %s (%s)\n", identity.AccountID, identity.AccountType)
fmt.Printf("Available credits: %g\nOne search: %g credits\n", balance.AvailableCredits, cost)
if balance.AvailableCredits < cost {
log.Fatal("Insufficient credits. Check Billing or claim existing trial access.")
}
fmt.Println("Access check passed. No paid query submitted.")
}go run ./cmd/check2. Jalankan dengan direktori output baru
Jalankan salah satu program ini setelah pemeriksaan lulus. Ini menciptakan direktori sebelum mengajukan, mencatat permintaan, kemudian menyimpan respon. Simpan direktori pada kegagalan: menghapusnya atau memilih yang baru memungkinkan pertanyaan yang dapat diagihkan lagi.
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from flashdata import FlashData, APIError, SubmissionUnknownError
def main():
key = os.environ.get("FLASHDATA_API_KEY", "").strip()
if not key:
raise RuntimeError("Set FLASHDATA_API_KEY before running.")
directory = Path(sys.argv[1] if len(sys.argv) > 1 else "runs/research-001")
directory.mkdir(mode=0o700, parents=True, exist_ok=False)
def save(name, value):
with (directory / name).open("x", encoding="utf-8") as output:
json.dump(value, output, ensure_ascii=False, indent=2)
request = {"source": "google_search", "query": "battery recycling research",
"params": {"num": 5}}
save("request.json", request)
save("intent.json", {"state": "dispatching",
"startedAt": datetime.now(timezone.utc).isoformat()})
try:
with FlashData(api_key=key) as client:
response = client.google.search(request["query"], **request["params"])
except (APIError, SubmissionUnknownError) as error:
detail = {"kind": type(error).__name__}
if isinstance(error, APIError):
detail.update(code=error.code, httpStatus=error.status_code,
requestId=error.request_id, retryAfter=error.retry_after)
save("error.json", detail)
raise RuntimeError("Inspect the saved attempt and History before retrying.") from None
save("result.json", response)
if response.get("status") != "done":
raise RuntimeError("Response saved; inspect its status before proceeding.")
print("Saved:", directory / "result.json")
print("Usage:", response.get("usage"))
if __name__ == "__main__":
try:
main()
except Exception as error:
print(f"{type(error).__name__}: {error}", file=sys.stderr)
sys.exit(1).venv/bin/python archive_search.py runs/research-001.\.venv\Scripts\python.exe archive_search.py runs/research-001Simpan program ESM Node ini dalam baik dalam proyek JavaScript atau TypeScript. Ini menggunakan paket @flashdata-dev/sdk terpasang yang sama.
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { FlashData, APIError, SubmissionUnknownError } from '@flashdata-dev/sdk';
try {
const apiKey = process.env.FLASHDATA_API_KEY?.trim();
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY before running.');
const directory = process.argv[2] || 'runs/research-001';
await mkdir(dirname(directory), { recursive: true });
await mkdir(directory, { mode: 0o700 }); // Existing attempt: stop before any API call.
const save = (name, value) => writeFile(join(directory, name),
JSON.stringify(value, null, 2), { flag: 'wx', mode: 0o600 });
const request = { source: 'google_search', query: 'battery recycling research',
params: { num: 5 } };
await save('request.json', request);
await save('intent.json', { state: 'dispatching', startedAt: new Date().toISOString() });
const client = new FlashData({ apiKey });
let response;
try {
response = await client.google.search({ query: request.query, ...request.params });
} catch (error) {
const detail = { kind: error instanceof SubmissionUnknownError
? 'SubmissionUnknownError' : error instanceof APIError ? 'APIError' : 'ClientError' };
if (error instanceof APIError) Object.assign(detail, {
code: error.code, httpStatus: error.statusCode,
requestId: error.requestId, retryAfter: error.retryAfter,
});
await save('error.json', detail);
throw new Error('Inspect the saved attempt and History before retrying.');
}
await save('result.json', response);
if (response.status !== 'done') throw new Error('Response saved; inspect its status.');
console.log('Saved:', join(directory, 'result.json'));
console.log('Usage:', response.usage);
} catch (error) {
console.error(error instanceof Error ? error.message : 'Inspect this attempt.');
process.exitCode = 1;
}node archive-search.mjs runs/research-001Buat cmd/archive sehingga titik masukan ini tetap terpisah dari program Quickstart anda.
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"time"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
func run() error {
key := os.Getenv("FLASHDATA_API_KEY")
if key == "" { return errors.New("set FLASHDATA_API_KEY before running") }
directory := "runs/research-001"
if len(os.Args) > 1 { directory = os.Args[1] }
if err := os.MkdirAll(filepath.Dir(directory), 0700); err != nil { return err }
if err := os.Mkdir(directory, 0700); err != nil { return err }
save := func(name string, value any) error {
file, err := os.OpenFile(filepath.Join(directory, name), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
if err != nil { return err }
err = json.NewEncoder(file).Encode(value)
closeErr := file.Close()
if err != nil { return err }
return closeErr
}
query := flashdata.GoogleSearchInput{Query: "battery recycling research",
Params: &flashdata.GoogleSearchParams{Num: flashdata.Ptr(int64(5))}}
if err := save("request.json", map[string]any{"source": "google_search",
"query": query.Query, "params": query.Params}); err != nil { return err }
if err := save("intent.json", map[string]string{"state": "dispatching",
"startedAt": time.Now().UTC().Format(time.RFC3339)}); err != nil { return err }
client, err := flashdata.New(flashdata.Options{APIKey: key})
if err != nil { return err }
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
result, err := client.Google.Search(ctx, query)
if err != nil {
detail := map[string]any{"kind": "ClientError"}
var api *flashdata.APIError
var unknown *flashdata.SubmissionUnknownError
if errors.As(err, &api) {
detail = map[string]any{"kind": "APIError", "code": api.Code,
"httpStatus": api.StatusCode, "requestId": api.RequestID, "retryAfter": api.RetryAfter}
} else if errors.As(err, &unknown) { detail["kind"] = "SubmissionUnknownError" }
if saveErr := save("error.json", detail); saveErr != nil { return saveErr }
return errors.New("inspect the saved attempt and History before retrying")
}
if err := save("result.json", result); err != nil { return err }
if result.Status != "done" { return errors.New("response saved; inspect its status") }
fmt.Printf("Saved: %s\nUsage: %+v\n", filepath.Join(directory, "result.json"), result.Usage)
return nil
}go run ./cmd/archive runs/research-001Semua berkas yang diharapkan
Kejayaan mencetak jalur dan penggunaan hasil yang disimpan. result.json harus memiliki status: done; Hasil Google berada di results[].organic[]. Sebuah susunan organik kosong adalah valid. Sebuah API yang dilaporkan atau kesalahan transportasi disimpan ke error.json; intent.json tetap merupakan catatan awal pengiriman.
runs/research-001/
request.json Sumber, pertanyaan dan parameter
intent.json Mencoba waktu mulai percobaan
XAresult.json # Respon penuh, termasuk hasil dan penggunaan3. Keluaran tersimpan Read Kebocoran
Kemudia baca result.json untuk parsing, summaries dan UI kerja. Perintah-perintah ini hanya menggunakan berkas lokal. Alokasi ulang pencarian dengan stop direktori yang sama sebelum panggilan jaringan; tidak berkoordinasi dengan mesin yang berbeda atau memulihkan respon server yang hilang.
cat runs/research-001/result.jsonGet-Content -Raw -LiteralPath './runs/research-001/result.json'Buat cmd/read dan simpan dekoder ini di sana. Ia membaca berkas dan mencetak judul sumber dan URLs tanpa membangun klien atau membuat permintaan API.
package main
import (
"encoding/json"
"fmt"
"log"
"os"
flashdata "github.com/flashdatadev/flashdata-go"
)
func main() {
filename := "runs/research-001/result.json"
if len(os.Args) > 1 { filename = os.Args[1] }
data, err := os.ReadFile(filename)
if err != nil { log.Fatal(err) }
var result flashdata.DataQueryResponse
if err := json.Unmarshal(data, &result); err != nil { log.Fatal(err) }
if result.Source != "google_search" || result.Status != "done" {
log.Fatal("Expected a completed Google Search response")
}
pages, err := flashdata.DecodeResults[flashdata.GoogleSearchPayload](&result)
if err != nil { log.Fatal(err) }
for _, page := range pages {
for _, hit := range page.Organic {
if hit.Title != nil && hit.Link != nil { fmt.Println(*hit.Title, *hit.Link) }
}
}
fmt.Printf("Original query credits: %g\n", result.Usage.Credits)
}go run ./cmd/read runs/research-001/result.jsonMemutuskan apa yang harus dilakukan setelah kegagalan
| Apa yang Anda miliki | Tindakan berikutnya |
|---|---|
| Direktori / EEXIST Terwujud | Periksa berkasnya. Tidak ada pertanyaan baru yang dikirim oleh upaya ini. |
| result.json, status: done | Baca dan proses respon yang disimpan. Reacuuse penggunaannya sebagai penerimaan dari muatan asli. |
| error.json dengan 401 / 403 / 402 | Fix akses, hak sumber atau keseimbangan sebelum merencanakan upaya baru. |
| 429 / retryAfter | - Tunggu seperti yang diperintahkan dan kurangi nilai permintaan. Tinjau upaya gagal sebelum memilih direktori lari baru. |
| Pengiriman / niatan hanya / gagal menulis tidak diketahui | Pekerjaan kinologi mungkin sudah diterima. ¡Keep the directory and inspect History atau pekerjaan yang diketahui IDQ sebelum mengirim pertanyaan lain. |
Klien Async dan pekerjaan latar belakang
| Perlunya Kebutuhan | Guna |
|---|---|
| ULANGLAHLAH agar lingkaran acara tanggap | SDK's async client / menunggu panggilan. Sebuah pertanyaan realtime masih lengkap dalam respon HTTP. |
| Kembali setelah proses pemanggilan keluar | Berikan pekerjaan latar belakang sekali, simpan remote ID, lalu baca status dan hasilnya. |
| Jalankan mengikut jadual | Guna akses pemilik dan aplikasi tahan lama menjalankan catatan, atau jurnal jangka CLI yang sudah ada. |