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

فيديو: جلسة "الخدمات والمراجع" من ورشة العمل لعام 2019

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

التدرّج الهرمي للعناصر

يمكن اعتبار حساب "إعلانات Google" تدرّجًا هرميًا للكائنات.

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

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

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

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

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

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

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

الموارد

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

أرقام تعريف العناصر

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

رقم تعريف العنصر	نطاق التفرّد	هل المعرّف فريد عالميًا؟
معرِّف الميزانية	عالمي	نعم
الرقم التعريفي للحملة	عالمي	نعم
معرف المجموعة الإعلانية	عالمي	نعم
معرّف الإعلان	المجموعة الإعلانية	لا، ولكنّ الزوج (AdGroupId، AdId) فريد على مستوى العالم
رقم تعريف معيار المجموعة الإعلانية	المجموعة الإعلانية	لا، ولكنّ الزوج (AdGroupId، CriterionId) فريد على مستوى العالم
رقم تعريف CampaignCriterion	الحملة	لا، ولكنّ الزوج (CampaignId, CriterionId) فريد على مستوى العالم
معلومات الإعلان الإضافية	الحملة	لا، ولكنّ الزوج (CampaignId, AdExtensionId) فريد على مستوى العالم
الرقم التعريفي للتصنيف	عالمي	نعم
UserList ID	عالمي	نعم
رقم تعريف مادة العرض	عالمي	نعم

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

نقطة أساسية: يقتصر عدد طلبات get على 1,000 طلب في اليوم. في معظم حالات الاستخدام الواقعية، يجب بدلاً من ذلك طلب التقارير باستخدام GoogleAdsService.

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

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