دليل Twitch API (Helix) في 2026: المصادقة ونقاط النهاية والحدود

واجهة Twitch API، المعروفة باسم Helix، واجهة REST على https://api.twitch.tv/helix. بتطبيق مسجّل واحد ورمز من تدفق client credentials، تستطيع قراءة المستخدمين والبثوث المباشرة والفيديوهات والمقاطع ومعلومات القنوات وجداول البث. يشرح هذا الدليل الإعداد، والمصادقة، ونقاط النهاية الأكثر استخدامًا، وحدود الطلبات، والتنقل بين الصفحات، والتغييرات التي تكسر الشيفرة القديمة.

ما هي Twitch Helix API؟

Helix هي واجهة Twitch API الحالية. وقد حلّت محل v5، المعروفة باسم Kraken، التي توقفت نقاط نهايتها عن العمل في 28 فبراير 2022. وتسمّيها وثائق Twitch اليوم في الغالب Twitch API، لكن الاسم باقٍ في كل رابط. ويحتاج كل طلب إلى ترويستين:

• Client-Id: معرّف العميل الخاص بتطبيقك.
• Authorization: Bearer <token>: رمز وصول للتطبيق أو للمستخدم.

كيف تحصل على بيانات اعتماد Twitch API؟

1. فعّل المصادقة الثنائية في حسابك على Twitch؛ فلوحة المطوّرين تشترطها.
2. سجّل تطبيقًا في dev.twitch.tv/console: اختر Applications ثم Register Your Application، وأدخل اسمًا ورابط إعادة توجيه OAuth (مثل http://localhost) وفئة.
3. انسخ Client ID، وأنشئ Client Secret إن كان التدفق الذي تستخدمه يحتاج إليه.
4. احصل على رمز وصول. لدى Twitch نوعان:

ولقراءة البيانات العامة يكفي رمز التطبيق:

TOKEN=$(curl -s -X POST "https://id.twitch.tv/oauth2/token" \
  -d "client_id=$TWITCH_CLIENT_ID" \
  -d "client_secret=$TWITCH_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl "https://api.twitch.tv/helix/users?login=twitchdev" \
  -H "Client-Id: $TWITCH_CLIENT_ID" \
  -H "Authorization: Bearer $TOKEN"

وإذا كان تطبيقك يحتفظ برموز المستخدمين، فإن Twitch تشترط التحقق منها عبر https://id.twitch.tv/oauth2/validate عند تشغيله ثم كل ساعة بعد ذلك، وتدقّق في التطبيقات التي لا تفعل.

ما نقاط نهاية Twitch API التي تحتاج إليها؟

تقبل نقاط نهاية القراءة التالية رمز وصول للتطبيق أو للمستخدم، بحسب مرجع الواجهة:

تأخذ معظم نقاط النهاية معرّفات رقمية لا أسماء دخول، لذا تكون الخطوة الأولى عادةً استدعاء Get Users لتحويل twitchdev إلى broadcaster_id. وللتحقق مما إذا كانت عدة قنوات تبث مباشرة، مرّر حتى 100 قيمة user_login إلى Get Streams في طلب واحد: فالقناة غير المتصلة تغيب ببساطة عن النتيجة.

المتابعون هم الاستثناء. لا تعيد Get Channel Followers القائمة الكاملة إلا لرمز مستخدم بصلاحية moderator:read:followers، صادر عن صاحب القناة أو أحد مشرفيه. وأي رمز آخر يحصل على العدد الإجمالي فقط.

كيف تعمل حدود الطلبات في Twitch API؟

تستخدم Twitch نظام token bucket. لكل نقطة نهاية تكلفة بالنقاط، 1 افتراضيًا، ويُعاد ملء الرصيد على مدى دقيقة. ولرموز التطبيق ورموز المستخدم رصيدان منفصلان. وتخبرك كل استجابة بموقفك:

• Ratelimit-Limit: حجم الرصيد، وهو عادةً 800 نقطة في الدقيقة.
• Ratelimit-Remaining: النقاط المتبقية.
• Ratelimit-Reset: موعد إعادة ملء الرصيد، كطابع زمني بصيغة Unix.

اقرأ هذه الترويسات بدل تثبيت رقم في الشيفرة. وعند HTTP 429، انتظر حتى Ratelimit-Reset ثم أعد المحاولة، لكن افحص رسالة الخطأ أيضًا: فبعض أخطاء 429 لا علاقة لها بالرصيد.

كيف يعمل التنقل بين الصفحات في Twitch API؟

تعيد نقاط نهاية القوائم قيمة pagination.cursor. مرّرها كقيمة after للحصول على الصفحة التالية، وتوقف حين يصبح المؤشر فارغًا. ويحدد first حجم الصفحة، ويختلف حدّه الأقصى من نقطة نهاية إلى أخرى: 100 لمعظمها، و25 للجداول.

const headers = {
  'Client-Id': process.env.TWITCH_CLIENT_ID,
  Authorization: `Bearer ${process.env.TWITCH_TOKEN}`,
};
let after;
const clips = [];
do {
  const params = new URLSearchParams({ broadcaster_id: '141981764', first: '100', ...(after ? { after } : {}) });
  const res = await fetch(`https://api.twitch.tv/helix/clips?${params}`, { headers });
  const body = await res.json();
  clips.push(...body.data);
  after = body.pagination?.cursor;
} while (after && clips.length < 500);

ولرصد التغيّر مع الوقت، مثل بدء قناة بثًّا مباشرًا، يستهلك الاستطلاع المتكرر نقاطًا من حدود الطلبات في كل فحص. أما EventSub فيرسل الأحداث إلى webhook أو WebSocket لديك، وهو الأنسب للتنبيهات.

ما الذي تغيّر مؤخرًا في Twitch API؟

من سجل تغييرات Twitch:

بماذا تسمح شروط مطوّري Twitch؟

استخدام الواجهة مجاني، لكن اتفاقية Developer Services Agreement تضع قواعد تحدد ما يمكنك بناؤه. لا يجوز لك تخزين بيانات Twitch لأكثر من 24 ساعة ما لم تأذن Twitch بذلك كتابيًا أو كنت تملك الحقوق، ولا يجوز لك إعادة توزيعها أو بيعها، ويحتاج استخدامها في التسويق أو الأبحاث إلى اتفاقية منفصلة مع Twitch. وإذا كنت تخطط لبناء قاعدة بيانات للقنوات بمرور الوقت، فاقرأ الاتفاقية أولًا.

بيانات Twitch إلى جانب المنصات الأخرى

إذا كانت Twitch مصدرًا واحدًا من عدة مصادر، كأن تتابع صنّاع محتوى يبثون على Twitch وينشرون على TikTok وYouTube، فإن crawlfeed يقدّم عمليات القراءة على Twitch بالمفتاح نفسه وبنى الاستجابة نفسها التي يستخدمها لبقية منصاته الـ26:

يكلّف الاستعلام عن قناة رصيد واحد، ويجيب استدعاء live انطلاقًا من اسم القناة، دون الحاجة إلى البحث عن معرّف رقمي أولًا:

curl -G https://api.crawlfeed.dev/v1/twitch/live \
  -H "Authorization: Bearer $CRAWLFEED_KEY" \
  --data-urlencode "handle=shroud"

والنتيجة من نوع LiveStream، وهو النوع نفسه الذي يعيده crawlfeed للبث المباشر على TikTok. راجع مرجع Twitch لكل المُعاملات. أما كل ما يعمل نيابةً عن مستخدم، مثل الدردشة أو الإشراف أو قوائم المتابعين، فاستخدم له واجهة Twitch الخاصة.

الخلاصة

سجّل تطبيقًا في dev.twitch.tv/console مع تفعيل المصادقة الثنائية، واستبدل معرّف العميل والسرّ برمز وصول للتطبيق عبر id.twitch.tv/oauth2/token، ثم استدعِ https://api.twitch.tv/helix مع ترويستي Client-Id وAuthorization: Bearer. حوّل أسماء الدخول إلى معرّفات عبر Get Users، وتنقّل بين الصفحات بمؤشر after، وراقب ترويسات Ratelimit-*، واستخدم EventSub بدل الاستطلاع المتكرر لتنبيهات البث المباشر. الواجهة مجانية، لكن شروط Twitch تقصر تخزين بياناتها على 24 ساعة دون إذن.