> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# نظرة عامة على GraphQL API

> استعلم عن عمليات وسائل التواصل الاجتماعي المدعومة في Ayrshare عبر نقطة نهاية GraphQL واحدة.

تُتيح GraphQL API مجموعة فرعية مدعومة من إمكانات REST في Ayrshare عبر نقطة نهاية واحدة. يستدعي كل حقل متاح وحدة التحكم الأساسية نفسها التي يستدعيها نظيره في REST، لذا تتبع المصادقة والصلاحيات والحصص وبيانات الاستجابة سلوك REST. تظل REST هي واجهة API الأشمل؛ استخدم المخطط أو Explorer لمعرفة العمليات التي تدعمها GraphQL بالضبط.

ما تضيفه هو القدرة على طلب عدة أشياء في طلب واحد واكتشاف واجهة GraphQL المدعومة حاليًا من المخطط نفسه، دون قراءة التوثيق صفحةً تلو الأخرى. يصف المخطط كل حقل طلب مدعوم والتحديدات ذات الأنواع المتاحة في الاستجابات المنظّمة؛ أما العمليات التي تُرجع غلاف REST بصيغة `JSON` فتحتفظ بالحمولة الكاملة.

```
https://api.ayrshare.com/graphql
```

أرسل طلب `POST` بجسم JSON يحتوي على `query`، تمامًا كما هو الحال مع أي نقطة نهاية GraphQL. يُرجع `GET` و`DELETE` الرمز `405 Method Not Allowed`، إذ إن الاستعلامات عبر `GET` اختيارية في مواصفة GraphQL وغير مدعومة هنا.

<h2 id="your-first-query">
  استعلامك الأول
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

الاستجابة هي غلاف JSON نفسه الذي تُرجعه [نقطة نهاية السجل في REST](/docs/apis/history/get-history)، مُغلّفًا داخل الحقل `data` في GraphQL:

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  طلب عدة أشياء في آن واحد
</h2>

السبب الذي يدفعك إلى استخدام GraphQL هو طلب كهذا، كان سيتطلب أربعة استدعاءات REST:

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

رحلة ذهاب وإياب واحدة تُرجع الأربعة جميعًا. لاحظ أن هذه **أربعة حقول عمليات جذرية وأربعة استدعاءات API لأغراض الفوترة**، وليست استدعاءً واحدًا. لا يضيف تحديد حقول الاستجابة المتداخلة أي استدعاءات؛ راجع [الحدود والفوترة](/docs/apis/graphql/limits).

<h2 id="authentication">
  المصادقة
</h2>

مطابقة لـ REST. أرسل مفتاح API الخاص بك كرمز bearer:

```
Authorization: Bearer YOUR_API_KEY
```

إذا كان حسابك يستخدم User Profiles، فيمكن للعمليات التي تُتيح `profileKey` تحديد الملف الشخصي بإحدى طريقتين:

<ul class="custom-bullets">
  <li>أرسل <code>Profile-Key</code> كقيمة افتراضية على مستوى الطلب بأكمله.</li>
  <li>مرّر <code>profileKey</code> في حقل منفرد لتجاوز تلك القيمة الافتراضية، مما يسمح لطلب واحد بالعمل على أكثر من ملف شخصي.</li>
</ul>

تكون الأولوية لوسيط الحقل عند وجود الاثنين معًا. لا تُتيح الحقول الخاصة بمستوى الحساب أو بالحساب الأساسي فقط `profileKey` وقد ترفض ترويسة `Profile-Key`؛ على سبيل المثال، يجب أن يستخدم `createProfile` مفتاح API الأساسي دون تلك الترويسة. تحقّق من تعريف كل حقل في المخطط لمعرفة نطاقه، وراجع [إدارة مستخدمين متعددين](/docs/multiple-users/business-plan-overview) لمعرفة كيفية عمل مفاتيح الملفات الشخصية.

<h2 id="try-it-without-writing-code">
  جرّبها دون كتابة أي شيفرة
</h2>

[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) هو متصفح تفاعلي للمخطط الحالي. يسرد كل عملية GraphQL متاحة مع وسائطها وأوصافها، ويُكمل تلقائيًا أثناء الكتابة، وينفّذ الاستعلامات على حسابك.

لا تحتاج إلى مفتاح API لتصفح المخطط، فالمخطط عام، تمامًا مثل هذا التوثيق. لكنك تحتاج إليه لتنفيذ استعلام، لأن كل عملية تمر عبر المصادقة نفسها المستخدمة في REST.

<h2 id="should-you-use-graphql-or-rest">
  هل تستخدم GraphQL أم REST؟
</h2>

تظل REST الواجهة الأساسية، وهي التي بُني حولها معظم توثيقنا و[حزم SDK](/docs/packages-guides/overview) والتكاملات. استخدم GraphQL عندما:

<ul class="custom-bullets">
  <li>تحتاج إلى عدة أجزاء غير مترابطة من البيانات وتريدها في رحلة ذهاب وإياب واحدة.</li>
  <li>تريد أسماء عمليات ووسائط وكائنات إدخال وتعدادات وتحديدات استجابة ذات أنواع قابلة للقراءة آليًا. تظل معظم الاستجابات بصيغة <code>JSON</code> حتى تحتفظ بغلاف REST الكامل؛ ويُرجع <code>createPost</code> حاليًا <code>PostResult</code> ذا نوع محدد.</li>
  <li>تستكشف واجهة API وتريد رؤية ما هو موجود دون التنقل بين صفحات التوثيق.</li>
</ul>

استمر في استخدام REST عندما:

<ul class="custom-bullets">
  <li>ترفع ملفات. لا يمكن لبايتات الوسائط أن تنتقل عبر طلب GraphQL؛ راجع <a href="/docs/apis/graphql/using-the-api#uploading-media">رفع الوسائط</a> لمعرفة المسار المدعوم.</li>
  <li>تستخدم إحدى <a href="/docs/packages-guides/overview">حزم SDK أو تكاملات بدون شيفرة</a> الخاصة بنا، والتي تتعامل عبر REST.</li>
  <li>تريد أصغر قدر ممكن من التبعيات. لا يحتاج استدعاء REST إلى شيء سوى عميل HTTP.</li>
</ul>

الواجهتان مدعومتان جنبًا إلى جنب، ويمكنك المزج بينهما بحرية في التكامل نفسه.

<h2 id="read-next">
  اقرأ التالي
</h2>

<ul class="custom-bullets">
  <li>[استخدام واجهة API](/docs/apis/graphql/using-the-api): العثور على العمليات، وأنواع الوسائط، ورفع الوسائط.</li>
  <li>[الأخطاء](/docs/apis/graphql/errors): حالات الفشل التي تُغيّر حالة HTTP، ولماذا تُرجع العمليات الفاشلة HTTP 200 مع ذلك، وكيفية التعامل مع النجاح الجزئي.</li>
  <li>[الحدود والفوترة](/docs/apis/graphql/limits): الحدود القصوى لحجم الاستعلام وكيفية احتساب الطلبات.</li>
</ul>