أسماء الموارد

التدرّج الهرمي للأسماء

أسماء الموارد المستخدمة في Google Ads API هرمية تعكس تنظيم الكيانات في "إعلانات Google". جميع الموارد تقريبًا عبارة عن موارد فرعية لمورد Customer، مما يعكس حقيقة أن كل طلب بيانات من واجهة برمجة التطبيقات يجب أن يستهدف حسابًا محددًا على "إعلانات Google". فمثلاً، الحملات والمجموعات الإعلانية والإعلانات والكلمات الرئيسية هي جميعها موارد فرعية لمورد العملاء الأساسيين.

المورد	اسم المورد
العميل	customers/1234567890
الحملة	customers/1234567890/campaigns/8765432109
AdGroup	customers/1234567890/adGroups/54321098765
AdGroupAd	customers/1234567890/adGroupAds/54321098765~2109876543210

نقطة رئيسية: تستخدم Google Ads API أسماء موارد relative (وليس relative موارد كاملة مثل بعض واجهات Google APIs الأخرى).

أرقام تعريف الموارد

يُشار إلى كيانات "إعلانات Google" (العملاء والحملات وما إلى ذلك) من خلال أسماء الموارد من خلال واجهة برمجة التطبيقات. ومع ذلك، من المهم ملاحظة أنّ أسماء الموارد نفسها قد تحتوي على معرّفات موارد رقمية فريدة تحدّد كل عنصر في التسلسل الهرمي. في هذه الحالات، قد يكون من المفيد تحليل اسم المورد لاستخراج معرّفات الموارد هذه وتجميع معرّفات جديدة.

على سبيل المثال، افحص اسم مورد AdGroupAd من الجدول السابق:

customers/1234567890/adGroupAds/54321098765~2109876543210

ويمكن تقسيم ذلك إلى أرقام تعريف موارد فردية (مفصولة حسب أرقام تعريف المجموعات) على النحو التالي:

مكونات اسم المورد
معرّفات الموارد	معرف العميل: "1234567890" الرقم التعريفي للمجموعة الإعلانية: "54321098765" الرقم التعريفي لإعلان المجموعة الإعلانية: "2109876543210"
أرقام تعريف المجموعات	"customers" "adGroupAds"

يتيح لك تحليل أرقام التعريف الفردية اشتقاق أسماء موارد جديدة للإشارة إلى عميل إعلان المجموعة الإعلانية (customers/1234567890) أو مجموعته الإعلانية (customers/1234567890/adGroupAds/54321098765).

نقطة رئيسية: تتم الإشارة إلى أسماء الموارد في طلبات JSON ونص الرد من خلال الحقل resourceName، وليس الحقل name كما هو الحال في بعض واجهات برمجة تطبيقات Google Cloud الأخرى. تحتوي العديد من كيانات "إعلانات Google" على سمات أسماء نفسها (campaign.Name وadGroup.Name وما إلى ذلك)، ولذلك يتم استخدام resourceName لتجنُّب الاصطدام مع أسماء الكائنات الحالية.

معرّفات العناصر المشتركة

ترتبط معظم العناصر في واجهة برمجة التطبيقات بعميل واحد محدد في "إعلانات Google". ومع ذلك، هناك بعض أنواع الكائنات التي يمكن مشاركتها بين حسابات متعددة. من الناحية العملية، تشمل هذه العناصر قوائم الكلمات الرئيسية السلبية أو إجراءات الإحالات الناجحة في جميع الحسابات والتي ينشئها عادةً ما يُنشئها المدراء ثم تتم مشاركتها مع العديد من حسابات العملاء.

ستختلف أسماء الموارد لكائنات مثل هذه، بناءً على الحساب الذي ترسل استدعاء واجهة برمجة التطبيقات إليه.

مثال: إجراءات الإحالات الناجحة في جميع الحسابات

لنفترض أنّ لدينا حسابًا إداريًا 987-654-3210 يتشارك في إجراء إحالة ناجحة في جميع الحسابات مع أحد حسابات العملاء 123-456-7890:

إنّ طلب بيانات من واجهة برمجة التطبيقات للحساب الإداري، على سبيل المثال، لتعديل فترة معاينة الإعلان لإجراء الإحالة الناجحة سيشير إلى العنصر المشترَك باستخدام اسم المورد: customers/9876543210/conversionActions/257733534.

إنّ طلب بيانات من واجهة برمجة التطبيقات إلى حساب العميل لتفعيل استخدام إجراء الإحالة الناجحة المشترَك سيشير إليه باستخدام اسم المورد: customers/1234567890/conversionActions/257733534.

هذا هو إجراء الإحالة الناجحة الأساسي نفسه، ولكن اسم المورد له مرتبط بالحساب المستخدَم للوصول إليه.