# البدء السريع

نفّذ أول بحث في Google واحصل على نتائج منظّمة لتطبيقك أو وكيل الذكاء الاصطناعي.

مرجع كانوني: https://flashdata.dev/ar/docs/guides/quickstart
Reviewed: 2026-11-04 by FlashData

<a id="agent"></a>

## ابدأ باستخدام وكيل الذكاء الاصطناعي

أرسل هذا الموجّه إلى وكيل يستطيع استخدام الطرفية. سيُعدّ FlashData وينفّذ عملية بحث واحدة.

### موجّه الإعداد والمهمة الأولى

```text
اقرأ https://flashdata.dev/auth.md واتبع تعليمات إعداد FlashData لهذه البيئة. أعد استخدام الوصول الموجود؛ وإن لم يوجد، ابدأ تجربة واحدة فقط إذا استوفيت شروطها. ابحث في Google عن "battery recycling research" بحد أقصى خمس نتائج. أعد عناوين المصادر وعناوين URL والأرصدة المستخدمة فعليًا. احتفظ ببيانات الاعتماد في مخزن محمي، وليس في المحادثة. إذا كان الوصول محظورًا، أبلغ عن الخطوة التالية بدلًا من إنشاء تجربة أخرى.
```

- [إعداد MCP](https://flashdata.dev/ar/docs/integrations/mcp-clients/reference.md)
- [مهارات الوكلاء](https://flashdata.dev/ar/docs/guides/agent-skill/reference.md)

<a id="application"></a>

## نفّذ أول استدعاء API

هل تفضّل كتابة الكود بنفسك؟ اتبع هذه الخطوات الثلاث في الطرفية.


<a id="api-key"></a>

### احصل على مفتاح API

أنشئ حسابًا وأكّد بريدك الإلكتروني، ثم أنشئ مفتاحًا بصلاحية Google Search. أعد استخدام مفتاحك إن كان لديك واحد بالفعل.

شغّل الأمر في الطرفية والصق المفتاح عند مطالبة الإدخال المخفي. تجاوز هذه الخطوة إذا كان FLASHDATA_API_KEY مضبوطًا بالفعل.

#### Bash

##### اضبط المفتاح

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

##### اضبط المفتاح

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


- [إنشاء حساب](https://flashdata.dev/signup)
- [فتح API Keys](https://flashdata.dev/app/api-keys)

<a id="request"></a>

### نفّذ بحثًا

اختر لغة برمجة وشغّل المثال في الطرفية نفسها. كل تشغيل يرسل عملية بحث واحدة.

#### Python

Python 3.10+ · احفظ المثال باسم quickstart.py.

##### تثبيت

```bash
python -m pip install "flashdata==1.1.0"
```

##### quickstart.py

```python
import json
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.search("battery recycling research", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    print(json.dumps(response, indent=2))
```

##### تشغيل

```bash
python quickstart.py
```


#### TypeScript

Node.js 22.18+ · ابدأ في مجلد فارغ واحفظ quickstart.mts.

##### الإعداد

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mts

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### تشغيل

```bash
node quickstart.mts
```


#### JavaScript

Node.js 22+ · ابدأ في مجلد فارغ واحفظ quickstart.mjs.

##### الإعداد

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mjs

```javascript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### تشغيل

```bash
node quickstart.mjs
```


#### Go

Go 1.25+ · ابدأ في مجلد فارغ واحفظ main.go. تجاوز go mod init إذا كنت تعمل ضمن وحدة موجودة.

##### الإعداد

```bash
go mod init example.com/flashdata-quickstart
go get github.com/flashdatadev/flashdata-go@v1.1.0
```

##### main.go

```go
package main

import (
    "context"
    "encoding/json"
    "log"
    "os"
    "time"

    flashdata "github.com/flashdatadev/flashdata-go"
)

func main() {
    key := os.Getenv("FLASHDATA_API_KEY")
    if key == "" {
        log.Fatal("Set FLASHDATA_API_KEY through your server's secret manager.")
    }
    client, err := flashdata.New(flashdata.Options{APIKey: key})
    if err != nil {
        log.Fatal(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()
    result, err := client.Google.Search(ctx, flashdata.GoogleSearchInput{
        Query: "battery recycling research",
        Params: &flashdata.GoogleSearchParams{Num: flashdata.Ptr(int64(5))},
    })
    if err != nil {
        // Do not automatically resubmit an uncertain paid request.
        log.Fatal(err)
    }
    if err := json.NewEncoder(os.Stdout).Encode(result); err != nil {
        log.Fatal(err)
    }
    if result.Status != "done" {
        log.Fatalf("Search did not complete: %s", result.Status)
    }
}
```

##### تشغيل

```bash
go run .
```


#### HTTP API

لا تحتاج إلى SDK. شغّل أمر Bash / cURL 7.76+ أو PowerShell 7.

##### Bash / cURL

```bash
curl --fail-with-body --silent --show-error \
  --request POST https://data.flashdata.dev/v1/queries/realtime \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
```

##### PowerShell 7

```powershell
$flashdataRequest = '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
$flashdataResult = Invoke-RestMethod -Method Post -Uri 'https://data.flashdata.dev/v1/queries/realtime' -Headers @{ 'X-API-Key' = $env:FLASHDATA_API_KEY } -ContentType 'application/json' -Body $flashdataRequest
$flashdataResult | ConvertTo-Json -Depth 20
```


- [تحقق من النتيجة أدناه](https://flashdata.dev/ar/docs/guides/quickstart/reference.md#result)

<a id="result"></a>

### تحقق من النتيجة

تتضمن الاستجابة الناجحة status: done. توجد المصادر في results[].organic والأرصدة المستخدمة في usage.credits.

#### مثال استجابة مختصر

```json
{
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  }
}
```

- [حسّن بحثك](https://flashdata.dev/ar/docs/guides/google-search-guide/reference.md)
- [جرّب YouTube Data](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md)
- [إعداد API وحل المشكلات](https://flashdata.dev/ar/docs/guides/http-quickstart/reference.md)

<a id="console"></a>

## جرّب لوحة التحكم

1. اصنعي حساباً أو اوقعي فيه التحقق الكامل من البريد الإلكتروني وأي شكل من أشكال الحساب المبينة في مجموعة الوصلات.
2. افتح Google Search، واختر مصدر Google Search ووضع Realtime، ثم أدخل battery recycling research. وسّع Additional parameters واضبط Page size (num) على 5.
3. تحقق من الطلب المُعرض و الائتمانات المتاحة، ثمّ يُدير البحث مرة واحدة.
4. فحص الرد والإستخدام. فتح مصدر عائد للتحقق من محتوياته قبل الاستشهاد بأكثر من مقتطفه.

- [إنشاء حساب](https://flashdata.dev/signup)
- [Open Google Search](https://flashdata.dev/app/google-search)

<a id="next"></a>

## تابع بعد النتيجة الأولى

- [البحث باستخدام المرشحات](https://flashdata.dev/ar/docs/guides/google-search-guide/reference.md)
- [استكشف بيانات YouTube](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md)
- [أضف البحث إلى تطبيق](https://flashdata.dev/ar/docs/guides/search-in-an-app/reference.md)

<a id="troubleshooting"></a>

## إذا فشل الطلب الأول

| ما الذي يظهر | الإجراء المطلوب |
| --- | --- |
| لم يتم ضبط FLASHDATA_API_KEY | اضبط المفتاح في الطرفية أو بيئة التشغيل التي تستخدمها للمثال. هذه الأمثلة لا تقرأ ملفات .env. |
| 401 / 403 | تحقق من أن المفتاح أو الاتصال نشط ولديه صلاحية google_search. |
| 402 | تحقق من الأرصدة المتاحة في Billing. اربط التجربة الحالية بالحساب إذا احتجت إلى صلاحيات المالك. |
| 429 | التزم بقيمة Retry-After. احتفظ بالهوية وإثبات التسجيل نفسيهما؛ لا تنشئ تجربة أخرى. |
| انتهت المهلة أو تعذّر تحديد حالة الإرسال | افحص التشغيل الموجود قبل إعادة المحاولة. على مستخدمي CLI الاحتفاظ بالملف الشخصي ومعرّف التشغيل نفسيهما؛ وعلى مستخدمي SDK/API حفظ معرّف المهمة أو الطلب المُعاد. |

