> ## 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 API.

<h2 id="finding-an-operation">
  العثور على عملية
</h2>

المخطط هو المرجع المعتمد للمجموعة الفرعية المدعومة من GraphQL: جذور العمليات وأسماؤها ووسائطها وأنواع الإدخال وقيم التعدادات. تقدّم الأوصاف إرشادات الاستخدام، ويعرض [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) كليهما. أما الإمكانات المتاحة في REST فقط، فاستخدم لها [مرجع REST API](/docs/apis/overview).

تتبع أسماء العمليات نقاط نهاية REST التي تصل إليها، بصيغة camelCase. فـ `GET /history` هو `postHistory`، و`GET /analytics/social` هو `socialAnalytics`، و`POST /post` هو `createPost`.

<h2 id="queries-read-mutations-write">
  الاستعلامات للقراءة، والطفرات للكتابة
</h2>

الاستعلامات (queries) هي عمليات قراءة وتحقق لا تُغيّر شيئًا لدينا. أما الطفرات (mutations) فتنشر أو تُغيّر الحالة، أو تبدأ عملًا، أو ترسل بريدًا إلكترونيًا. لا يحدد فعل HTTP في REST ولا تكلفة الاستدعاء الجذرَ المناسب:

<ul class="custom-bullets">
  <li>يتحقق <code>validatePost</code> من منشور دون نشره.</li>
  <li>يتحقق <code>validateMedia</code> من إمكانية الوصول إلى عنوان URL للوسائط.</li>
  <li><code>generatePost</code> هو استعلام لأنه لا يتغير شيء لدينا. لكنه لا يزال يُحتسب كاستدعاء API ويُرجع نصًا مختلفًا في كل مرة، لذا تأكد من أن ذاكرة التخزين المؤقت لدى العميل أو إعادة الجلب التلقائية لا تكرره دون أن تلاحظ.</li>
  <li><code>mediaUploadUrl</code> هو طفرة لأنه يُنشئ عنوان URL للرفع خاصًا بحسابك.</li>
  <li><code>linkAnalytics</code> هو طفرة لأنه قد يطلب تقريرًا يُرسَل عبر البريد الإلكتروني.</li>
  <li><code>userBatch</code> هو طفرة لأنه يبدأ مهمة تصدير.</li>
</ul>

استخدم Explorer أو المخطط للتأكد من الجذر الخاص بكل عملية مدعومة.

<h2 id="creating-a-post">
  إنشاء منشور
</h2>

يأخذ `createPost` وسيطًا واحدًا هو `input`، لذا فإن المنشور بأكمله كائن واحد:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}
```

يعكس الإدخال [نقطة نهاية النشر في REST](/docs/apis/post/post) الموثّقة، بما في ذلك كائنات الخيارات الخاصة بكل شبكة وصيغ REST التي تقبل أكثر من شكل JSON:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}
```

قد ينجح المنشور على شبكة ويفشل على أخرى. هذا ليس فشلًا في الطلب؛ راجع [الأخطاء](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

<h2 id="argument-types">
  أنواع الوسائط
</h2>

معظم الوسائط سلاسل نصية وأرقام وقيم منطقية عادية. وهناك ثلاث حالات تستحق المعرفة.

<h3 id="enums">
  التعدادات
</h3>

كثير من الوسائط النصية ذات المجموعة المغلقة من القيم المدعومة هي تعدادات GraphQL، وتُكتب **دون علامات اقتباس وبأحرف كبيرة**:

```graphql theme={"system"}
{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }
```

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

تتشارك بعض الوسائط الاسم نفسه عبر العمليات لكنها تقبل قيمًا مختلفة، لأن نقاط النهاية تختلف فعلًا. يقبل `reviews(platform:)` القيمتين `GMB` و`FACEBOOK` فقط، لأنهما الشبكتان الوحيدتان اللتان تحتويان على مراجعات. سيعرض الإكمال التلقائي في عميلك المجموعة الصحيحة لكل عملية.

<h3 id="the-json-scalar">
  النوع القياسي (scalar) JSON
</h3>

بعض الوسائط من النوع `JSON` بدلًا من نوع محدد. يحدث ذلك عندما يكون للقيمة بشكل مشروع أكثر من شكل ولا يمكن لنوع GraphQL واحد وصفها بدقة:

<ul class="custom-bullets">
  <li>يقبل <code>explainError(code:)</code> القيمة <code>215</code> أو <code>"215"</code>، لأن العملاء يحتفظون برموز الأخطاء بالصيغتين.</li>
  <li>يستخدم <code>createPost(input:)</code> صيغة JSON لحقول مثل <code>post</code> و<code>mediaUrls</code>، والتي يمكن أن تكون قيمًا مشتركة أو كائنات خاصة بكل منصة.</li>
  <li>يأخذ <code>createAutomation(triggers:, actions:)</code> مصفوفات تعتمد حقولها على <code>type</code> الخاص بكل عنصر.</li>
  <li>يقبل <code>boostFacebookPost(interests:)</code> معرّفات اهتمامات Meta كسلاسل نصية أو أرقام.</li>
</ul>

مرّر القيمة نفسها التي كنت سترسلها في جسم REST المقابل. الوسيط من نوع `JSON` ليس ثغرة: إذ يتحقق منه المُحلِّل قبل الإرسال، لذا تُرجع القيمة غير الصالحة خطأ تحقق ولا تستهلك أي استدعاء API.

<h3 id="optional-arguments-and-nulls">
  الوسائط الاختيارية والقيم الفارغة
</h3>

بالنسبة إلى الوسائط الاختيارية والحقول الاختيارية داخل كائنات الإدخال، تُعامَل القيمة `null` الصريحة كأنها محذوفة. أما العناصر الفارغة داخل القوائم فيُحتفظ بها عندما يسمح نوع القائمة بذلك.

<h2 id="reading-responses">
  قراءة الاستجابات
</h2>

تُرجع معظم العمليات قيمة قياسية (scalar) من النوع `JSON` تحتوي على غلاف استجابة REST الكامل، لذا حدّد الحقل الجذري دون حقول فرعية. يُرجع `createPost` حاليًا `PostResult` ذا نوع محدد، لذا حدّد حقوله:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}
```

تتضمن أنواع الاستجابة ذات الأنواع المحددة مثل `PostResult` أيضًا الحقل `raw: JSON!`، الذي يحتوي على استجابة REST الكاملة دون تعديل:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}
```

الحقل `raw` دائم، ووُجد حتى لا يتعذر أبدًا الوصول من GraphQL إلى حقل جديد يظهر في استجابة REST ريثما نُضيف نوعه. إذا احتجت إلى شيء لا تعرضه الحقول ذات الأنواع المحددة، فاطلب `raw`.

<h2 id="uploading-media">
  رفع الوسائط
</h2>

**لا يمكن لبايتات الوسائط أن تنتقل عبر طلب GraphQL.** طلب GraphQL هو مستند JSON واحد بحد أقصى 64 KB، لذا لا يوجد حقل يقبل ملفًا، كما أن ترميز صورة بصيغة base64 داخل الاستعلام سيتجاوز هذا الحد لأي شيء أكبر من صورة مصغّرة.

يتجنب المسار المدعوم هذه المشكلة تمامًا، وهو أسرع من الرفع عبر واجهة API في كل الأحوال، لأن البايتات تذهب مباشرة إلى التخزين:

1. اطلب عنوان URL للرفع:

   ```graphql theme={"system"}
   mutation { mediaUploadUrl(contentType: "image/jpeg") }
   ```

2. اقرأ `data.mediaUploadUrl.uploadUrl` و`accessUrl` و`contentType` من JSON المُرجَع.

3. نفّذ `PUT` لملفك **مباشرة إلى `uploadUrl`**، وليس إلى Ayrshare API، مع تعيين ترويسة `Content-Type` للطلب إلى قيمة `contentType` المُرجَعة.

4. بعد نجاح الرفع، مرّر `accessUrl` في `createPost.input.mediaUrls`:

   ```graphql theme={"system"}
   mutation {
     createPost(input: {
       post: "With a photo"
       platforms: [INSTAGRAM]
       mediaUrls: ["https://the-returned-access-url"]
       idempotencyKey: "instagram-photo-001"
     }) {
       status
       postIds { platform postUrl }
     }
   }
   ```

تعامل مع `uploadUrl` كبيانات اعتماد كتابة قصيرة الأجل، ولا تسجّله أو تكشفه. أما `accessUrl` فهو عنوان URL للوسائط المستخدم عند إنشاء المنشور.

يمكنك أيضًا الاستمرار في استخدام [نقاط نهاية الرفع في REST](/docs/apis/media/upload-media) والإشارة إلى عناوين URL الناتجة من GraphQL. تتشارك الواجهتان مكتبة الوسائط نفسها.

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

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