تتيح Google Ads API ربط فيديوهات YouTube بحسابك على "إعلانات Google". يوضّح هذا الدليل كيفية استخدام واجهة برمجة التطبيقات لإضافة روابط إلى حسابك وإزالتها منه.
ربط الفيديوهات
يمكن ربط الفيديوهات بحسابك بإحدى الطريقتَين التاليتَين، وذلك حسب الجهة التي تبدأ العملية:
- تطلب ربط فيديو بحسابك. في هذه الحالة، عليك إرسال طلب إلى صانع محتوى، وعليه قبول الطلب لإنشاء رابط إلى الفيديو الذي يقدّمه. يمكنك إلغاء طلب تم تمديده قبل قبوله، ويمكنك أيضًا إزالة فيديو مرتبط بعد قبوله.
- يطلب صانع محتوى ربط الفيديو الذي يقدّمه بحسابك على "إعلانات 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 |
يتم عرض هذا الخطأ عندما يكون رابط البيانات الخاص بالفيديو متوفّرًا. |