# تنسيقات الاستجابة

الاختراع مهيأ JSON لطلبك أو Markdown محتواه لوكيل الـ(آي آي) التحكم في الرد مع اثنين من رؤساء.

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

<a id="headers"></a>

## اختر استمارة

الافتراضي هو JSON بحقول النتائج الأصلية. يختار Accept صيغة JSON أو النص العادي؛ ويحوّل X-Respond-With: markdown محتوى النتيجة إلى Markdown. يبقى جسم طلبك بصيغة JSON.

| استجابة | Accept | X-Respond-With | الاستخدام |
| --- | --- | --- | --- |
| JSON | application/json | Omit | حقول العزل في الرمز |
| JSON + Markdown | application/json | markdown | سياق عمل مع البيانات الوصفية المنظمة |
| نص قُضي | text/plain | Omit | قراءة الحقول الأصلية في محطة |
| النص + Markdown | text/plain | markdown | قراءة البيانات الفوقية و Markdown معا |


<a id="examples"></a>

## أمثلة للطلبات والاستجابة

تعرض علامات التبويب بحث Google نفسه بكل صيغة. استخدم Bash وcURL 7.76+ مع ضبط FLASHDATA_API_KEY على مفتاح يسمح بـ google_search. يرسل كل تشغيل للأمر بحثًا واحدًا مدفوعًا.

### JSON

خطأ. تطهير صفيفة النتائج؛ وتعتمد المجالات داخلها على المصدر.

#### الطلب: cURL/ Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### الاستجابة على سبيل المثال: قيم توضيحية

```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Example page",
          "link": "https://example.com/article",
          "snippet": "A short source snippet."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-10-22T12:00:00.000Z"
}
```


### JSON + Markdown

اقرأ المحتوى كـ Markdown الخيط وهو يحل محل النتائج؛ ولا يزال المصدر والوضع والاستخدام متاحين في ميادين JSON.

#### الطلب: cURL/ Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Respond-With: markdown' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### الاستجابة على سبيل المثال: قيم توضيحية

```json
{
  "source": "google_search",
  "status": "done",
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-10-22T12:00:00.000Z",
  "content": "# Google search\n\n## Organic\n\n### 1. Example page\n\n**Link:** <https://example.com/article>\n\n**Snippet:** A short source snippet\\.\n"
}
```


### نص قُضي

اقرأ الرد كنص. وهي تحتوي على الحقول الأصلية في مخططات معدودة، وليس على وثيقة JSON.

#### الطلب: cURL/ Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/plain' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### الاستجابة على سبيل المثال: قيم توضيحية

```text
Source: "google_search"
Status: "done"
Results:
  1:
    Organic:
      1:
        Title: "Example page"
        Link: "https://example.com/article"
        Snippet: "A short source snippet."
Usage:
  Credits: 0.01
Created at: "2026-10-22T12:00:00.000Z"
```


### النص + Markdown

اقرأ الرد كنص: البيانات الوصفية أولا، يليه محتوى Markdown.

#### الطلب: cURL/ Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/plain' \
  --header 'X-Respond-With: markdown' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### الاستجابة على سبيل المثال: قيم توضيحية

```text
Source: "google_search"
Status: "done"
Usage: {"credits":0.01}
Created at: "2026-10-22T12:00:00.000Z"

Markdown Content:
# Google search

## Organic

### 1. Example page

**Link:** <https://example.com/article>

**Snippet:** A short source snippet\.
```


- [API authentication](https://flashdata.dev/ar/docs/guides/headers-and-authentication/reference.md)
- [Google Search response fields](https://flashdata.dev/ar/docs/sources/google_search/reference.md#response)

<a id="supported-endpoints"></a>

## نقاط النهاية المدعومة

وتنطبق نفس القواعد على مصادر الاستفسار من Google Search و YouTube. بالنسبة لـ YouTube Download، فإنها تشكل سجل التوصيل، وليس الفيديو أو اللوحات الصوتية. وتستخدم نماذجها الخاصة في حساب مؤشرات الأداء، وبيانات Bulk، وأجزاء من NDJSON، والردود على المكالمات، وردود MCP.

| نقطة النهاية | JSON/ plain text | محتوى Markdown |
| --- | --- | --- |
| POST /v1/queries/realtime | الدعم | الدعم |
| GET /v2/jobs/{id}/results | الدعم | الدعم |
| POST /v1/queries | إيصال المعلومات | - اختياره عند قراءة النتائج |
| POST /v1/queries/batch | إيصال المعلومات | - اختياره عند قراءة النتائج |
| GET /v2/jobs/{id} | مركز العمل | لا يوجد هناك أي نتيجة هنا |


<a id="completed-results"></a>

## الصيغة النهائية لنتيجة العمل

ضعوا الرعاة عند قراءة النتيجة، حتى لو وضعتموهم في المقدمة. المجموعة JOB_ID إلى عمل مكتمل يمكنك الوصول إليه ويقرأ هذا الرقم " GET " النتائج القائمة دون تقديم استفسار آخر.

| الشكل المطلوب | استجابة النتيجة |
| --- | --- |
| Original JSON | 302 مع رابط تخزين موقّع في Location. اجلب ذلك الرابط منفصلًا دون X-API-Key. قد تكون النتائج المخزنة مضغوطة بـ gzip. |
| نص مقدم أو خيار Markdown | استجابة 200 مع النص المنسّق مباشرة في الاستجابة. |

### Retrieve Markdown inside JSON ; cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json' \
  --header 'X-Respond-With: markdown'
```

- [Retrieve original JSON ; Python and cURL](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#results)

<a id="errors-and-scope"></a>

## الأخطاء الشكلية

API الأخطاء تبقى JSON أو application/problem+jsonحتى عندما تطلب نصاً عادياً تحقق من حالة HTTP قبل أن تقطع استمارة النجاح.

| الحالة/الرمز | Fix |
| --- | --- |
| 400 · unsupported_representation | إستعملْ X-Respond-With: علامة أسفل أَو omit the header. ولا تحظى قيم مثل " جيسون " أو النص بتأييد. |
| 406 · not_acceptable | الاستخدام Accept: application/json أو text/plain. text/markdown و application/xml غير مدعوم. |

- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md)

<a id="negotiation"></a>

## تفاصيل عن رئيس شركة Accept

احذف Accept أو أرسل */* للحصول على JSON. تستخدم الاستجابات UTF-8. تُدعم نطاقات الوسائط وأوزان q؛ ويعيد charset غير المدعوم 406 إلا إذا طابق نطاقًا مقبولًا آخر. يصف Content-Type: application/json جسم الطلب، وليس الاستجابة.

### النص المفضّل، السماح JSON

```http
Accept: text/plain; charset=utf-8, application/json;q=0.8
```

