بااستفاده از زیرمیانای برنامه‌سازی کاربردی «گزارش‌دهی» می‌توانید سنجه‌های کلیدی عملکرد را برای محصولات شرکت‌کننده در برنامه همکاری YouTube بازیابی کنید. این راهنما توضیح می‌دهد که چگونه داده‌های وابسته خاص YouTube، مانند فروش، کمیسیون، سفارش، بازدید، و کلیک، را که به محتواسازان مختلف، محتوای ویدیویی، محصولات فردی، دسته‌های محصول، و پویش‌های هدفمند نسبت داده شده‌اند، پُرسمان کنید.
استفاده شما از APIهای «برنامه فروش‌یار YouTube» و داده‌های مرتبط باید با خط‌مشی‌های توسعه‌دهنده «مرکز خرید YouTube» مطابقت داشته باشد.
می‌توانید از Merchant Center Query Language (MCQL) برای انتخاب سنجه‌ها و ابعاد از نماهای اختصاصی «برنامه همکاری YouTube» استفاده کنید که مانند جدول در پُرسمان‌های شما عمل می‌کنند.
پیش‌نیازها
قبل‌از استفاده از این راهنما، مطمئن شوید:
- حسابی که برای اصالت‌سنجی فراخوانی‌های میانای برنامه‌سازی کاربردی استفاده می‌شود، نقش عملکرد و اطلاعات آماری را دارد که دسترسی به سنجه‌های عملکرد را اعطا می‌کند.
- حساب Google Merchant Center شما در برنامه فروش‌یار YouTube شرکت می‌کند.
پُرسمان نقطه پایان آلفا
ازآنجایی‌که این ویژگی در مرحله آلفای عمومی است، نقطه پایانی متفاوت است. برای بازیابی داده‌های عملکرد «برنامه همکاری 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 آورده شده است که می‌توانید از آن برای دریافت
۳ محتواساز برتر ازنظر فروش بین ۱ مه و ۲ مه ۲۰۲۵ استفاده کنید:
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
این پُرسمان عنوان محتواساز، شناسه کانال، و سنجه‌های عملکرد کلیدی را برای ۳ محتواساز برتر که براساس سنجه فروش ناخالص در محدوده تاریخ مشخص‌شده رتبه‌بندی شده‌اند واکشی می‌کند.
مشاهده عملکرد براساس محتوا
برای دیدن اینکه کدام ویدیوهای YouTube بهترین عملکرد را دارند، می‌توانید
youtube_content_performance_view را پُرسمان کنید.
این نما سنجه‌ها را براساس ویدیوهای YouTube مجزا تجمیع می‌کند و شامل
عنوان‌ها و شناسه‌های ویدیو می‌شود. برای بازارگاه‌ها،
account_id را اضافه کنید تا عملکرد را براساس حساب‌های
فروشنده فرعی جداگانه تفکیک کنید. برای مشاهده مبالغ کارمزد تأمین‌شده توسط
فروشندگان فرعی و پلاتفرم بازارگاه، seller_commissions و
platform_commissions را اضافه کنید.
برای بازیابی ۳ ویدیو برتر براساس بازدید بین ۱ مه و ۲ مه ۲۰۲۵،
عبارت MCQL زیر را به روش
accounts.reports.search
ارسال کنید:
SELECT title, video_id, account_id, gross_sales, net_sales, commissions, seller_commissions, platform_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
این پُرسمان عنوان ویدیو، شناسه ویدیو، شناسه حساب فروشنده فرعی
(account_id)، کل کارمزدها (commissions)،
کارمزدهای تأمین‌شده توسط فروشنده (seller_commissions)،
کارمزدهای تأمین‌شده توسط پلاتفرم (platform_commissions)، و دیگر
سنجه‌های کلیدی برای ۳ ویدیو برتر رتبه‌بندی‌شده براساس تعداد کل
views در محدوده تاریخ مشخص‌شده را بازیابی می‌کند. توجه: نمی‌توانید از account_id در بند MCQL WHERE برای فیلتر کردن نتایج استفاده کنید.
دیدن محصولات برچسب‌گذاری‌شده با بیشترین تعامل
برای اینکه متوجه شوید کدام محصولات برچسب‌گذاری‌شده بیشترین تعامل و فروش را دارند،
می‌توانید
youtube_product_tagged_stats_view را پُرسمان کنید.
این نما سنجه‌ها را براساس محصولات برچسب‌گذاری‌شده تکی، ازجمله
عنوان‌ها و شناسه‌های پیشنهاد ویژه آن‌ها، انبوهش می‌کند.
در اینجا نمونه‌ای از بیانیه MCQL SELECT وجود دارد که می‌توانید برای دریافت
۱۰ محصول برتر براساس بازدیدها بین ۲۰ و ۲۱ ژانویه ۲۰۲۶ استفاده کنید:
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
این پُرسمان عنوان‌ها، تعداد ویدیوهای برچسب‌گذاری‌شده، و سنجه‌های کلیدی را برای ۱۰ محصول برتر که براساس تعداد کل views در محدوده تاریخ مشخص‌شده رتبه‌بندی شده‌اند بازیابی می‌کند.
دیدن عملکرد براساس دسته محصول برچسب‌گذاری‌شده
برای اینکه بفهمید کدام دسته‌های محصول برچسب‌گذاری‌شده بیشترین تعامل
و فروش را ایجاد می‌کنند،
youtube_product_category_tagged_stats_view را پُرسمان کنید.
این نما سنجه‌ها را براساس دسته محصول
(product_type) در طبقه‌بندی محصول شما تجمیع می‌کند، ازجمله
تعداد محتواسازان و ویدیوهای متمایزی که محصولات را در هر
دسته برچسب‌گذاری کرده‌اند.
از عبارت MCQL SELECT زیر برای دریافت ۱۰ دسته محصول برچسب‌گذاری‌شده برتر رتبه‌بندی‌شده براساس فروش ناخالص در ۱ سپتامبر ۲۰۲۶ استفاده کنید:
SELECT product_type, tagged_creator_count, tagged_video_count, gross_sales, net_sales, commissions, views, clicks, impressions, orders, conversion_rate FROM youtube_product_category_tagged_stats_view WHERE date = '2026-09-01' ORDER BY gross_sales DESC LIMIT 10
این پُرسمان دسته محصول (product_type)،
تعداد محتواسازان برچسب‌گذاری‌شده، تعداد ویدیوهای برچسب‌گذاری‌شده، و سنجه‌های کلیدی عملکرد
را برای ۱۰ دسته محصول برتر رتبه‌بندی‌شده براساس gross_sales در
تاریخ مشخص‌شده بازیابی می‌کند.
دیدن پرفروش‌ترین محصولات
برای اینکه بفهمید کدام محصولات بیشترین فروش را دارند، می‌توانید از
youtube_product_sold_stats_view پُرسمان کنید.
در اینجا نمونه‌ای از عبارت MCQL SELECT آورده شده است که می‌توانید از آن برای دریافت
۱۰ محصول برتر رتبه‌بندی‌شده براساس فروش ناخالص بین ۲۰ و ۲۱ ژانویه ۲۰۲۶ استفاده کنید:
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
این پُرسمان داده‌های فروش، کارمزدها، و سنجه‌های کلیدی را برای ۱۰ محصول برتر براساس فروش ناخالص در محدوده تاریخ مشخص‌شده بازیابی می‌کند.
دیدن عملکرد در همه پویش‌ها
برای درک عملکرد کلی پویش‌های فروش‌یاری‌تان،
youtube_campaigns_stats_view را پُرسمان کنید.
این نما سنجه‌ها را در همه پویش‌ها، ازجمله نام پویش، تاریخ شروع و پایان، تعداد محتواسازان فعال، و سنجه‌های فروش و تعامل، تجمیع می‌کند.
از عبارت MCQL SELECT زیر برای دریافت ۱۰ پویش برتر براساس سفارش‌ها در ۲۳ آوریل ۲۰۲۶ استفاده کنید:
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
این پُرسمان شناسه پویش، نام پویش، محدوده تاریخ، تعداد محتواسازان فعال، و سنجه‌های عملکرد کلیدی را برای ۱۰ پویش برتر رتبه‌بندی‌شده براساس تعداد کل orders در تاریخ مشخص‌شده بازیابی می‌کند.
دیدن عملکرد پویش براساس محتواساز
برای تجزیه‌وتحلیل عملکرد محتواسازان منفرد شرکت‌کننده در یک پویش خاص،
youtube_individual_campaign_stats_view را پُرسمان کنید.
این نما سنجه‌ها را براساس محتواساز در یک پویش تجمیع می‌کند، ازجمله
عنوان‌های کانال، تعداد ویدیوها، و عنوان‌های محصول برچسب‌گذاری‌شده.
از عبارت MCQL زیر SELECT برای دریافت ۱۰ محتواساز برتر براساس بازدید برای یک پویش خاص در ۲۳ آوریل ۲۰۲۶ استفاده کنید:
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
این پُرسمان عنوان کانال محتواساز، تعداد ویدیوها، عناوین محصولات، و سنجه‌های کلیدی عملکرد را برای ۱۰ محتواساز برتر که براساس کل بازدیدها در پویش و تاریخ مشخص‌شده رتبه‌بندی شده‌اند بازیابی می‌کند.
دیدن عملکرد پویش براساس ویدیو
برای دیدن عملکرد ویدیوهای محتواساز خاص در پویش،
youtube_campaign_videos_stats_view را پُرسمان کنید.
این نما سنجه‌های عملکرد در سطح ویدیو را برای محتواساز در پویش ارائه می‌دهد، ازجمله عنوان ویدیو، قالب ویدیو، و محصولات برچسب‌گذاری‌شده.
از عبارت MCQL SELECT زیر برای دریافت ۱۰ ویدیو برتر براساس بازدید برای یک محتواساز و پویش خاص در ۲۰ مه ۲۰۲۶ استفاده کنید:
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)،
عنوان‌های محصول برچسب‌گذاری‌شده، و سنجه‌های کلیدی عملکرد را برای ۱۰ ویدیو برتر
که براساس تعداد کل views برای کانال، پویش، و تاریخ محتواساز مشخص‌شده رتبه‌بندی شده‌اند بازیابی می‌کند.
دیدن عملکرد پویش به‌تفکیک محصول
برای درک عملکرد محصولات منفرد در یک پویش،
youtube_campaign_products_stats_view را پُرسمان کنید.
این نما سنجه‌های عملکرد در سطح محصول را در پویش ارائه می‌دهد،
ازجمله عنوان محصول، جزئیات ویدیو مرتبط، و سنجه‌های فروش.
از عبارت MCQL SELECT زیر برای دریافت ۱۰ محصول برتر براساس بازدید برای یک پویش خاص در ۲۰ ژوئن ۲۰۲۶ استفاده کنید:
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
این پُرسمان عنوان کانال محتواساز، عنوان محصول، عنوان ویدیو، نشانی وب ویدیو، و سنجه‌های کلیدی عملکرد را برای ۱۰ محصول برتر که براساس تعداد کل 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.
-
- تأخیر: تأخیر پرسمان‌ها به حجم داده‌های درخواست‌شده بستگی دارد. پُرسمان‌هایی که مجموعه‌های داده بزرگ را پوشش می‌دهند بیشتر طول می‌کشند و ممکن است باعث اتمام زمان شوند.