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

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

التسلسل الهرمي للعناصر

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

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

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

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

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

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

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

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

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

الموارد

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

معرّفات العناصر

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

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

يمكن استخدام بعض العناصر لأنواع متعددة من الكيانات. في هذه الحالات، يحتوي العنصر على حقل type يصف محتوياته. على سبيل المثال، AdGroupAd يمكن أن يشير إلى عنصر مثل إعلان متجاوب على شبكة البحث أو إعلان فندق أو إعلان زيادة الطلب. يمكن الوصول إلى هذه القيمة من خلال الحقل AdGroupAd.ad.type، ويعرض قيمة في تعداد AdType. يُرجى العِلم أنّ إمكانية التغيير يمكن أن تختلف حسب الإصدار (على سبيل المثال، VideoResponsiveAdInfo في Ad يمكن تغييره في الإصدار 24 والإصدارات الأحدث).

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

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

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

الخدمات

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

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

تعدّل الخدمات الخاصة بالمورِدات مثيلات نوع مورِد مرتبط باستخدام طلب mutate. يمكنك أيضًا استخدام GoogleAdsService.Mutate لإجراء عمليات تبديل ذرية على أنواع موارد متعددة في طلب واحد (مثل إنشاء ميزانية حملة وحملة ومجموعة إعلانية معًا).

في ما يلي أمثلة على الخدمات الخاصة بالمورِدات:

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

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

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

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

عمليات التبديل المتزامنة

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

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

عمليات التبديل غير المتزامنة مقابل المتزامنة

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

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

راجِع دليل المعالجة على دفعات لمزيد من المعلومات عن المعالجة غير المتزامنة.

التحقّق من صحة عمليات التبديل

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

لاستخدام هذه الميزة، اضبط الحقل المنطقي الاختياري validate_only في الطلب على true. يتم التحقّق من صحة الطلب بالكامل كما لو كان سيتم تنفيذه، ولكن يتم تخطّي التنفيذ النهائي. إذا لم يتم العثور على أي أخطاء، يتم عرض الردّ بدون ملء أي نتائج تم تبديلها (يكون results فارغًا). إذا تعذّر التحقّق من الصحة، سيتعذّر تنفيذ الطلب مع ظهور خطأ GoogleAdsFailure في طلب الإجراء عن بُعد (RPC) تلقائيًا (partial_failure = false)، أو سيتم عرض ردّ عادي يتضمّن أخطاء خاصة بالعملية في partial_failure_error عندما تكون partial_failure = true.

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

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

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

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

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

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

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