بنية واجهة برمجة التطبيقات

فيديو: الاطّلاع على حديث عن الخدمات والموارد من ورشة عمل 2019

يتناول هذا الدليل المكوّنات الأساسية التي تتألف منها واجهة برمجة التطبيقات Google Ads API. تتألّف واجهة برمجة التطبيقات مع "إعلانات Google" من موارد وخدمات. يمثل المورد كيان "إعلانات Google"، بينما تسترد الخدمات كيانات "إعلانات Google" وتعالجها.

التدرّج الهرمي للكائنات

يمكن النظر إلى حساب "إعلانات Google" على أنّه تدرّج هرمي من العناصر.

نموذج الحملة

  • إنّ المورد العالي المستوى للحساب هو العميل.

  • يحتوي كل عميل على حملة نشطة واحدة أو أكثر.

  • تحتوي كل حملة على مجموعة إعلانية واحدة أو أكثر، تُستخدم لتجميع إعلاناتك في مجموعات منطقية.

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

يمكنك إرفاق رمز AdGroupCriterion واحد أو أكثر أو CampaignCriterion بمجموعة إعلانية أو حملة. وهي تمثل المعايير التي تحدد كيفية عرض الإعلانات.

هناك العديد من أنواع المعايير، مثل الكلمات الرئيسية والفئات العمرية والمواقع الجغرافية. تؤثر المعايير المحدّدة على مستوى الحملة على جميع الموارد الأخرى ضمن الحملة يمكنك أيضًا تحديد تواريخ وميزانيات على مستوى الحملة.

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

المراجع

تمثّل الموارد الكيانات داخل حسابك على "إعلانات Google". Campaign وAdGroup هما مثالان على الموارد.

أرقام تعريف الكائنات

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

رقم تعريف الكائن نطاق التميز هل هو فريد عالميًا؟
معرِّف الميزانية شبكة عالمية نعم
معرّف الحملة شبكة عالمية نعم
معرف المجموعة الإعلانية شبكة عالمية نعم
الرقم التعريفي للإعلان المجموعة الإعلانية لا، ولكن الثنائي (AdGroupId، AdId) فريد عالميًا
رقم تعريف معيار المجموعة الإعلانية المجموعة الإعلانية لا، ولكن الثنائي (AdGroupId، CriterionId) فريد عالميًا
رقم تعريف معيار الحملة الحملة لا، ولكن الثنائي (CampaignId، CriterionId) فريد عالميًا
معلومات الإعلان الإضافية الحملة لا، ولكن الثنائي (CampaignId، AdExtensionId) فريد عالميًا
الرقم التعريفي للخلاصة شبكة عالمية نعم
الرقم التعريفي لعنصر الخلاصة شبكة عالمية نعم
رقم تعريف سمة الخلاصة الخلاصة لا
الرقم التعريفي لتخطيط الخلاصة شبكة عالمية نعم
الرقم التعريفي للتصنيف شبكة عالمية نعم
رقم تعريف قائمة المستخدمين شبكة عالمية نعم

يمكن أن تكون قواعد المعرِّف هذه مفيدة عند تصميم مساحة تخزين محلية لكائنات "إعلانات Google".

يمكن استخدام بعض الكائنات لأنواع متعددة من الكيانات. في هذه الحالات، يحتوي الكائن على حقل type يصف محتواه. على سبيل المثال، يمكن أن تشير السمة AdGroupAd إلى عنصر مثل إعلان نصي أو إعلان فندق أو إعلان محلي. يمكن الوصول إلى هذه القيمة من خلال الحقل AdGroupAd.ad.type، وتعرض قيمة في التعداد AdType.

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

يتم التعرّف على كل مورد بشكل فريد بواسطة سلسلة resource_name، التي تربط المورد ومصادره الرئيسية في مسار. على سبيل المثال، تكون أسماء موارد الحملات بالشكل التالي:

customers/customer_id/campaigns/campaign_id

لذلك بالنسبة إلى الحملة التي تحمل رقم التعريف 987654 في حساب "إعلانات Google" وتحمل الرقم التعريفي للعميل 1234567، ستكون resource_name على النحو التالي:

customers/1234567/campaigns/987654

الخدمات

تسمح لك الخدمات باسترداد كياناتك في "إعلانات Google" وتعديلها. هناك ثلاثة أنواع من الخدمات: التعديل، وخدمات استرجاع الكائنات والإحصاءات، وخدمات استرجاع البيانات الوصفية.

تعديل (تغيير) العناصر

تعدّل هذه الخدمات نُسخًا من نوع مورد مرتبط باستخدام طلب mutate. وتوفر أيضًا طلب get الذي يسترد مثيلاً واحدًا للمورد، ما قد يكون مفيدًا لفحص بنية أحد الموارد.

أمثلة على الخدمات:

يجب أن يشتمل كل طلب mutate على عناصر operation المقابلة. على سبيل المثال، تتوقع الطريقة CampaignService.MutateCampaigns مثيلاً واحدًا أو أكثر لـ CampaignOperation. راجِع تغيير العناصر وفحصها للاطّلاع على مناقشة تفصيلية حول العمليات.

عمليات التغيُّر المتزامنة

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

لا توفّر واجهة برمجة التطبيقات طريقة لقفل عنصر قبل تحديثه. إذا حاول مصدران تغيير عنصر في الوقت نفسه، ستعرِض واجهة برمجة التطبيقات الرمز DatabaseError.CONCURRENT_MODIFICATION_ERROR.

غير المتزامنة مقابل المتحولات المتزامنة

طرق التغيير في Google Ads API متزامنة. لا تعرض طلبات البيانات من واجهة برمجة التطبيقات ردًا إلا بعد أن يتم تغيير الكائنات، ما يتطلب منك انتظار الرد على كل طلب. في حين أن هذا النهج بسيط نسبيًا للترميز، إلا أنه يمكن أن يؤثر سلبًا على موازنة الحمل وإهدار الموارد إذا اضطرر العمليات إلى انتظار اكتمال المكالمات.

هناك نهج بديل وهو تبديل العناصر بشكل غير متزامن باستخدام BatchJobService، والذي ينفذ مجموعات من العمليات على خدمات متعددة بدون انتظار اكتمالها. بعد إرسال المهام المجمّعة، تنفّذ خوادم Google Ads API العمليات بشكل غير متزامن، ما يوفّر العمليات لتنفيذ عمليات أخرى. يمكنك التحقق بشكل دوري من حالة الوظيفة لإكمالها.

يمكنك الاطّلاع على دليل المعالجة المجمّعة للحصول على مزيد من المعلومات عن المعالجة غير المتزامنة.

تغيير التحقق

يمكن التحقق من معظم طلبات التبديل دون تنفيذ المكالمة فعليًا مقابل بيانات حقيقية. يمكنك اختبار طلب المعلمات المفقودة وقيم الحقول غير الصحيحة دون تنفيذ العملية فعليًا.

لاستخدام هذه الميزة، اضبط حقل validate_only المنطقي الاختياري للطلب على true. سيتم بعد ذلك التحقق من صحة الطلب بالكامل كما لو كان سيتم تنفيذه، ولكن يتم تخطي التنفيذ النهائي. إذا لم يتم العثور على أي أخطاء، سيتم عرض رد فارغ. إذا فشلت عملية التحقق، فإن رسائل الخطأ في الاستجابة ستشير إلى نقاط الفشل.

تُعد validate_only مفيدة بشكلٍ خاص في اختبار الإعلانات بحثًا عن انتهاكات السياسة الشائعة. يتم رفض الإعلانات تلقائيًا إذا انتهكت سياسات مثل استخدام كلمات محددة أو علامات ترقيم أو أحرف كبيرة أو طول محدد. قد يتسبب إعلان واحد غير صالح في فشل دفعة كاملة. يمكن أن يكشف اختبار إعلان جديد في طلب validate_only عن أي من هذه الانتهاكات. راجِع مثال الرمز من أجل التعامل مع أخطاء انتهاك السياسة لمعرفة ذلك بشكل عملي.

الحصول على العناصر وإحصاءات الأداء

GoogleAdsService هي خدمة واحدة وموحّدة لاسترداد العناصر وإحصاءات الأداء.

تتطلب كل طلبات Search وSearchStream لـ GoogleAdsService طلب بحث يحدد المورد المطلوب طلبه، وسمات الموارد ومقاييس الأداء المطلوب استردادها، وعبارات الإسناد التي يجب استخدامها لفلترة الطلب، والشرائح التي يجب استخدامها لتقسيم إحصاءات الأداء بشكل أكبر. لمزيد من المعلومات عن تنسيق طلبات البحث، اطّلع على دليل لغة طلب البحث في "إعلانات Google".

استرداد البيانات الوصفية

يسترد GoogleAdsFieldService البيانات الوصفية عن الموارد في Google Ads API، مثل السمات المتاحة للمورد ونوع بياناته.

توفّر هذه الخدمة المعلومات اللازمة لإنشاء طلب بحث من أجل GoogleAdsService. ولتسهيل الأمر، تتوفّر أيضًا المعلومات التي تعرضها GoogleAdsFieldService في المستندات المرجعية للحقول.

السابق
نظرة عامة
التالي
علاقات الكيانات