يمكنك استرداد مقاييس الأداء الرئيسية لمنتجاتك المشارِكة في برنامج شركاء YouTube باستخدام واجهة برمجة التطبيقات الفرعية Reporting. يوضّح هذا الدليل كيفية طلب بيانات الشركاء التابعين الخاصة بمنصة YouTube، مثل المبيعات والعمولات والطلبات والمشاهدات والنقرات، والتي تعود إلى صنّاع محتوى مختلفين ومحتوى فيديو ومنتجات فردية وحملات مستهدَفة.
يجب أن يتوافق استخدامك لواجهات برمجة التطبيقات الخاصة ببرنامج التسويق بالعمولة من YouTube والبيانات المرتبطة بها مع سياسات مطوّري "التسوّق على YouTube".
يمكنك استخدام Merchant Center Query Language (MCQL) لاختيار المقاييس والسمات من طرق العرض المخصّصة في "برنامج شركاء YouTube"، والتي تعمل مثل الجداول في طلبات البحث.
المتطلبات الأساسية
قبل استخدام هذا الدليل، تأكَّد مما يلي:
- يملك الحساب المستخدَم للمصادقة على طلبات البيانات من واجهة برمجة التطبيقات دور الأداء والإحصاءات الذي يمنح إذن الوصول إلى مقاييس الأداء.
- يشارك حسابك على Google Merchant Center في برنامج التسويق بالعمولة من منصّة YouTube.
طلب البحث من نقطة نهاية الإصدار الأوّلي
بما أنّ هذه الميزة في مرحلة الإصدار الأوّلي العلني، يختلف عنوان URL لنقطة النهاية. لاسترداد بيانات أداء برنامج الشركاء التابعين في YouTube، عليك إرسال طلب POST إلى نقطة النهاية v1alpha. لمزيد من المعلومات حول استرداد التقارير، يُرجى الاطّلاع على
accounts.reports.search.
في ما يلي نموذج للطلب:
HTTP
POST https://merchantapi.googleapis.com/reports/v1alpha/accounts/{ACCOUNT_ID}/reports:search
{
"query": "SELECT title, channel_id, gross_sales, net_sales, commissions, orders, clicks, views FROM youtube_creator_performance_view WHERE date >= '2025-05-01' AND date < '2025-05-02' ORDER BY gross_sales DESC LIMIT 3"
}
cURL
curl -X POST \
'https://merchantapi.googleapis.com/reports/v1alpha/accounts/{ACCOUNT_ID}/reports:search?key={YOUR_API_KEY}' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"query": "SELECT title, channel_id, gross_sales, net_sales, commissions, orders, clicks, views FROM youtube_creator_performance_view WHERE date >= '\''2025-05-01'\'' AND date < '\''2025-05-02'\'' ORDER BY gross_sales DESC LIMIT 3"
}' \
--compressed
الاطّلاع على الأداء حسب صانع المحتوى
لمعرفة صنّاع المحتوى على YouTube الذين يحقّقون أكبر قدر من التفاعل والمبيعات، يمكنك طلب البحث عن youtube_creator_performance_view.
تجمع طريقة العرض هذه المقاييس حسب صنّاع المحتوى الفرديين على YouTube، وتشمل عناوين صنّاع المحتوى ومعرّفات القنوات.
في ما يلي مثال على عبارة MCQL SELECT يمكنك استخدامها للحصول على
أفضل 3 صنّاع محتوى من حيث المبيعات بين 1 مايو و2 مايو 2025:
SELECT title, channel_id, gross_sales, net_sales, commissions, orders, clicks, views FROM youtube_creator_performance_view WHERE date >= '2025-05-01' AND date < '2025-05-02' ORDER BY gross_sales DESC LIMIT 3
يجلب طلب البحث هذا عنوان صانع المحتوى ومعرّف القناة ومقاييس الأداء الرئيسية لأهم 3 صنّاع محتوى مرتّبين حسب مقياس إجمالي المبيعات ضمن النطاق الزمني المحدّد.
الاطّلاع على الأداء حسب المحتوى
للاطّلاع على فيديوهات YouTube المحدّدة التي تحقّق أفضل أداء، يمكنك طلب البحث عن
youtube_content_performance_view.
تجمع طريقة العرض هذه المقاييس حسب فيديوهات YouTube الفردية، وتشمل عناوين الفيديوهات ومعرّفاتها.
لاسترداد أفضل 3 فيديوهات حسب عدد المشاهدات بين 1 مايو و2 مايو 2025، مرِّر عبارة MCQL التالية إلى الطريقة accounts.reports.search:
SELECT title, video_id, gross_sales, net_sales, commissions, orders, clicks, views FROM youtube_content_performance_view WHERE date >= '2025-05-01' AND date < '2025-05-02' ORDER BY views DESC LIMIT 3
يستردّ طلب البحث هذا عنوان الفيديو ورقم تعريفه والمقاييس الرئيسية لأفضل 3 فيديوهات مرتّبة حسب إجمالي عدد views في النطاق الزمني المحدّد.
الاطّلاع على المنتجات المُشار إليها التي حصدت أكبر قدر من التفاعل
لمعرفة المنتجات التي تمت الإشارة إليها والتي حصدت أعلى نسبة تفاعل ومبيعات، يمكنك طلب البحث عن youtube_product_tagged_stats_view.
تجمع طريقة العرض هذه المقاييس حسب المنتجات الفردية التي تمت الإشارة إليها، بما في ذلك عناوينها وأرقام تعريف العروض.
في ما يلي مثال على عبارة MCQL SELECT يمكنك استخدامها للحصول على
أفضل 10 منتجات حسب عدد المشاهدات بين 20 و21 يناير 2026:
SELECT title, offer_id, tagged_creator_count, tagged_video_count, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_product_tagged_stats_view WHERE date >= '2026-01-20' AND date < '2026-01-21' ORDER BY views DESC LIMIT 10
يستردّ طلب البحث هذا العناوين وعدد الفيديوهات التي تمّت الإشارة فيها إلى المنتجات والمقاييس الرئيسية لأهم 10 منتجات مرتّبة حسب إجمالي عدد views في النطاق الزمني المحدّد.
الاطّلاع على المنتجات الأكثر مبيعًا
لمعرفة المنتجات التي حقّقت أكبر عدد من المبيعات، يمكنك طلب البحث عن
youtube_product_sold_stats_view.
في ما يلي مثال على عبارة MCQL SELECT يمكنك استخدامها للحصول على
أفضل 10 منتجات مرتّبة حسب إجمالي المبيعات بين 20 و21 يناير 2026:
SELECT title, offer_id, gross_sales, net_sales, commissions, orders FROM youtube_product_sold_stats_view WHERE date >= '2026-01-20' AND date < '2026-01-21' ORDER BY gross_sales DESC LIMIT 10
يستردّ هذا الطلب بيانات المبيعات والعمولات والمقاييس الرئيسية لأفضل 10 منتجات تم طلبها حسب إجمالي المبيعات، وذلك في النطاق الزمني المحدّد.
الاطّلاع على الأداء على مستوى جميع الحملات
للتعرّف على مستوى أداء حملات الشركاء التابعين بشكل عام، يمكنك طلب البحث عن youtube_campaigns_stats_view.
تجمع طريقة العرض هذه المقاييس على مستوى جميع الحملات، بما في ذلك أسماء الحملات وتواريخ البدء والانتهاء وعدد صنّاع المحتوى النشطين ومقاييس المبيعات والتفاعل.
استخدِم عبارة MCQL SELECT التالية للحصول على أفضل 10 حملات حسب الطلبات في 23 أبريل 2026:
SELECT campaign_id, campaign_name, start_date, end_date, active_creators, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_campaigns_stats_view WHERE date = '2026-04-23' ORDER BY orders DESC LIMIT 10
يستردّ هذا الطلب رقم تعريف الحملة واسم الحملة والنطاق الزمني وعدد صنّاع المحتوى النشطين ومقاييس الأداء الرئيسية لأفضل 10 حملات مرتّبة حسب إجمالي عدد orders في التاريخ المحدّد.
الاطّلاع على أداء الحملة حسب صانع المحتوى
لتحليل أداء صنّاع المحتوى الفرديين المشاركين في حملة معيّنة، يمكنك طلب البحث عن youtube_individual_campaign_stats_view.
تجمع طريقة العرض هذه المقاييس لكل صانع محتوى ضمن حملة، بما في ذلك عناوين القنوات وعدد الفيديوهات وعناوين المنتجات المُشار إليها.
استخدِم عبارة MCQL SELECT التالية للحصول على أفضل 10 صنّاع محتوى حسب عدد المشاهدات لحملة معيّنة في 23 أبريل 2026:
SELECT channel_title, video_count, product_titles, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_individual_campaign_stats_view WHERE date = '2026-04-23' AND campaign_id = 'YOUR_CAMPAIGN_ID' ORDER BY views DESC LIMIT 10
يستردّ هذا الطلب عنوان قناة صانع المحتوى وعدد الفيديوهات وعناوين المنتجات ومقاييس الأداء الرئيسية لأفضل 10 صنّاع محتوى مرتّبين حسب إجمالي عدد المشاهدات ضمن الحملة والتاريخ المحدّدَين.
الاطّلاع على أداء الحملة حسب الفيديو
للاطّلاع على مستوى أداء فيديوهات معيّنة لصنّاع المحتوى ضمن حملة، أرسِل طلب بحث إلى youtube_campaign_videos_stats_view.
تقدّم طريقة العرض هذه مقاييس الأداء على مستوى الفيديو لصانع محتوى في حملة، بما في ذلك عناوين الفيديوهات وأشكالها والمنتجات التي تمّت الإشارة إليها.
استخدِم عبارة MCQL SELECT التالية للحصول على أفضل 10 فيديوهات حسب عدد المشاهدات لصنّاع محتوى وحملة معيّنَين في 20 مايو 2026:
SELECT video_title, content_type, product_titles, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_campaign_videos_stats_view WHERE date = '2026-05-20' AND campaign_id = 'YOUR_CAMPAIGN_ID' AND channel_id = 'YOUR_CHANNEL_ID' ORDER BY views DESC LIMIT 10
يستردّ هذا الطلب عنوان الفيديو وتنسيقه (content_type) وعناوين المنتجات التي تمّت الإشارة إليها ومقاييس الأداء الرئيسية لأفضل 10 فيديوهات مرتّبة حسب إجمالي عدد views لقناة صانع المحتوى والحملة والتاريخ المحدّدين.
الاطّلاع على أداء الحملة حسب المنتج
لمعرفة مستوى أداء المنتجات الفردية ضمن حملة، يمكنك طلب البحث عن youtube_campaign_products_stats_view.
يوفّر هذا العرض مقاييس الأداء على مستوى المنتج ضِمن الحملة، بما في ذلك عناوين المنتجات وتفاصيل الفيديو المرتبطة بها ومقاييس المبيعات.
استخدِم عبارة MCQL SELECT التالية للحصول على أفضل 10 منتجات
حسب عدد المشاهدات لحملة معيّنة في 20 يونيو 2026:
SELECT channel_title, product_title, video_title, video_url, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_campaign_products_stats_view WHERE date = '2026-06-20' AND campaign_id = 'YOUR_CAMPAIGN_ID' ORDER BY views DESC LIMIT 10
يستردّ طلب البحث هذا عنوان قناة صانع المحتوى وعنوان المنتج وعنوان الفيديو وعنوان URL الخاص بالفيديو ومقاييس الأداء الرئيسية لأفضل 10 منتجات حسب الترتيب استنادًا إلى إجمالي عدد views ضمن الحملة والتاريخ المحدّدَين.
اعتبارات مهمة
- التواريخ: احرص دائمًا على فلترة طلبات البحث حسب
dateباستخدام عباراتWHEREلتحديد الفترة المشمولة بالتقارير. التواريخ بالتنسيقYYYY-MM-DD - الفلاتر المطلوبة: تتطلّب بعض طرق عرض الحملات فلاتر إضافية في عبارة
WHERE:-
youtube_individual_campaign_stats_view:campaign_idوdate youtube_campaign_videos_stats_view:campaign_idوchannel_idوdate-
youtube_campaign_products_stats_view:campaign_idوdate
-
- وقت الاستجابة: يعتمد وقت استجابة طلبات البحث على حجم البيانات المطلوبة. تستغرق طلبات البحث التي تغطي مجموعات بيانات كبيرة وقتًا أطول وقد تؤدي إلى انتهاء المهلة.