تصفح الوثائق
البدء
تحقق من التكلفة، والاحتفاظ بسجل لكل محاولة وقراءة النتائج المحفوظة دون اتصال آخر من API.
في هذه الصفحة
قبل أن تبدأ
استخدام المشروع، المركب SDK و FLASHDATA_API_KEY من SDK أسرع. اختر لغة واحدة أدناه. ويمثِّل كل دليل جديد للبحث المقصود؛ ويتوقف استخدام الدليل الحالي قبل تقديم أي طلب.
1. الوصول إلى السجلات والتكلفة الحالية
انقذوا و اديروا الشيك من اجلكم SDK. ويقرأ الأذون والرصيد وسعر واحد من طراز Google Search. ولا تستمر إلا بعد مرور عملية التفتيش على الدخول؛ ولا تقدم هذه الشيكات استفساراً مدفوعاً أو ائتمانات احتياطية.
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.mjsالإبداع cmd/check وأنقذ هذا الملف هناك
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. تشغيل مع دليل جديد للنواتج
أدير واحدة من هذه البرامج بعد مرور الشيكات وهو يُنشئ الدليل قبل تقديم الطلب، ويسجل الطلب، ثم يحفظ الرد. أبق الدليل على الفشل: حذفه أو اختيار واحد جديد يسمح باستفسار آخر قابل للتعديل.
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-001وفّر هذا البرنامج في إطار مشروع JavaScript أو TypeScript. وهو يستخدم نفس الرزمة المثبتة على @flashdata-dev/sdk.
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-001الإبداع cmd/archive لذا نقطة الدخول هذه تبقى منفصلة عن برنامجك السريع
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-001الملفات المتوقعة
النجاح يطبع مسار النتائج المنقذ وإستخدامه. result.json كان يجب أن status: done; وتتحقق نتائج Google في results[].organic[]. صفيفة عضوية فارغة صالحة A reported API or transport error is save to error.json; intent.json remains the original pre-submission record.
runs/research-001/
request.json # المصدر والاستعلام والمعاملات
intent.json # وقت بدء المحاولة
result.json # الاستجابة الكاملة مع النتائج والاستخدام3. النواتج المحتفظ بها
اقرأ result.json للطوابق، والملخصات، و UI يعمل. هذه الأوامر لا تستخدم سوى الملفات المحلية ويتوقف البحث عن طريق نفس الدليل قبل إجراء مكالمة من الشبكة؛ ولا ينسق الأجهزة المختلفة أو يستعيد استجابة الخادم المفقودة.
cat runs/research-001/result.jsonGet-Content -Raw -LiteralPath './runs/research-001/result.json'الإبداع cmd/read وإنقاذ هذا الدّينك هناك ويقرأ الملف ويطبع سندات المصدر ورقم URLs دون بناء زبون أو تقديم طلب من شركة 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.jsonيقرر ما يجب فعله بعد الفشل
| ما لديك | الإجراء التالي: |
|---|---|
| الدليل الحالي/الإكسست | تفحص ملفاته ولم ترسل هذه المحاولة أي استفسارات جديدة. |
| result.json, status: done | اقرأ الاستجابة المحفوظة وعالجها. أعد استخدام usage فيها كإيصال للرسم الأصلي. |
| error.json with 401 / 403 / 402 | اصلح الوصول أو الاذن المصدرية أو التوازن قبل التخطيط لمحاولة جديدة. |
| 429 / retryAfter | انتظروا حسب التعليمات وقللوا معدل الطلب. استعراض المحاولة الفاشلة قبل اختيار دليل جديد. |
| غير معروف/قصد فقط/كتابة الفشل | ويمكن بالفعل قبول العمل. حافظ على الدليل والتفتيش History أو عمل معروف ID قبل إرسال استفسار آخر. |
عملاء من طراز Async ووظائف خلفية
| الحاجة | الاستخدام |
|---|---|
| إبقاء حلقة الحدث مستجيبة | The SDKعميل (أسينك) ينتظر المكالمات ولا يزال الاستفسار في الوقت الحقيقي مكتملا في ردها على HTTP. |
| يُسترجع بعد خروج عملية الاتصال | تقديم وظيفة خلفية مرة واحدة، وإنقاذ جهازها من بُعد ID، ثم قراءة الحالة والنتائج. |
| تشغيل على جدول زمني | إمكانية وصول المالك المستخدم إلى السجلات ذات الجرعة الدائمة، أو CLIمجلة الجريدة الحالية. |