اطلاعات آماری محتواساز YouTube

توجه: این ویژگی در مرحله بتا است و فقط برای توسعه‌دهندگان موجود در فهرست مجاز دردسترس است.

با ویژگی اطلاعات آماری محتواساز در ContentCreatorInsightsService، اطلاعات آماری درباره محتواسازان YouTube را کاوش و دریافت کنید. این سرویس به آژانس‌ها و تبلیغ‌کنندگان کمک می‌کند تا محتواسازانی را پیدا کنند که با مخاطبان هدف آن‌ها مرتبط هستند.

این میانای برنامه‌سازی کاربردی چهار عملکرد اصلی دارد:

1. یافت‌پذیری محتواساز: محتواسازان مرتبط را برای مجموعه‌ای از موضوعات، جمعیت‌شناسی، مخاطبان، یا مشخصه‌های محتواساز پیدا کنید.
2. اطلاعات آماری موضوع محتواساز: اطلاعات آماری درباره محتواسازان مرتبطی که درباره موضوعات مشخص‌شده محتوا می‌سازند واکشی کنید.
3. اطلاعات آماری محتواساز: اطلاعات آماری درباره کانال‌های خاص YouTube، مانند تعداد مشترکان، تعداد بازدیدها، و جمعیت‌شناسی مخاطبان را واکشی کنید.
4. اطلاعات آماری پرطرفدار: اطلاعات آماری درباره گرایش‌های خاص را براساس مخاطبان یا موضوعات خاص واکشی کنید.

کاوش محتواسازان محلی (پیدا کردن محتواسازانی که در کشور خاصی مستقر هستند یا از آن کشور پست می‌کنند و در آن کشور دیده می‌شوند) هنگام استفاده از کاوش محتواسازان موضوع‌محور یا اطلاعات آماری پرطرفدار با درخواست داده‌های تکمیلی پشتیبانی می‌شود. همچنین می‌توانید با درخواست داده‌های تکمیلی، اطلاعات آماری احساسات نمانام را برای اطلاعات آماری پرطرفدار موضوع‌محور درخواست کنید.

شرایط صلاحیت

GenerateCreatorInsights مؤلفه‌ای خصوصی از Google Ads API است که با پروانه داده غیرانحصاری و بدون بهره مالکانه ارائه می‌شود. شرکای امضاکننده می‌توانند از کتابخانه‌های مشتری Google Ads استاندارد برای کاوش محتواسازان و محتوای YouTube استفاده کنند. برای واجدشرایط بودن، شرکا باید شرایط زیر را برآورده کنند:

• ابزار برنامه‌ریزی یا میانای کاربری داشته باشید که Google Ads API را ادغام کند.
• از API برای کاوش محتوا و محتواسازان YouTube برای فرصت‌های تبلیغاتی بالقوه استفاده کنید.
• برای تأیید واجدشرایط بودن، ارزیابی پیش‌غربالگری را تکمیل کنید.
• الزامات استفاده از داده را رعایت کنید و تحت ممیزی‌های دوره‌ای داده قرار بگیرید.
• شرایط خدمات Google Ads API و خط‌مشی استفاده از داده‌های مرتبط را بپذیرید.

برای کسب اطلاعات بیشتر با نماینده Google تماس بگیرید.

تولید کردن اطلاعات آماری محتواساز

برای تولید اطلاعات آماری محتواساز، درخواستی به روش GenerateCreatorInsights ارسال کنید. این روش دارای محدودیت ۵ پُرسمان در ثانیه (QPS) است. این نقطه پایان بسته به اینکه به‌دنبال قابلیت پیدا شدن محتواساز، جستجوی محتواساز براساس موضوع، یا اطلاعات آماری محتواساز مختص کانال باشید، معیارهای مختلفی را می‌پذیرد. باید مکان‌های کشور هدف را در country_locations ارائه کنید.

1. قابلیت کشف محتواساز (search_attributes): فهرستی از ویژگی‌های مخاطب (مانند سن، جنسیت، و علایق کاربر (مخاطبان هم‌گرا، واقعی بازار، و رویدادهای زندگی)) را بااستفاده از فیلد search_attributes ارائه دهید تا محتواسازانی را که مخاطبانشان با این ویژگی‌ها مطابقت دارند پیدا کنید. همچنین می‌توانید مشخصه‌های محتواساز را ارائه دهید تا محتواسازانی را که محتوایشان با مشخصه‌های خاصی مطابقت دارد فیلتر کنید.

   بااستفاده از ListAudienceInsightsAttributes و با مشخص کردن ابعاد موردنیازتان، مثلاً KNOWLEDGE_GRAPH برای موضوعات موردعلاقه، مشخصه‌های مخاطب دردسترس را بازیابی کنید. برای ترکیب کردن مشخصه‌ها بااستفاده از گروه‌های بولی AND و OR، از audience_combinations همان‌طور که در ترکیب‌های پیچیده مخاطب شرح داده شده است استفاده کنید.

2. بینش‌های تحلیلی موضوع محتواساز (search_topics): فهرستی از موضوعات محتوا را بااستفاده از فیلد search_topics ارائه دهید. میانای برنامه‌سازی کاربردی محتواسازان مرتبطی را که درباره موضوعات مشخص‌شده محتوا می‌سازند برمی‌گرداند. داده‌ها برای کشور مشخص‌شده در country_locations واکشی می‌شود (این گزینه از یک کشور در هر درخواست پشتیبانی می‌کند).

   نهادهای پشتیبانی‌شده در search_topics باید با قابلیت CONTENT_TRENDING_INSIGHTS یا CREATOR_TOPIC_INSIGHTS برچسب‌گذاری شوند. از ListAudienceInsightsAttributes برای بازیابی قابلیت‌های موجودیت پشتیبانی‌شده استفاده کنید.

   توجه: گزینه search_brand در v24 منسوخ شد و در v25 برداشته شد. درعوض از search_topics استفاده کنید.

3. اطلاعات آماری محتواساز (search_channels): فهرستی از شناسه‌های کانال YouTube، نام‌های کاربری کانال YouTube (youtube_channel_handles، دردسترس در v25 و نسخه‌های جدیدتر)، یا ترکیبی از هر دو را بااستفاده از فیلد search_channels ارائه دهید. ‫API اطلاعات آماری درباره آن کانال‌های خاص را برمی‌گرداند.

ترکیب‌های پیچیده مخاطب

در هر دو GenerateCreatorInsights و GenerateTrendingInsights، می‌توانید روابط پیچیده مشخصه مخاطب را بااستفاده از audience_combinations تعریف کنید. این فیلد به شما امکان می‌دهد مشخصه‌های مخاطب را با منطق بولی (AND و OR) فراتر از رفتار اجتماع مسطح (OR) audience_attributes ترکیب کنید:

• هر InsightsAudienceAttributeGroup در audience_combinations مشخصه‌هایش را با OR منطقی ترکیب می‌کند.
• چندین مورد InsightsAudienceAttributeGroup در audience_combinations با AND منطقی ترکیب شده‌اند.

برای مثال، برای هدف‌یابی مخاطبان علاقه‌مند به ("Skin care" OR "Hair care") AND "Cosmetics"، دو مورد InsightsAudienceAttributeGroup در audience_combinations اضافه کنید:

1. گروه ۱ حاوی مشخصه‌های نهاد «گنجینهٔ دانش» برای "Skin care" و "Hair care".
2. گروه ۲ حاوی مشخصه نهاد «گنجینهٔ دانش» برای "Cosmetics" (مثل /m/014trl).

توجه: اگر نهادهای «گراف دانش»، «دسته‌های محصول و خدمات»، یا علایق کاربر را در audience_combinations مشخص کنید، نمی‌توانید آن انواع مشخصه را در audience_attributes نیز مشخص کنید. همچنان می‌توانید از audience_attributes برای فیلترهای جمعیت‌شناسی (مانند سن و جنسیت) درکنار audience_combinations استفاده کنید.

داده‌های تکمیلی و محتواسازان محلی

به‌طور پیش‌فرض، فقط داده‌های اطلاعات آماری اصلی برگردانده می‌شود. با تنظیم فیلد تکراری supplemental_data می‌توانید ویژگی‌های اختیاری و داده‌های اضافی را در پاسخ خود درخواست کنید.

برای مثال، می‌توانید با افزودن مقدار شمارشی LOCAL_CREATOR_DATA به supplemental_data، داده‌های محتواساز محلی را درخواست کنید. اگر بااستفاده از search_topics محتواسازان را جستجو کنید (و موضوع یک موجودیت «گراف دانش» باشد که با قابلیت CREATOR_TOPIC_INSIGHTS برچسب‌گذاری شده است)، API فیلد local_creator_insights را در پاسخ با محتواسازان محلی که با هم‌رسانی داده‌های مکانشان موافقت کرده‌اند پر می‌کند.

برای کاوش محتواسازان محلی، مشخصات زیر را درنظر داشته باشید:

• تعریف: محتواسازان محلی محتواسازانی هستند که در کشور انتخاب‌شده مستقر هستند یا از آن کشور پست می‌کنند و در آن کشور دیده می‌شوند.
• محدودیت: وقتی sub_country_locations در درخواست تنظیم شده باشد، کاوش محتواسازان محلی پشتیبانی نمی‌شود.
• قابلیت‌ها: می‌توانید فهرست نهادهای پشتیبانی‌شده «گنجینه دانش» و قابلیت‌های آن‌ها را بااستفاده از ListAudienceInsightsAttributes بازیابی کنید.

روش GenerateCreatorInsights یک شیء GenerateCreatorInsightsResponse برمی‌گرداند که شامل فیلدهای زیر است:

• creator_insights: فهرستی از YouTubeCreatorInsights شیء که با معیارهای اصلی شما مطابقت دارد.
• local_creator_insights: فهرستی از اشیاء YouTubeCreatorInsights برای محتواسازان محلی. این فقط زمانی پُر می‌شود که LOCAL_CREATOR_DATA درخواست شده باشد و معیار استفاده‌شده search_topics باشد.

هر شیء YouTubeCreatorInsights حاوی موارد زیر است:

• creator_name: نام سازنده.
• ‫creator_channels: فهرستی از YouTubeChannelInsights شیء. جزئیات کانال و channel_metrics (YouTubeMetrics) در داخل هر شیء YouTubeChannelInsights در creator_channels برگردانده می‌شوند.

شیء YouTubeMetrics حاوی موارد زیر است:

• تعداد مشترکان، بازدیدها، و ویدیوها
• تعداد کل پسندیدن‌ها، هم‌رسانی‌ها، و نظرات در همه ویدیوهای کانال
• نرخ تعامل از ابتدا (مجموع تعامل تقسیم بر مجموع بازدیدها)
• میانگین بازدیدها، پسندیدن‌ها، هم‌رسانی‌ها، و نظرات به‌ازای هر ویدیو در ۲۸ روز گذشته
• تعداد بازدید و ویدیوهای «کوته‌ویدیوهای YouTube»
• اینکه محتواساز یک محتواساز فعال «کوته‌ویدیوها» یا یک محتواساز فعال جاری‌سازی زنده است (یک مورد در ۹۰ روز گذشته منتشر کرده است)
• فرصت‌های مشارکت

نرخ تعامل و میانگین بازدیدها، پسندیدن‌ها، و نظرات برای هر ویدیو سنجه‌های غیرعمومی هستند که فقط زمانی تکمیل می‌شوند که محتواساز با هم‌رسانی آن‌ها موافقت کرده باشد.

برای بررسی اینکه آیا محتواساز واجدشرایط مشارکت در محتوای نمانام‌دار اصلی است یا نه، partnership_opportunities را بررسی کنید؛ اگر فهرست حاوی CREATOR_PARTNERSHIPS باشد، محتواساز واجدشرایط است.

شیء YouTubeChannelInsights حاوی اطلاعات زیر درباره کانال YouTube است:

• نام، شناسه، نام کاربری، نشانی وب، شرح، و نشانی وب ریزعکس کانال
• تاریخ ایجاد کانال و کشور مرتبط
• سنجه‌های کانال
• مشخصه‌های مخاطبان کانال (مانند سن، جنسیت، و تفکیک علایق کاربر)
• مشخصه‌های کانال (مشخصه‌های مرتبط با محتوای کانال)
• ویدیوهای برتر
• نوع کانال و زبان‌های محتوا
• امتیاز ارتباط (فقط برای جستجوهای گرایش موضوع)
• آیا محتواساز برای هم‌رسانی سنجه‌های غیرعمومی رضایت داده است یا نه

مرجع درخواست و پاسخ GenerateCreatorInsights

فراخوانی GenerateCreatorInsights در ContentCreatorInsightsService در نقطه پایانی زیر:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

جدول زیر فیلدهای موجود در GenerateCreatorInsightsRequest را خلاصه می‌کند:

راه در مزرعه	الزام	قالب و محدودیت‌ها
customer_id	الزامی	شناسه مشتری ۱۰ رقمی (string) بدون خط تیره.
customer_insights_group	الزامی	نام تعریف‌شده توسط کاربر (string) برای مشتری یا نمانامی که برای آن برنامه‌ریزی می‌شود.
country_locations[]	الزامی	فهرست اشیاء LocationInfo کشور (geo_target_constant، مانند "geoTargetConstants/2840"). وقتی از search_topics استفاده می‌شود، باید شامل یک کشور باشد.
sub_country_locations[]	اختیاری	فیلترهای LocationInfo زیرکشور؛ فقط با search_attributes پشتیبانی می‌شود و با LOCAL_CREATOR_DATA ناسازگار است.
search_attributes	‫criteria‏ (oneof)	SearchAttributes حاوی: • audience_attributes[]: age_range، gender، device، parental_status، income_range (به‌علاوه user_interest، entity، یا category وقتی audience_combinations استفاده نشده باشد). • ‫audience_combinations[]: AND-of-ORs InsightsAudienceAttributeGroup مورد. • ‫creator_attributes[]: entity مورد «گنجینه دانش» با قابلیت CREATOR_ATTRIBUTE.
search_topics	‫criteria‏ (oneof)	SearchTopics حاوی entities[] (AudienceInsightsEntity با knowledge_graph_machine_id برچسب‌گذاری‌شده با CREATOR_TOPIC_INSIGHTS یا CONTENT_TRENDING_INSIGHTS).
search_channels	‫criteria‏ (oneof)	YouTubeChannels حاوی youtube_channels[] (channel_id) و/یا youtube_channel_handles[] (نام‌های کاربری که با @ شروع می‌شوند، مثل "@youtubecreators").
supplemental_data[]	اختیاری	ContentCreatorInsightsSupplementalData مقدار. ‫LOCAL_CREATOR_DATA را در درخواست search_topics تک‌کشوری (برای نهادهای دارای CREATOR_TOPIC_INSIGHTS) تنظیم کنید تا local_creator_insights[] تکمیل شود.
insights_application_info	اختیاری	AdditionalApplicationInfo فراداده درباره برنامه‌ای که درخواست را صادر می‌کند.

پیام GenerateCreatorInsightsResponse فیلدهای زیر را برمی‌گرداند:

فیلد پاسخ	نوع	شرح
creator_insights[]	YouTubeCreatorInsights	محتواسازانی که با معیارهای اصلی شما (creator_name و creator_channels[]) مطابقت دارند.
local_creator_insights[]	YouTubeCreatorInsights	محتواسازان محلی که با هم‌رسانی داده‌های مکان موافقت کرده‌اند (وقتی LOCAL_CREATOR_DATA با search_topics در نهادی با CREATOR_TOPIC_INSIGHTS درخواست شود، تکمیل می‌شود).
creator_channels[]	YouTubeChannelInsights	فراداده: display_name، youtube_channel.channel_id، handle، channel_url، publish_date، country_location، و data_sharing_consent_given. اطلاعات آماری و محتوا: channel_audience_attributes[] (محدود به رضایت)، channel_attributes[]، top_videos[]، language_distributions[]، relevance_score (فقط برای GenerateTrendingInsights با search_topics پر شده است)، و channel_metrics.
channel_metrics	YouTubeMetrics	سنجه‌های عمومی: subscriber_count،‏ views_count،‏ video_count،‏ likes_count،‏ shares_count،‏ comments_count،‏ shorts_views_count،‏ shorts_video_count،‏ is_active_shorts_creator،‏ is_active_live_stream_creator، و partnership_opportunities[]. سنجه‌های نیازمند رضایت: engagement_rate و میانگین‌های ۲۸ روزه برای هر ویدیو (average_views_per_video،‏ average_likes_per_video،‏ average_shares_per_video،‏ average_comments_per_video).

GenerateCreatorInsights نمونه‌های درخواست و پاسخ REST

مثال زیر محتواسازانی را که از searchAttributes با جمعیت‌شناسی audienceAttributes، بولی audienceCombinations ("Skin care" OR "Hair care"، AND "Cosmetics")، و creatorAttributes استفاده می‌کنند پیدا می‌کند:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "searchAttributes": {
    "audienceAttributes": [
      {
        "ageRange": {
          "type": "AGE_RANGE_25_34"
        }
      },
      {
        "gender": {
          "type": "FEMALE"
        }
      }
    ],
    "audienceCombinations": [
      {
        "attributes": [
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/015c4z"
            }
          },
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/018bb_"
            }
          }
        ]
      },
      {
        "attributes": [
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/014trl"
            }
          }
        ]
      }
    ],
    "creatorAttributes": [
      {
        "entity": {
          "knowledgeGraphMachineId": "/m/014trl"
        }
      }
    ]
  }
}

برای واکشی محتواسازان موضوع‌محور به‌همراه محتواسازان محلی، از searchTopics استفاده کنید و "LOCAL_CREATOR_DATA" را در supplementalData قرار دهید:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "supplementalData": [
    "LOCAL_CREATOR_DATA"
  ],
  "searchTopics": {
    "entities": [
      {
        "knowledgeGraphMachineId": "/m/014trl"
      }
    ]
  }
}

برای واکشی اطلاعات آماری کانال‌های خاص YouTube براساس شناسه یا نام کاربری کانال، از searchChannels استفاده کنید:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "searchChannels": {
    "youtubeChannels": [
      {
        "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
      }
    ],
    "youtubeChannelHandles": [
      "@exampleskincare"
    ]
  }
}

GenerateCreatorInsightsResponse موفق این موارد را برمی‌گرداند creatorInsights[] (و localCreatorInsights[] وقتی LOCAL_CREATOR_DATA درخواست شده باشد):

{
  "creatorInsights": [
    {
      "creatorName": "Example Skincare Creator",
      "creatorChannels": [
        {
          "displayName": "Example Skincare Channel",
          "youtubeChannel": {
            "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
          },
          "channelUrl": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
          "handle": "@exampleskincare",
          "publishDate": "2020-03-15",
          "countryLocation": {
            "geoTargetConstant": "geoTargetConstants/2840"
          },
          "dataSharingConsentGiven": true,
          "channelMetrics": {
            "subscriberCount": "450000",
            "viewsCount": "38200000",
            "videoCount": "210",
            "likesCount": "1950000",
            "commentsCount": "84000",
            "engagementRate": 0.056,
            "averageViewsPerVideo": 62000.0,
            "shortsViewsCount": "14500000",
            "shortsVideoCount": "95",
            "isActiveShortsCreator": true,
            "isActiveLiveStreamCreator": false,
            "partnershipOpportunities": [
              "CREATOR_PARTNERSHIPS",
              "PARTNERSHIP_ADS"
            ]
          }
        }
      ]
    }
  ],
  "localCreatorInsights": []
}

تولید کردن اطلاعات آماری پرطرفدار

برای تولید اطلاعات آماری پرطرفدار، درخواستی به روش GenerateTrendingInsights ارسال کنید. این روش دارای محدودیت ۵ پُرسمان در ثانیه (QPS) است. این نقطه پایانی دو نوع ورودی را می‌پذیرد، بسته به اینکه گرایش‌های مخاطب را می‌خواهید یا گرایش‌های موضوعی، و به مکان کشور هدف نیاز دارد.

1. روندهای مخاطب (search_audience): فهرستی از مشخصه‌های مخاطب (مانند سن، جنسیت، و علایق کاربر) را در فیلد audience_attributes از search_audience ارائه دهید و، به‌صورت اختیاری، از audience_combinations برای ترکیب مشخصه‌ها با منطق بولی AND/OR استفاده کنید. میانای برنامه‌سازی کاربردی فهرستی از اطلاعات آماری پرطرفدار برای آن مخاطبان برمی‌گرداند، ازجمله سنجه‌هایی مثل درصد تغییر در مقدار گرایش درطول دوره مقایسه.

   توسعه‌دهندگانی که به ContentCreatorInsightsService دسترسی دارند، به‌طور خودکار به ListAudienceInsightsAttributes در AudienceInsightsService دسترسی دارند (به راهنمای اطلاعات آماری مخاطب مراجعه کنید). سایر نقاط پایانی در AudienceInsightsService به فهرست مجازهای جداگانه‌ای نیاز دارند.

2. روندهای موضوع (search_topics): فهرستی از موضوعات محتوا را در فیلد search_topics ارائه دهید. میانای برنامه‌سازی کاربردی اطلاعات آماری پرطرفدار را برای آن موضوعات برمی‌گرداند، ازجمله درصد تغییر در مقدار گرایش درطول دوره مقایسه. همچنین می‌توانید با تنظیم supplemental_data، اطلاعات آماری درباره محتواسازان محلی یا احساسات نسبت به نمانام را درخواست کنید.

   KNOWLEDGE_GRAPH مشخصه برگردانده‌شده توسط ListAudienceInsightsAttributes شامل یک یا چند برچسب InsightsKnowledgeGraphEntityCapabilities است؛ نهادهای برچسب‌گذاری‌شده با CONTENT_TRENDING_INSIGHTS به‌عنوان موضوع در GenerateTrendingInsights پشتیبانی می‌شوند.

داده‌های تکمیلی و محتواسازان محلی

مشابه تولید اطلاعات آماری محتواساز، می‌توانید با تنظیم فیلد تکراری supplemental_data روی LOCAL_CREATOR_DATA یا BRAND_SENTIMENT_DATA، ویژگی‌های اختیاری را در اطلاعات آماری پرطرفدار درخواست کنید:

• محتواسازان محلی (LOCAL_CREATOR_DATA): وقتی درخواست پرطرفدار شما از search_topics استفاده می‌کند (و موضوع یک موجودیت «گراف دانش» است که با قابلیت CREATOR_TOPIC_INSIGHTS برچسب‌گذاری شده است)، تنظیم supplemental_data روی LOCAL_CREATOR_DATA فیلد related_local_creators را در اشیاء TrendInsight برگردانده‌شده با محتواسازان محلی مرتبطی که با هم‌رسانی داده‌های مکانشان موافقت کرده‌اند پر می‌کند. کاوش محتواسازان محلی با sub_country_locations ناسازگار است.
• احساسات نمانام (BRAND_SENTIMENT_DATA): وقتی درخواست پرطرفدار شما از search_topics استفاده می‌کند و موضوع نهاد گنجینهٔ دانش درخواست‌شده دارای قابلیت BRAND است، تنظیم supplemental_data روی BRAND_SENTIMENT_DATA فیلد brand_sentiment_insights را در اشیای TrendInsight برگردانده‌شده پر می‌کند.

سنجش احساسات نمانام از مدل‌های هوش مصنوعی Gemini برای تجزیه‌وتحلیل محتوای ویدیو YouTube مرتبط با نمانام استفاده می‌کند و احساسات را به‌عنوان مثبت، منفی، یا خنثی دسته‌بندی می‌کند. فقط خود محتوای ویدیو تجزیه‌وتحلیل می‌شود؛ نظرات کاربر لحاظ نمی‌شود.

فراداده‌های اطلاعات آماری پرطرفدار

روش GenerateTrendingInsights فهرستی از اشیاء TrendInsight را برمی‌گرداند که هرکدام حاوی موارد زیر است:

• ‫trend_attribute: AudienceInsightsAttributeMetadata اصلی برای روند.
• ‫trend_metrics: سنجه‌های گرایش، مثل درصد تغییر درطول دوره مقایسه.
• trend: مقدار InsightsTrend (EMERGING،‏ RISING،‏ SUSTAINED، یا DECLINING) که جهت روند را نشان می‌دهد. برای اندازه تغییر، trend_metrics.trend_change_percent را ببینید.
• trend_data_points: نقاط داده‌های قدیمی برای روند. فقط برای گرایش‌هایی که از search_topics استفاده می‌کنند درج می‌شود.
• related_videos: فهرستی از AudienceInsightsAttributeMetadata شیء برای ویدیوهای پرطرفدار مرتبط با موضوع پرطرفدار (فقط برای موارد پرطرفدار بااستفاده از search_topics پر می‌شود). برای این مشخصه‌ها، YouTubeVideoAttributeMetadata تودرتو با فراداده سطح ویدیو (نشانی وب، نشانی وب ریزعکس، تعداد بازدید و پسندیدن) و فراداده سطح کانال (شناسه کانال، نام، و نشانی وب) پر می‌شود.
• related_creators: فهرستی از YouTubeCreatorInsights شیء برای محتواسازان مرتبط با موضوع گرایش (فقط برای گرایش‌هایی که از search_topics استفاده می‌کنند پر می‌شود).
• related_local_creators: فهرستی از اشیاء YouTubeCreatorInsights برای محتواسازان محلی مرتبط با موضوع پرطرفدار که با هم‌رسانی داده‌های مکانشان موافقت کرده‌اند. فقط زمانی درج می‌شود که LOCAL_CREATOR_DATA درخواست شده باشد (به داده‌های تکمیلی، محتواسازان محلی، و احساسات نمانام مراجعه کنید).
• brand_sentiment_insights: فهرستی از اشیاء BrandSentimentInsight برای روند (زمانی پر می‌شود که درخواست از search_topics برای نهادی با قابلیت BRAND استفاده کند و BRAND_SENTIMENT_DATA را درخواست کند). هر شیء BrandSentimentInsight شامل موارد زیر است:
  • ‫month: ماهی که احساسات نمانام در قالب YYYY-MM نشان می‌دهد.
  • has_insufficient_data: آیا داده‌های کافی برای محاسبه احساسات نمانام وجود دارد یا نه.
  • sentiment_distributions: توزیع رویکرد بین مثبت، منفی، و خنثی که به‌عنوان نسبت بازدیدهای ویدیوهای مربوط به نمانام با هر رویکرد محاسبه می‌شود.
  • sentiment_summaries: خلاصه‌های تولیدشده با هوش مصنوعی از موضوعات مثبت و منفی در محتوای مرتبط با نمانام، به‌همراه ویدیوهای نمونه برای هر احساس. خلاصه‌ها فقط برای احساسات مثبت و منفی تولید می‌شوند، نه خنثی.

مرجع درخواست و پاسخ GenerateTrendingInsights

فراخوانی GenerateTrendingInsights در ContentCreatorInsightsService در نقطه پایانی زیر:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights

جدول زیر فیلدهای موجود در GenerateTrendingInsightsRequest را خلاصه می‌کند:

راه در مزرعه	الزام	قالب و محدودیت‌ها
customer_id	الزامی	شناسه مشتری ۱۰ رقمی (string) بدون خط تیره.
customer_insights_group	الزامی	نام تعریف‌شده توسط کاربر (string) برای مشتری یا نمانامی که برای آن برنامه‌ریزی می‌شود.
country_location	الزامی	یک کشور LocationInfo (geo_target_constant، مثل "geoTargetConstants/2840").
sub_country_locations[]	اختیاری	فیلترهای زیرکشور LocationInfo؛ فقط برای search_audience پشتیبانی می‌شود و با LOCAL_CREATOR_DATA ناسازگار است.
search_audience	‫criteria‏ (oneof)	SearchAudience حاوی: • audience_attributes[] (الزامی): age_range، gender، parental_status، income_range (به‌علاوه user_interest، entity، یا category وقتی audience_combinations استفاده نشده است). • audience_combinations[] (اختیاری): گروه‌های مشخصه AND-of-ORs.
search_topics	‫criteria‏ (oneof)	SearchTopics حاوی entities[] (AudienceInsightsEntity با knowledge_graph_machine_id برچسب‌گذاری‌شده با CONTENT_TRENDING_INSIGHTS).
supplemental_data[]	اختیاری	مقادیر ContentCreatorInsightsSupplementalData: • LOCAL_CREATOR_DATA: related_local_creators[] را برای نهادهای search_topics با CREATOR_TOPIC_INSIGHTS پر می‌کند. • BRAND_SENTIMENT_DATA: brand_sentiment_insights[] را برای نهادهای search_topics با BRAND پر می‌کند.
insights_application_info	اختیاری	AdditionalApplicationInfo فراداده درباره برنامه‌ای که درخواست را صادر می‌کند.

پیام GenerateTrendingInsightsResponse TrendInsight ورودی را در trend_insights[] برمی‌گرداند:

TrendInsight فیلد	نوع	شرح
trend_attribute	AudienceInsightsAttributeMetadata	مشخصه اصلی برای گرایش (dimension، display_name، attribute).
trend_metrics	TrendInsightMetrics	سنجه‌ها درطول دوره مقایسه ۳ ماهه (views_count و views_indexed_value برای search_topics؛ audience_share برای search_audience؛ trend_change_percent).
trend	InsightsTrend	جهت گرایش (EMERGING،‏ RISING،‏ SUSTAINED، یا DECLINING).
trend_data_points[]	TrendInsightDataPoint	داده‌های قدیمی ماهانه (month در قالب YYYY-MM و trend_metrics)؛ برای search_topics پر شده است.
related_videos[]	AudienceInsightsAttributeMetadata	ویدیوهای پرطرفدار با YouTubeVideoAttributeMetadata؛ برای search_topics پر شده است.
related_creators[]	YouTubeCreatorInsights	محتواسازان مرتبط با موضوع؛ برای search_topics پر شده است.
related_local_creators[]	YouTubeCreatorInsights	محتواسازان محلی موافق؛ برای search_topics پر شده است وقتی LOCAL_CREATOR_DATA در نهادی با CREATOR_TOPIC_INSIGHTS درخواست شده است.
brand_sentiment_insights[]	BrandSentimentInsight	احساسات ماهانه نسبت‌به نمانام (month، has_insufficient_data، sentiment_distributions[]، sentiment_summaries[])؛ برای search_topics پر می‌شود وقتی BRAND_SENTIMENT_DATA در نهادی با قابلیت BRAND درخواست شود.

GenerateTrendingInsights نمونه درخواست و پاسخ REST

مثال زیر GenerateTrendingInsights را بااستفاده از searchTopics برای نهاد نمانام «گراف دانش» (/g/11example_brand، برچسب‌گذاری‌شده با CONTENT_TRENDING_INSIGHTS، CREATOR_TOPIC_INSIGHTS، و BRAND) فراخوانی می‌کند و LOCAL_CREATOR_DATA و BRAND_SENTIMENT_DATA را درخواست می‌کند:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocation": {
    "geoTargetConstant": "geoTargetConstants/2840"
  },
  "supplementalData": [
    "LOCAL_CREATOR_DATA",
    "BRAND_SENTIMENT_DATA"
  ],
  "searchTopics": {
    "entities": [
      {
        "knowledgeGraphMachineId": "/g/11example_brand"
      }
    ]
  }
}

GenerateTrendingInsightsResponse موفق TrendInsight ورودی را در trendInsights[] برمی‌گرداند:

{
  "trendInsights": [
    {
      "trendAttribute": {
        "dimension": "KNOWLEDGE_GRAPH",
        "displayName": "Example Skincare Brand",
        "attribute": {
          "entity": {
            "knowledgeGraphMachineId": "/g/11example_brand"
          }
        }
      },
      "trendMetrics": {
        "viewsCount": "18500000",
        "viewsIndexedValue": "82",
        "trendChangePercent": 0.24
      },
      "trend": "RISING",
      "trendDataPoints": [
        {
          "month": "2026-05",
          "trendMetrics": {
            "viewsCount": "18500000",
            "viewsIndexedValue": "82",
            "trendChangePercent": 0.08
          }
        }
      ],
      "brandSentimentInsights": [
        {
          "month": "2026-05",
          "hasInsufficientData": false,
          "sentimentDistributions": [
            {
              "sentiment": "SENTIMENT_POSITIVE",
              "sentimentShare": 0.68
            },
            {
              "sentiment": "SENTIMENT_NEUTRAL",
              "sentimentShare": 0.25
            },
            {
              "sentiment": "SENTIMENT_NEGATIVE",
              "sentimentShare": 0.07
            }
          ]
        }
      ],
      "relatedVideos": [],
      "relatedCreators": [],
      "relatedLocalCreators": []
    }
  ]
}

سامانه پیگیری Google

از Google Issue Tracker برای پرسیدن سؤالات پشتیبانی، گزارش اشکالات، یا ارسال درخواست‌های ویژگی استفاده کنید. Google درخواست‌های شما را مستقیماً در Issue Tracker پیگیری، اولویت‌بندی، و به‌روزرسانی می‌کند. برای اطلاعات بیشتر، ایجاد مشکل در Google Issue Tracker را ببینید.

بااستفاده از یکی از الگوهای Issue Tracker زیر، مشکلی ایجاد کنید:

• پرسیدن سؤال پشتیبانی عمومی یا ارسال بازخورد درباره اسناد
• گزارش کردن اشکال فنی
• ارسال درخواست ویژگی میانای برنامه‌سازی کاربردی

همه فیلدهای الگو را با اطلاعات دقیق تکمیل کنید تا Google بتواند درخواستتان را بازتولید و اولویت‌بندی کند. Google ممکن است گزارش‌های ناقص را ببندد و از شما بخواهد مشکل جدیدی را با جزئیات جاافتاده ارسال کنید.