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

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

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

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

نموذج الحملة

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

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

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

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

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

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

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

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

الموارد

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

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

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

رقم تعريف العنصر نطاق التفرّد هل هو فريد عالميًا؟
معرِّف الميزانية جميع أنحاء العالم نعم
الرقم التعريفي للحملة جميع أنحاء العالم نعم
معرف المجموعة الإعلانية جميع أنحاء العالم نعم
معرّف الإعلان المجموعة الإعلانية لا، ولكن الزوج (AdGroupId, AdId) فريد على مستوى العالم. لا يُسمح بمشاركة AdId في مجموعات إعلانية متعددة.
رقم تعريف AdGroupCriterion المجموعة الإعلانية لا، ولكن الزوج (AdGroupId، CriterionId) فريد على مستوى العالم
رقم تعريف CampaignCriterion الحملة لا، ولكن الزوج (CampaignId، CriterionId) فريد على مستوى العالم
الرقم التعريفي للتصنيف العميل لا، ولكن الزوج (CustomerId، LabelId) فريد على مستوى العالم
رقم تعريف قائمة المستخدمين جميع أنحاء العالم نعم
رقم تعريف مادة العرض جميع أنحاء العالم نعم

يمكن أن تكون قواعد أرقام التعريف هذه مفيدة عند تصميم مساحة تخزين محلية لعناصر "إعلانات 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 لإجراء تغييرات ذرية على مستوى أنواع موارد متعددة في طلب واحد (مثل إنشاء ميزانية حملة وحملة ومجموعة إعلانية معًا).

أمثلة على الخدمات الخاصة بالمراجع:

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

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

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

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

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

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

السابق
أنواع الحسابات
التالي
تحديد الإصدار