# الأتمتة باستخدام FlashData CLI

يُقيّمُ a طلب، يُديرُه مِنْ a نصّ ويُقرأُ النتيجةَ المنفصلةَ و الإيصالات الخاطئةِ.

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

<a id="profiles"></a>

## 1. اختيار الموجز الحالي

استخدم CLI المثبّت وBash وjq. على Windows، شغّل أمثلة الصدفة في Git Bash. يستخدم هذا الدليل ملف research موثّقًا؛ واضبط FLASHDATA_STATE_DIR على المسار المطلق لمجلد تخزينه.

استخدم مستخدم نظام التشغيل ودليل الحالة نفسيهما في كل أمر. يتجاوز FLASHDATA_API_KEY المفتاح المحفوظ؛ واتركه غير مضبوط لاستخدام الملف الشخصي. لا يحمّل CLI ملفات .env.

### تحقق من إمكانية الوصول

```bash
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata auth status --profile research --state-dir "$FLASHDATA_STATE_DIR" --json
```

- [Connect the CLI first](https://flashdata.dev/ar/docs/guides/flashdata-cli/reference.md#existing-key)

<a id="profile-paths"></a>

### مواقع الدولة غير المستقرة

إستخدمي نسختك الأصلية --state-dir إذا اخترت موقعاً عادياً auth status ينبغي أن يكون التقرير data.accessVerified: true. من أجل نشر غير مكتمل، يستورد المالك المفتاح من خلال stdin من مخزنه السري.

| OS | Directory |
| --- | --- |
| Windows | %APPDATA%/FlashData |
| macOS | ~/Library/Application Support/FlashData |
| Linux | XDG_STATE_HOME/flashdata أو - /.local/state/flashdata |

- [وثائق تفويض خواديم](https://flashdata.dev/ar/docs/guides/production-deployment/reference.md#secrets)

<a id="check"></a>

## 2. تقييم الطلب والسعر

انقذوا request.jsonثمّ يُديرُ الشيكاتَ المجانيةَ في نفس الدليلِ. ولا يطبع المرشح true إلا عندما يكون سعر المصدر متاحاً ويغطي الرصيد استفساراً واحداً. توقّفْ على a مخرج غير صفري. لا يحجز سعراً ائتمانياً.

### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Bash + jq · no paid submission

```bash
set -euo pipefail
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
flashdata account balance --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > balance.json
flashdata query --input request.json --dry-run --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
  .ok and .data.dryRun and .data.estimateAvailable
  and ($balance[0].ok == true)
  and any(.data.estimate.prices[]?;
    .source == "google_search" and .available == true
    and (.estimatedCredits | type == "number")
    and ($balance[0].data.availableCredits | type == "number")
    and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json
```


<a id="json"></a>

## 3. تشغيل وقراءة الاستلام

بعد مرور الشيكات، أنقذ run-search.sh و اهربوا run-search.sh. ويُجري أول إعدام ناجح بحثا واحدا. كل محاولة تنقذ ملفاتها في دليل جديد على مدار كلي؛ والركض المستقر ID لندع CLI إعادة استخدام النجاح في وقت سابق لنفس الحساب، والصورة، ودليل الدولة.

### run-search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
dir=$(mktemp -d "cli-run.XXXXXX")
if ! flashdata query --input request.json --run-id cli-research-001 \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$dir/result.json" --timeout 2m --json --non-interactive \
  > "$dir/receipt.json" 2> "$dir/error.json"; then
  cat "$dir/error.json" >&2
  printf 'Inspect saved run cli-research-001; receipts: %s\n' "$dir" >&2
  exit 1
fi
jq -e '.schemaVersion == 1 and .ok == true' "$dir/receipt.json" >/dev/null
jq -e '.status == "done" and .source == "google_search"' "$dir/result.json" >/dev/null
jq -r '.results[]?.organic[]? | [.title, .link] | @tsv' "$dir/result.json"
jq '{runId, cached, usage}' "$dir/receipt.json"
printf 'Files: %s\n' "$dir"
```


<a id="receipt-fields"></a>

### أعرف أي ملف يقرأ

غلاف CLI واستجابة المصدر وثيقتا JSON مختلفتان. دون --output، توجد استجابة المصدر داخل data. يستخدم هذا المثال --output، لذا اقرأ حقول المصدر من result.json المحفوظ.

| File | اقرأ |
| --- | --- |
| receipt.json | حسناً runIdو مخبأ و ممر الاستخدام و طريق الإنتاج إيصال مخبأ يُبلغ عن الاستخدام الأصلي وليس شحنة جديدة |
| result.json | المصدر، الحالة، النتائج، الاستخدام. يستعاض عن الرمز Google Search برقم results[].organic[]. يمكن أن تكون المجموعة الفارغة نتيجة بحث صحيحة. |
| error.json | عند مخرج غير صفري error.code, error.httpStatus, error.retryAfter and any run/job IDs. |

#### receipt.json · illustrative excerpt

```json
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "cli-research-001",
  "cached": false,
  "data": {
    "output": "cli-run.EXAMPLE/result.json"
  },
  "usage": {
    "credits": 0.02
  }
}
```


<a id="recover"></a>

## إستعادة بدون بحث آخر

تحقق من الركض المنقذ قبل إعادة التجفيف وبإمكانية الوصول إلى الحساب الأصلي، يُصدّر نجاحاً إلى اسم ملف لا وجود له بعد. (ب) تحويلات المطالبة من حساب التجربة إلى المالك؛ والاحتفاظ بنتائج التجربة التي سبق تصديرها، واستخدام معدات جديدة من طراز IDs لمهام أصحابها الجدد. ويرفض طلب متغير في إطار نفس الترتيب، وهو " ID " ؛ ولا يستخدم أي " ID " إلا لمهمة جديدة مقصودة.

### التفتيش، ثم تصدير النجاح المنقذ

```bash
flashdata runs show cli-research-001 --profile research \
  --state-dir "$FLASHDATA_STATE_DIR" --json
flashdata runs show cli-research-001 --result --output recovered.json \
  --profile research --state-dir "$FLASHDATA_STATE_DIR" --json
```

- [الوظائف المقبولة والأخطاء والأوراق غير المؤكدة](https://flashdata.dev/ar/docs/guides/agent-recovery/reference.md)

<a id="recurring"></a>

## يضاف الجدول الزمني عندما يعمل السيناريو

استخدم --recurring مع وصول مالك مثبّت ومعرّف ثابت لكل موعد مجدول وحالة دائمة. لا تستطيع التجربة تنفيذ عمل متكرر. المضيف مسؤول عن الجدول؛ والخيار يتحقق من الوصول فقط. استخدم مشغّل المهام المتكررة الكامل للتعامل مع التواريخ المجدولة وإعادة التشغيل.

- [إدارة مهام العملاء المتكررة](https://flashdata.dev/ar/docs/guides/recurring-tasks/reference.md)
- [النشر إلى خادم أو حاوية](https://flashdata.dev/ar/docs/guides/production-deployment/reference.md)

<a id="storage"></a>

## الاختياري: تخزين حمولة خاصة

تحميل لكمتوبي --storage-config storage.jsonاحفظ فقط هذا الجسم المخزني storage.json وإستبدال أصحاب الأماكن محلياً. يجب أن يكون الملف خاصاً وممتلكاً من قبل المستعمل المنفذ. استخدموا أوامر الأذن المطابقة قبل أن يتم تحميلها

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### Linux / macOS

#### تقييد الوصول إلى الملفات

```bash
chmod 600 storage.json
```


### Windows PowerShell

#### تقييد الوصول إلى الملفات

```powershell
$storagePath = (Resolve-Path -LiteralPath './storage.json').Path
$storageUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$storageAcl = [System.Security.AccessControl.FileSecurity]::new()
$storageAcl.SetOwner($storageUser)
$storageAcl.SetAccessRuleProtection($true, $false)
$storageAcl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($storageUser, 'FullControl', 'Allow'))
Set-Acl -LiteralPath $storagePath -AclObject $storageAcl
```


- [مقدمو خدمات التخزين ونتائج التنفيذ](https://flashdata.dev/ar/docs/guides/youtube-download-guide/reference.md#storage)
- [قيادة تحميل](https://flashdata.dev/ar/docs/guides/flashdata-cli/reference.md#commands)

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

## الأدلة ذات الصلة

- [CLI faststart](https://flashdata.dev/ar/docs/guides/flashdata-cli/reference.md)
- [التاريخ](https://flashdata.dev/app/jobs)
- [التخزين الاستبدادي والإلغاء](https://flashdata.dev/ar/docs/guides/production-deployment/reference.md#maintain)
