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

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

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

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

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

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

تتم الإشارة إلى كيانات "إعلانات 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.

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