الخلفية

قبل البدء

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

الحسابات الرئيسية والحسابات الفرعية

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

الحسابات الفرعية

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

حسابات الوالدَين

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

ملاحظة: عليك التواصل مع المدير التقني لحسابك إذا أردت ضبط بنية حساب باستخدام الحسابات الرئيسية والحسابات الفرعية.

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

المورد هو كيان بيانات فردي له معرّف فريد. يمثّل مورد "الحسابات" إدخالاً لحساب "الشراة المعتمَدون"، وهو فئة البيانات الجذر لواجهة برمجة تطبيقات المشترين في Ad Exchange. تعمل طرق واجهة برمجة التطبيقات على موارد الحسابات الفردية وعلى مجموعات من موارد الحسابات.

ويتضمّن مورد الحسابات ما يلي: رقم تعريف الحساب والمعلومات المستخدَمة في مطابقة ملفات تعريف الارتباط والمواقع الجغرافية لمقدّمي عروض الأسعار وعنوان URL الذي يتمّ إرسال طلبات عروض الأسعار إليه وطلب تحديد الحدّ الأقصى لطلبات البحث في الثانية التي يتمّ إرسالها بواسطة تبادل الإعلانات.

بالإضافة إلى مورد الحسابات وجمعها، تُحدِّد واجهة برمجة التطبيقات للمشتري في Ad Exchange هياكل البيانات التالية:

الموقع الجغرافي لمقدِّم عروض الأسعار

المواقع الجغرافية لمقدّمي عروض الأسعار هي بُنى يتم عرضها مع "موارد الحسابات" لتوفير عنوان URL الذي يجب أن يرسل إليه تبادل الإعلانات طلبات عروض الأسعار والحد الأقصى لعدد طلبات البحث في الثانية التي يجب أن يرسلها تبادل الإعلانات. في ما يلي مثال على موقع جغرافي لمقدّم عرض سعر، معبرًا عنه بالترميز JSON:

"bidderLocation": [
    {
      "url": "http://bid.url.com/bidder",
      "maximumQps": 1500
    }
  ],

السلع

توفِّر العناصر قائمة بالحسابات. إليك مثال على العناصر معبرًا عنها بتنسيق JSON:

{
  "kind": "adexchangebuyer#accountsList",
  "items": [
    accounts Resource
  ]
}

العمليات المتاحة

يمكنك استدعاء ثلاث طرق مختلفة في المجموعات والموارد في Ad Exchange Buyer API كما هو موضّح في الجدول التالي. تتطلب جميع العمليات تفويضًا.

العملية	الوصف	تعيينات REST HTTP
list	يتم إدراج جميع الحسابات التي يمكن للمستخدم الذي تمت مصادقتها حاليًا الوصول إليها.	GET على معرّف موارد منتظم (URI) لمجموعة.
الحصول على	الحصول على مورد "حسابات" محدَّد	GET على عنوان URI للمورد.
تعديل	لتعديل مورد "حسابات" محدَّد	PUT على معرّف الموارد المنتظم (URI) للمورد، والذي يتم من خلاله تمرير بيانات المورد المعدّل.

نمط الاتصال

REST هي نمط من بنية البرامج التي توفر نهجًا مريحًا ومتسقًا لطلب البيانات وتعديلها.

يشير الاختصار REST إلى "نقل الولاية التمثيلية". يشير سياق Google APIs إلى استخدام أفعال HTTP لاسترداد تمثيلات البيانات التي خزّنتها Google وتعديلها.

في نظام RESTful، يتم تخزين الموارد في مخزن بيانات؛ يرسل العميل طلبًا بأن يؤدي الخادم إجراءً معينًا (مثل إنشاء مورد أو استرداده أو تحديثه أو حذفه)، وينفذ الخادم الإجراء ويرسل استجابة، غالبًا في شكل تمثيل للمورد المحدد.

في واجهات برمجة التطبيقات RESTful الخاصة بـ Google، يحدّد العميل إجراءً باستخدام فعل HTTP، مثل POST أو GET أو PUT أو DELETE. ويحدد موردًا بواسطة معرف موارد منتظم (URI) فريد عالميًا بالنموذج التالي:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

ونظرًا لأن جميع موارد واجهة برمجة التطبيقات تحتوي على عناوين URI فريدة يمكن الوصول إليها عبر HTTP، تعمل REST على تخزين البيانات مؤقتًا ويتم تحسينها للعمل مع البنية الأساسية الموزعة للويب.

يمكنك الاستفادة من تعريفات الطرق في مستندات معايير HTTP 1.1 التي تتضمّن مواصفات GET وPOST وPUT وDELETE.

REST في واجهة برمجة تطبيقات Ad Exchange Buyer

ترتبط العمليات المتوافقة مباشرةً بأفعال REST HTTP، كما هو موضّح في عمليات واجهة برمجة التطبيقات.

التنسيق المحدد لعناوين URI لواجهة برمجة التطبيقات هو:

https://www.googleapis.com/adexchangebuyer/v1.4/resourceID?parameters

حيث resourceID هو معرّف مورد الحسابات وparameters أي معلمات لتطبيقها على طلب البحث. راجِع مَعلمات طلب البحث العادية والمستندات المرجعية للحصول على التفاصيل.

يتيح لك تنسيق إضافات مسارات resourceID تحديد المورد الذي تعمل عليه حاليًا، على سبيل المثال:

https://www.googleapis.com/adexchangebuyer/v1.4/accounts
https://www.googleapis.com/adexchangebuyer/v1.4/accounts/id

تم تلخيص المجموعة الكاملة من معرّفات الموارد المنتظمة (URI) لكل عملية متوافقة في واجهة برمجة التطبيقات في المستندات المرجعية.

وفي ما يلي مثال على آلية عمل ذلك في Ad Exchange Buyer API.

احصل على قائمة حسابات المستخدم الذي تمت مصادقته:

GET https://www.googleapis.com/adexchangebuyer/v1.4/accounts

تنسيق البيانات

JSON

JSON (JavaScript Object Notation) هو تنسيق بيانات شائع ومستقل عن اللغة يوفّر تمثيلاً نصيًا بسيطًا لهياكل البيانات العشوائية. لمزيد من المعلومات، يمكنك الاطّلاع على json.org.