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

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

يقدم هذا الدليل المكوّنات الأساسية التي تتكون منها Google Ads API. تتكون Google Ads API من الموارد والخدمات. يمثل المورد كيان "إعلانات 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 في المستندات المرجعية للحقول.

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