إحصاءات صنّاع المحتوى في YouTube

ملاحظة: تتوفّر هذه الميزة في إصدار تجريبي، وهي متاحة فقط للمطوّرين المدرَجين في القائمة المسموح بها.

يمكنك التعرّف على صنّاع المحتوى في YouTube والحصول على إحصاءات عنهم باستخدام ميزة "إحصاءات صنّاع المحتوى" في ContentCreatorInsightsService. تساعد هذه الخدمة الوكالات والمعلنين في العثور على صنّاع محتوى مناسبين لجمهورهم المستهدف.

تتضمّن واجهة برمجة التطبيقات أربع وظائف رئيسية:

1. قابلية العثور على صنّاع المحتوى: يمكنك العثور على صنّاع محتوى مناسبين لمجموعة معيّنة من المواضيع أو الخصائص الديمغرافية أو شرائح الجمهور أو سمات صنّاع المحتوى.
2. إحصاءات حول مواضيع صنّاع المحتوى: يمكنك الحصول على إحصاءات حول صنّاع المحتوى الذين يقدّمون فيديوهات حول مواضيع محدّدة.
3. إحصاءات صنّاع المحتوى: يمكنك الحصول على إحصاءات حول قنوات معيّنة على YouTube، مثل عدد المشتركين وعدد المشاهدات والخصائص الديمغرافية للجمهور.
4. إحصاءات حول المواضيع الرائجة: يمكنك الحصول على إحصاءات حول مواضيع رائجة معيّنة، استنادًا إلى شرائح جمهور أو مواضيع محدّدة.

يمكن العثور على صنّاع المحتوى المحليين (أي صنّاع المحتوى المقيمين في بلد معيّن أو الذين ينشرون محتواهم من بلد معيّن ويشاهدهم الجمهور في ذلك البلد) من خلال ميزة "اكتشاف صنّاع المحتوى" المستندة إلى المواضيع أو من خلال طلب بيانات تكميلية في "إحصاءات المحتوى الرائج". يمكنك أيضًا طلب إحصاءات حول الآراء المتعلقة بالعلامة التجارية للحصول على إحصاءات حول المواضيع الرائجة من خلال طلب بيانات تكميلية.

متطلبات الأهلية

‫GenerateCreatorInsights هو مكوّن خاص من Google Ads API يتم تقديمه بموجب ترخيص بيانات غير حصري وغير خاضع لحقوق الملكية. يمكن للشركاء الذين وقّعوا على الاتفاقية استخدام مكتبات عملاء "إعلانات Google" العادية لاستكشاف صنّاع المحتوى والفيديوهات على YouTube. ليكون الشركاء مؤهَّلين، يجب أن يستوفوا الشروط التالية:

• أن يكون لديك أداة تخطيط أو واجهة مستخدم تتكامل مع Google Ads API
• استخدِم واجهة برمجة التطبيقات لاستكشاف محتوى YouTube وصنّاع المحتوى بحثًا عن فرص إعلانية محتملة.
• أكمِل تقييم الفحص المسبق لإثبات أهليتك.
• اتّباع متطلبات استخدام البيانات والخضوع لعمليات تدقيق دورية للبيانات
• قبول بنود خدمة Google Ads API وسياسة استخدام البيانات المرتبطة بها

يُرجى التواصل مع ممثل عن Google لمزيد من المعلومات.

إنشاء إحصاءات صانع المحتوى

لإنشاء إحصاءات حول صنّاع المحتوى، أرسِل طلبًا إلى طريقة GenerateCreatorInsights. يبلغ الحد الأقصى لهذه الطريقة 5 طلبات في الثانية (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. تعرض واجهة برمجة التطبيقات إحصاءات حول هذه القنوات المحدّدة.

مجموعات الجمهور المعقّدة

في كل من 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. المجموعة 1 التي تحتوي على سمات كيانات "الرسم البياني المعرفي" لـ "Skin care" و"Hair care"
2. المجموعة 2 التي تحتوي على سمة كيان "الرسم البياني المعرفي" لـ "Cosmetics" (مثل /m/014trl).

ملاحظة: إذا حدّدت كيانات في "الرسم البياني المعرفي" أو فئات المنتجات والخدمات أو اهتمامات المستخدمين في audience_combinations، لا يمكنك أيضًا تحديد أنواع السمات هذه في audience_attributes. لا يزال بإمكانك استخدام audience_attributes لفلاتر الخصائص الديمغرافية (مثل العمر والجنس) إلى جانب audience_combinations.

البيانات التكميلية وصنّاع المحتوى المحليون

بشكل تلقائي، يتم عرض بيانات الإحصاءات الأساسية فقط. يمكنك طلب ميزات اختيارية وبيانات إضافية في الردّ من خلال ضبط الحقل المتكرّر supplemental_data.

على سبيل المثال، يمكنك طلب بيانات صانع المحتوى المحلي من خلال إضافة قيمة التعداد LOCAL_CREATOR_DATA إلى supplemental_data. إذا بحثت عن صنّاع محتوى باستخدام search_topics (وكان الموضوع كيانًا في "الرسم البياني المعرفي" تم وضع علامة عليه باستخدام الإمكانية CREATOR_TOPIC_INSIGHTS)، ستملأ واجهة برمجة التطبيقات الحقل 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 على ما يلي:

• عدد المشتركين والمشاهدات والفيديوهات
• إجمالي عدد المعجبين والمشاركات والتعليقات على مستوى كل فيديوهات القناة
• نسبة التفاعل منذ البداية (إجمالي التفاعل مقسومًا على إجمالي عدد المشاهدات)
• متوسط عدد المشاهدات والمعجبين والمشاركات والتعليقات لكل فيديو خلال آخر 28 يومًا
• مشاهدات Shorts وعدد الفيديوهات
• ما إذا كان صانع فيديوهات Shorts نشطًا أو صانع بث مباشر نشطًا (نشر فيديو واحدًا في آخر 90 يومًا)
• فرص عقد شراكة

نسبة التفاعل ومتوسط عدد المشاهدات والمعجبين والتعليقات لكل فيديو هي مقاييس غير علنية لا تظهر إلا عندما يوافق صانع المحتوى على مشاركتها.

للتحقّق مما إذا كان صانع المحتوى مؤهلاً لعقد شراكات لإنشاء محتوى مرتبط بعلامة تجارية، يُرجى فحص partnership_opportunities. يكون صانع المحتوى مؤهلاً إذا كانت القائمة تحتوي على CREATOR_PARTNERSHIPS.

يحتوي العنصر YouTubeChannelInsights على المعلومات التالية حول قناة على YouTube:

• اسم القناة ومعرّفها واسمها المعرِّف وعنوان URL الخاص بها ووصفها وعنوان URL الخاص بالصورة المصغّرة
• تاريخ إنشاء القناة والبلد المرتبط بها
• مقاييس القناة
• سمات جمهور القناة (مثل العمر والجنس وتفاصيل اهتمامات المستخدمين)
• سمات القناة (السمات المرتبطة بمحتوى القناة)
• الفيديوهات الأفضل أداءً
• نوع القناة ولغات المحتوى
• نتيجة مدى الصلة بالموضوع (لعمليات البحث عن المواضيع الرائجة فقط)
• ما إذا كان صانع المحتوى قد وافق على مشاركة المقاييس غير العلنية

مرجع الطلبات والردود في GenerateCreatorInsights

اتصل بالرقم GenerateCreatorInsights في ContentCreatorInsightsService على نقطة النهاية التالية:

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

يلخّص الجدول التالي الحقول في GenerateCreatorInsightsRequest:

مسار الحقل	المتطلبات	التنسيق والقيود
customer_id	مطلوب	رقم تعريف العميل المكوّن من 10 أرقام (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 والمتوسطات لكل فيديو على مدار 28 يومًا (average_views_per_video وaverage_likes_per_video وaverage_shares_per_video وaverage_comments_per_video).

أمثلة على طلبات واستجابات REST في GenerateCreatorInsights

يستكشف المثال التالي صنّاع المحتوى باستخدام 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. يبلغ الحد الأقصى لهذه الطريقة 5 طلبات في الثانية (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 المدمجة بالبيانات الوصفية على مستوى الفيديو (عنوان URL وعنوان URL للصورة المصغّرة وعدد المشاهدات وعدد المعجبين) والبيانات الوصفية على مستوى القناة (معرّف القناة واسمها وعنوان URL الخاص بها).
• ‫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	مطلوب	رقم تعريف العميل المكوّن من 10 أرقام (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	المقاييس خلال فترة المقارنة التي تبلغ 3 أشهر (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 Issue Tracker

يمكنك استخدام Issue Tracker من Google لطرح أسئلة حول الدعم أو الإبلاغ عن الأخطاء أو إرسال طلبات الميزات. تتتبّع Google طلباتك وتحدّد أولوياتها وتنشر آخر المعلومات عنها مباشرةً في Issue Tracker. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء مشكلة في Google Issue Tracker.

أنشئ مشكلة باستخدام أحد نماذج Issue Tracker التالية:

• طرح سؤال عام حول الدعم أو إرسال ملاحظات بشأن المستندات
• الإبلاغ عن خطأ فني
• إرسال طلب ميزة في واجهة برمجة التطبيقات

املأ جميع الحقول في النموذج بمعلومات تفصيلية حتى تتمكّن Google من إعادة إنشاء طلبك وتحديد أولويته. قد تغلق Google البلاغات غير المكتملة وتطلب منك إرسال بلاغ جديد يتضمّن التفاصيل الناقصة.