كيفية الحصول على مفتاح YouTube API (YouTube Data API v3) وإجراء طلبك الأول

مفتاح YouTube API هو بيانات الاعتماد التي تسمح لرمزك بقراءة بيانات YouTube العامة: تفاصيل الفيديو، إحصائيات القناة، نتائج البحث، محتويات قوائم التشغيل. تصف وثائق Google الأمر بوضوح: "يجب أن يرسل أي طلب لا يوفر رمز OAuth 2.0 مفتاح API. يحدد المفتاح مشروعك ويوفر الوصول إلى API، والحصص، والتقارير." لا مفتاح، لا بيانات.

يقودك هذا الدليل من مشروع Google Cloud فارغ إلى طلب عامل في حوالي خمس عشرة دقيقة. ستقوم بتمكين YouTube Data API v3، وإنشاء مفتاح، وتأمينه، واستدعاء الـ API من curl و Python، ثم تخزين المفتاح في Apidog وحفظ الاستدعاء كاختبار قابل للتكرار. إذا كنت ترغب في الحصول على نظرة عامة أولاً، فإن نظرة عامة على YouTube Data API تغطي ما يكشفه الـ API؛ هذا المنشور هو الجزء العملي.

ما تحتاجه قبل البدء

• حساب Google. هذا يكفي لفتح Google Cloud Console وإنشاء مشروع.
• curl (يأتي مع macOS ومعظم توزيعات Linux) و Python 3 مع حزمة requests لعينات الكود.
• Apidog إذا كنت تريد تخزين المفتاح كسري وحفظ الطلب كاختبار. الخطة المجانية تغطي كل شيء هنا.

الخطوة 1: إنشاء مشروع Google Cloud

افتح Google Cloud Console وقم بتسجيل الدخول. استخدم منتقي المشروع في أعلى الصفحة لإنشاء مشروع جديد، على سبيل المثال youtube-integration. كل مفتاح API، وحصة، وتقرير استخدام ستراه لاحقًا يتم تحديد نطاقه لهذا المشروع، لذا احتفظ بمشروع واحد لكل تطبيق بدلاً من مشاركة مفتاح عبر أدوات غير ذات صلة. إذا كان التطبيق يحتوي بالفعل على مشروع، استخدمه.

الخطوة 2: تمكين YouTube Data API v3

واجهات الـ API تكون معطلة افتراضيًا في المشروع الجديد. في وحدة التحكم، انتقل إلى APIs & Services (واجهات الـ API والخدمات)، افتح API Library (مكتبة الـ API)، ابحث عن "YouTube Data API v3"، وقم بتمكينه. يصف دليل البدء من Google نفس التحقق من الاتجاه الآخر: قم بزيارة صفحة Enabled APIs (واجهات الـ API الممكنة) وقم بتمكين الـ API إذا لم يكن مدرجًا.

تخطَ هذه الخطوة وسيفشل طلبك الأول برمز 403 يشير إلى أن الـ API لم يستخدم في المشروع أو معطل. هذا هو السبب الأكثر شيوعًا لكون المفتاح الجديد "لا يعمل".

الخطوة 3: إنشاء مفتاح الـ API

انتقل إلى APIs & Services (واجهات الـ API والخدمات)، ثم Credentials (بيانات الاعتماد). انقر على Create credentials (إنشاء بيانات اعتماد) واختر API key (مفتاح API). تنشئ وحدة التحكم المفتاح فورًا وتعرضه في مربع حوار؛ انسخه في مكان آمن.

عامل المفتاح ككلمة مرور. لا تلصقه في مستودع Git، أو في محادثة Slack، أو في حزمة JavaScript من جانب العميل. إذا كان قد تسلل بالفعل إلى التزام (commit)، فإن دليلنا حول البحث عن مفاتيح الـ API المكشوفة وإصلاحها يغطي عملية التنظيف.

الخطوة 4: تقييد المفتاح

تقول وثائق Google الخاصة بها: "مفاتيح API غير المقيدة غير آمنة." بعد الإنشاء مباشرة، انقر على Restrict key (تقييد المفتاح). تحصل على تحكمين مستقلين، موثقين في دليل مفاتيح Cloud API:

• قيود التطبيق تحدد من يمكنه تقديم المفتاح. اختر واحدًا: مواقع الويب (مُحيلو HTTP، مع دعم محدود لرموز البدل)، عناوين IP (IPv4، IPv6، أو نطاقات CIDR)، تطبيقات Android (اسم الحزمة بالإضافة إلى بصمة شهادة SHA-1)، أو تطبيقات iOS (معرفات الحزمة). يجب أن تستخدم خدمة الواجهة الخلفية عناوين IP. يجب أن تستخدم أداة المتصفح فقط المُحيلين.
• قيود الـ API تحدد واجهات الـ API التي يمكن للمفتاح استدعاؤها. اختر "Restrict key" (تقييد المفتاح) وحدد فقط YouTube Data API v3. إذا تسرب المفتاح، يحصل المهاجم على حصة YouTube ولا شيء آخر.

احفظ وانتظر بضع دقائق حتى يسري التغيير قبل الاختبار. عادتان أخريان من نفس الدليل: قم بتدوير المفاتيح بشكل دوري للحد من الضرر الناتج عن المفتاح المخترق، واحذف المفاتيح القديمة بمجرد انتقال جميع المستدعين إلى البديل. ملاحظة للخطوة التالية: إذا قمت بالتقييد بواسطة IP إلى خادمك، فسيتم حظر curl من جهاز الكمبيوتر المحمول الخاص بك، لذا اختبر من المضيف المسموح به أو أنشئ مفتاح تطوير منفصل.

الخطوة 5: قم بأول طلب لك باستخدام curl و Python

كل نقطة نهاية ترتبط بـ https://www.googleapis.com/youtube/v3/. قم بتمرير المفتاح كمعامل استعلام key، وهي الطريقة التي تستخدمها أمثلة Google، أو في رأس x-goog-api-key، مما يبقيه خارج عناوين URL وسجلات الوصول. كلاهما يعمل على الـ API الحي.

ابدأ بـ videos.list، أرخص استدعاء مفيد: يعيد تفاصيل لمعرف فيديو واحد أو أكثر ويكلف وحدة حصة واحدة. المعرف أدناه هو الذي تستخدمه Google في وثائقها.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

يبدو الرد المختصر كما يلي:

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

معامل part إلزامي ويتحكم في الأقسام التي يتم إرجاعها؛ snippet، statistics، contentDetails، و status هي الأكثر استخدامًا.

الآن بحث، وهو الاستدعاء الذي يرغب فيه معظم الناس. في Python مع requests:

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

بالنسبة لـ search.list، يجب أن يكون part هو snippet، و maxResults يكون افتراضيًا 5 ويقبل من 0 إلى 50، و type يكون افتراضيًا video,channel,playlist، لذا عيّنه إلى video إذا كنت تريد مقاطع الفيديو فقط. تحمل نتائج البحث videoId داخل id، وليس في المستوى الأعلى، وهذا هو سبب قراءة الحلقة أعلاه item["id"]["videoId"].

الخطوة 6: تخزين المفتاح وتشغيل الطلب في Apidog

متغير الشيل (shell variable) يعمل لسكريبت واحد. لا يعمل لفريق، ولا يوفر لك فحصًا محفوظًا وقابلاً لإعادة التشغيل. إليك نفس الطلب في Apidog، مع الاحتفاظ بالمفتاح بعيدًا عن السحابة.

1. إنشاء بيئة. أضف بيئة باسم YouTube بمتغيرين: base_url مضبوطًا على https://www.googleapis.com/youtube/v3، و youtube_api_key. بالنسبة للمفتاح، اترك القيمة المشتركة كعنصر نائب والصق المفتاح الحقيقي في حقل القيمة المحلية. تظل القيم المحلية في ذاكرة التخزين المؤقت لعميلك ولا تتم مزامنتها أبدًا مع زملائك في الفريق؛ الإعداد الكامل موجود في دليلنا حول البيئات والمتغيرات السرية في Apidog.
2. بناء الطلب. طلب جديد، GET {{base_url}}/videos، معلمات الاستعلام part=snippet,statistics و id=7lCDEYXw3mM، ورأس x-goog-api-key مضبوطًا على {{youtube_api_key}}. حدد بيئة YouTube وأرسل. يجب أن ترى نفس JSON مثل استدعاء curl.
3. تحويله إلى اختبار. في المعالجات اللاحقة للطلب (post-processors)، أضف تأكيدات: الحالة تساوي 200، و $.items[0].id يساوي 7lCDEYXw3mM. احفظ الطلب وأضفه إلى سيناريو اختبار. يتم تشغيل الفحص الآن عند الطلب، أو بجدول زمني، أو في CI من خلال Apidog CLI، حيث --env-var "youtube_api_key=$YOUTUBE_API_KEY" يحقن المفتاح في وقت التشغيل بدلاً من تخزينه.

تأتي المكافأة في المرة الأولى التي يتم فيها تدوير المفتاح أو تغيير قيد: أعد تشغيل سيناريو واحد وستعرف في غضون ثوانٍ ما إذا كانت كل مكالمة لـ YouTube لا تزال تعمل. قم بتنزيل Apidog للمتابعة؛ إنه مجاني لفرق تصل إلى أربعة أفراد.

الحصص والقيود

لا يفوتر لك YouTube Data API بالدولار؛ بل يفوتر لك بوحدات الحصة (quota units)، وتأتي الأرقام من صفحة حاسبة الحصة من Google. يحصل كل مشروع يُمكِّن الـ API على هذا التخصيص الافتراضي:

ضمن المجموعة المشتركة التي تبلغ 10,000 وحدة، تكلف طرق القائمة مثل videos.list، channels.list، playlistItems.list، و commentThreads.list وحدة واحدة لكل منها. تكلف عمليات الكتابة أكثر: videos.update و videos.delete تكلف 50 وحدة، و captions.insert تكلف 400. أربع قواعد من نفس الصفحة تشكل كيفية تصميمك حول هذا:

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

تُسعر الأدلة القديمة عملية البحث بـ 100 وحدة من إجمالي 10,000 وحدة. أما الصفحة الحالية فتضع search.list في فئة خاصة بها، لذا لا يزال الحد الأقصى هو 100 عملية بحث يوميًا، لكن عمليات البحث لم تعد تستهلك من حصة مكالماتك الأخرى.

إذا لم يكن ذلك كافياً، فإن صفحة تدقيق الحصص والامتثال توجهك إلى نموذج تمديد الحصص وتدقيق خدمات YouTube API. قبل تقديمه، قم بتخزين الاستجابات مؤقتًا، اطلب فقط قيم part التي تحتاجها، وقم بتجميع المعرفات في استدعاء videos.list واحد (يقبل معامل id قائمة مفصولة بفواصل). يظهر الاستخدام في صفحة الحصص في Cloud Console.

الأخطاء الشائعة وكيفية إصلاحها

تسرد مرجع أخطاء Google رموز الأسباب الخاصة بالـ API. الصفان الأولان أدناه يأتيان من إرسال طلبات حقيقية إلى الـ API المباشر بمفتاح خاطئ وبدون مفتاح.

خطأ آخر من الممارسة: إذا لم يتطابق تقييد التطبيق مع المتصل، فستحصل على خطأ 403 يذكر المُحيل أو عنوان IP المحظور. قم بإصلاح التقييد أو اتصل من المضيف المسموح به. ولاحظ أن سلاسل المنتديات القديمة تسمي خطأ المفتاح غير الصالح `keyInvalid`؛ الـ API المباشر يعيد `badRequest` بتفاصيل `API_KEY_INVALID`، لذا تطابق مع الرسالة أو التفاصيل، وليس سلسلة السبب القديمة.

الأسئلة الشائعة

هل مفتاح YouTube API مجاني؟

نعم. إنشاء مفتاح لا يكلف شيئًا، وتُسعر الوثائق الـ API بوحدات الحصص (quota units)، وليس بالمال. التخصيص الافتراضي أعلاه هو ما تحصل عليه دون طلب أي شيء.

متى أحتاج إلى OAuth بدلاً من مفتاح API؟

يحدد مفتاح API مشروعك ويفتح البيانات العامة. في اللحظة التي تلامس فيها بيانات المستخدم الخاصة، أو تقوم بإدراج أو تحديث أو حذف أي شيء، تتطلب Google رمز OAuth 2.0 من المستخدم الذي يمتلك تلك البيانات. تقييم مقطع فيديو، أو سرد اشتراكاتك الخاصة، أو استخدام مرشح mine=true كلها تقع ضمن جانب OAuth. يشرح مقارنتنا بين مفاتيح API ورموز الحامل (bearer tokens) لماذا تجيب بيانات الاعتماد المختلفة عن أسئلة مختلفة.

هل يمكن لوكيل الذكاء الاصطناعي استخدام مفتاح YouTube API الخاص بي؟

نعم، طالما أن الوكيل يعمل حيث تسمح قيود المفتاح. يعتبر خادم YouTube MCP إحدى الطرق لتسليم بيانات الفيديو لمساعد برمجي؛ امنحه مفتاحًا مقيدًا بـ Data API وللجهاز الذي يعمل عليه، واحتفظ به بعيدًا عن المطالبة نفسها.

ماذا يجب أن أفعل إذا تسرب المفتاح؟

احذفه في صفحة Credentials (بيانات الاعتماد) وأنشئ بديلاً. ثم أصلح المصدر: انقل المفتاح إلى قيمة محلية في Apidog أو متجر سري، وقم بمسح المستودع حتى لا يظل المفتاح القديم موجودًا في سجل الإصدارات.

الخطوة التالية

لديك الآن مشروع، و API ممكن، ومفتاح مقيد، وطلب يعمل من curl و Python و Apidog. اربط السيناريو المحفوظ بـ CI ودع صفحة Quotas (الحصص) تخبرك متى يحين وقت التحسين.