ربط YouTube

تتيح Google Ads API ربط فيديوهات على YouTube بحسابك على "إعلانات Google". يشرح هذا الدليل كيفية استخدام واجهة برمجة التطبيقات لإضافة روابط إلى حسابك وإزالتها.

ربط الفيديوهات

يمكن ربط الفيديوهات بحسابك بإحدى طريقتَين، حسب الجهة التي تبدأ العملية:

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

يتم استخدام الطرق التالية في كل سيناريو:

السيناريو	الإجراء	الملاحظات
السيناريو 1	الحصول على معلومات الفيديو من YouTube API	استخدِم YouTube API للحصول على channel_id لإرسال طلب ربط الحساب إليه، وvideo_id للفيديو الذي تريد ربطه. ‫video_id هو سلسلة من 11 حرفًا تظهر في عناوين URL الخاصة بفيديوهات على YouTube (على سبيل المثال، المَعلمة v في www.youtube.com/watch?v=VIDEO_ID أو المسار في youtu.be/VIDEO_ID).
	إنشاء طلب ربط حساب	استخدِم طريقة DataLinkService.CreateDataLink لإنشاء طلب ربط حساب، مع تحديد كل من youtube_video.channel_id وyoutube_video.video_id لتحديد الفيديو والقناة المرتبطة به. اعتبارًا من الإصدار 24، يمكنك أيضًا تحديد youtube_link_metadata.brand_channel_id لتقديم معرّف قناة العلامة التجارية المرتبطة على YouTube لمساعدة صنّاع المحتوى في فهم علامتك التجارية. يجب عدم ضبط السمة status في DataLink، لأنّ خادم Google Ads API سيضبطها على REQUESTED بعد إكمال طلب البيانات من واجهة برمجة التطبيقات بنجاح.
	فحص حالة طلب	استخدِم GoogleAdsService.SearchStream أو GoogleAdsService.Search لطلب البحث عن مورد data_link وفحص status.
	إلغاء طلب	استخدِم طريقة DataLinkService.UpdateDataLink لإبطال طلب ربط حساب من خلال تغيير status في DataLink من REQUESTED إلى REVOKED.
	إزالة رابط	استخدِم DataLinkService.RemoveDataLink لإزالة فيديو مرتبط.
السيناريو 2	استرداد دعوة	استخدِم GoogleAdsService.Search أو GoogleAdsService.SearchStream للاستعلام عن مورد data_link. يمكنك الفلترة حسب status = PENDING_APPROVAL للعثور على طلبات ربط الحساب لقبولها أو رفضها.
	قبول طلب ربط حساب أو رفضه	استخدِم طريقة DataLinkService.UpdateDataLink لتعديل حالة DataLink إلى ENABLED لقبول الطلب أو REJECTED لرفضه.

استرداد تفاصيل الرابط

يمكنك استخدام GoogleAdsService.Search أو GoogleAdsService.SearchStream لطلب البحث عن المورد data_link. يستردّ طلب البحث التالي تفاصيل روابط فيديوهات YouTube، بما في ذلك معرّف الفيديو على YouTube ومعرّف القناة:

SELECT
  data_link.resource_name,
  data_link.status,
  data_link.youtube_video.video_id,
  data_link.youtube_video.channel_id
FROM data_link
WHERE data_link.type = 'VIDEO'

يمكن أن تظهر الأخطاء الشائعة التالية في سير العمل هذا:

رمز الخطأ	الشرح
DataLinkError.PERMISSION_DENIED	ليس لدى العميل الإذن لتنفيذ هذا الإجراء.
DataLinkError.YOUTUBE_VIDEO_ID_INVALID	تعذّر إنشاء رابط فيديو لأنّ معرّف الفيديو غير صالح.
DataLinkError.INVALID_STATUS	يتم طرح هذا الاستثناء عندما تكون الحالة الحالية لرابط البيانات غير صالحة للعملية المطلوبة.
DataLinkError.INVALID_UPDATE_STATUS	يتم عرض هذا الخطأ عند محاولة إجراء عملية انتقال غير متاحة للحالة أثناء التعديل (على سبيل المثال، الانتقال مباشرةً من REVOKED إلى ENABLED).
MutateError.RESOURCE_ALREADY_EXISTS	يتم طرح هذا الاستثناء عندما يكون رابط البيانات للفيديو موجودًا من قبل.