الخلفية

قبل البدء

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

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

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

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

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

الحسابات الرئيسية

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

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

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

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

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

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

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

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

السلع

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

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

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

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

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

أسلوب الاتصال

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

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

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

في واجهات برمجة التطبيقات 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 Purchases API

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

في ما يلي التنسيق المحدد لمعرّفات الموارد المنتظمة (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 Purchases API.

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

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

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

JSON

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