تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

البدء

فحص الحساب والنتائج المحفوظة باستخدام SDK

تحقق من التكلفة، والاحتفاظ بسجل لكل محاولة وقراءة النتائج المحفوظة دون اتصال آخر من API.

في هذه الصفحة

قبل أن تبدأ

استخدام المشروع، المركب SDK و FLASHDATA_API_KEY من SDK أسرع. اختر لغة واحدة أدناه. ويمثِّل كل دليل جديد للبحث المقصود؛ ويتوقف استخدام الدليل الحالي قبل تقديم أي طلب.

1. الوصول إلى السجلات والتكلفة الحالية

انقذوا و اديروا الشيك من اجلكم SDK. ويقرأ الأذون والرصيد وسعر واحد من طراز Google Search. ولا تستمر إلا بعد مرور عملية التفتيش على الدخول؛ ولا تقدم هذه الشيكات استفساراً مدفوعاً أو ائتمانات احتياطية.

check_access.py
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)
Linux / macOS
.venv/bin/python check_access.py
Windows PowerShell
.\.venv\Scripts\python.exe check_access.py

2. تشغيل مع دليل جديد للنواتج

أدير واحدة من هذه البرامج بعد مرور الشيكات وهو يُنشئ الدليل قبل تقديم الطلب، ويسجل الطلب، ثم يحفظ الرد. أبق الدليل على الفشل: حذفه أو اختيار واحد جديد يسمح باستفسار آخر قابل للتعديل.

archive_search.py
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)
Linux / macOS
.venv/bin/python archive_search.py runs/research-001
Windows PowerShell
.\.venv\Scripts\python.exe archive_search.py 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.json

يقرر ما يجب فعله بعد الفشل

ما لديكالإجراء التالي:
الدليل الحالي/الإكسستتفحص ملفاته ولم ترسل هذه المحاولة أي استفسارات جديدة.
result.json, status: doneاقرأ الاستجابة المحفوظة وعالجها. أعد استخدام usage فيها كإيصال للرسم الأصلي.
error.json with 401 / 403 / 402اصلح الوصول أو الاذن المصدرية أو التوازن قبل التخطيط لمحاولة جديدة.
429 / retryAfterانتظروا حسب التعليمات وقللوا معدل الطلب. استعراض المحاولة الفاشلة قبل اختيار دليل جديد.
غير معروف/قصد فقط/كتابة الفشلويمكن بالفعل قبول العمل. حافظ على الدليل والتفتيش History أو عمل معروف ID قبل إرسال استفسار آخر.

عملاء من طراز Async ووظائف خلفية

الحاجةالاستخدام
إبقاء حلقة الحدث مستجيبةThe SDKعميل (أسينك) ينتظر المكالمات ولا يزال الاستفسار في الوقت الحقيقي مكتملا في ردها على HTTP.
يُسترجع بعد خروج عملية الاتصالتقديم وظيفة خلفية مرة واحدة، وإنقاذ جهازها من بُعد ID، ثم قراءة الحالة والنتائج.
تشغيل على جدول زمنيإمكانية وصول المالك المستخدم إلى السجلات ذات الجرعة الدائمة، أو CLIمجلة الجريدة الحالية.