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

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

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

التسلسل الهرمي للكائنات

يمكن عرض حساب على "إعلانات Google" على أنّه تسلسل هرمي للكائنات.

• المورِد على المستوى الأعلى في الحساب هو الـ عميل.

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

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

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

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

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

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

الموارد

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

معرّفات الكائنات

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

يمكن أن تكون قواعد المعرّفات هذه مفيدة عند تصميم مساحة تخزين محلية لكائنات "إعلانات 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 يستردّ نُسخة مورِد واحدة، ما قد يكون مفيدًا لفحص بنية المورِد.

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

• CustomerService لتعديل العملاء.

• CampaignService لتعديل الحملات.

• AdGroupService لتعديل المجموعات الإعلانية.

يجب أن يتضمّن كل طلب 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 أيضًا في مستندات المرجع للحقول.