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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يصف هذا الدليل البنية المشتركة لجميع طلبات البيانات من واجهة برمجة التطبيقات.

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

واجهة برمجة التطبيقات مع "إعلانات Google" هي واجهة برمجة تطبيقات gRPC، مع روابط REST. وهذا يعني أن هناك طريقتان لإجراء استدعاءات لواجهة برمجة التطبيقات.

  1. [Preferred]يمكنك إنشاء نص الطلب باعتباره مخزنًا مؤقتًا للبروتوكول، وإرساله إلى الخادم باستخدام HTTP/2، ثم إلغاء ترتيب الاستجابة للمخزن المؤقت للبروتوكولات وتفسير النتائج. تصف معظم وثائقنا استخدام gRPC.

  2. [اختياري] يمكنك إنشاء نص الطلب ككائن JSON وإرساله إلى الخادم باستخدام HTTP 1.1، ثم إعادة ترتيب الاستجابة ككائن JSON وتفسير النتائج. يُرجى الرجوع إلى دليل واجهة REST للحصول على المزيد من المعلومات عن استخدام REST.

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

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

المعرّفات المركّبة

إذا لم يكن معرّف الكائن مختلفًا عالميًا، يتم إنشاء معرّف مركّب لذلك الكائن من خلال الاحتفاظ برقم تعريف التلدة الأصلي (~).

على سبيل المثال، بما أنّ الرقم التعريفي لإعلان المجموعة الإعلانية ليس فريدًا على مستوى العالم، فإننا نُلحق رقم تعريف الكائن الرئيسي (المجموعة الإعلانية) به لإنشاء رقم تعريفي مركّب فريد:

  • AdGroupId من 123 + ~ + AdGroupAdId من 45678 = رقم تعريف المجموعة الإعلانية المركّبة 123~45678.

عناوين الطلبات

هذه هي رؤوس HTTP (أو بيانات grpc الوصفية) التي تصاحب النص الأساسي في الطلب:

التفويض

يجب تضمين رمز دخول مميز عبر OAuth2 في شكل Authorization: Bearer YOUR_ACCESS_TOKEN يحدد حسابًا إداريًا يتصرف نيابةً عن عميل أو معلن يدير حسابه مباشرةً. يمكن العثور على توجيهات استرداد رمز الدخول في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة بعد الحصول عليه؛ وعند انتهاء صلاحيته، حدّث رمز الدخول لاسترداد رمز جديد. لاحظ أن مكتبات العملاء تعمل تلقائيًا على تحديث الرموز المميزة المنتهية الصلاحية.

الرمز المميز للمطوِّر

الرمز المميز للمطوِّر عبارة عن سلسلة تتكون من 22 حرفًا تحدد مطوّر برامج إعلانات Google API بشكل فريد. مثال على سلسلة الرموز المميزة للمطوِّر هو ABcdeFGH93KL-NOPQ_STUv. يجب تضمين الرمز المميز للمطوِّر على شكل developer-token : ABcdeFGH93KL-NOPQ_STUv.

معرِّف تسجيل الدخول-العميل

هذا هو الرقم التعريفي للعميل المُعتمَد لاستخدامه في الطلب، بدون واصلات (-). إذا كان الوصول إلى حساب العميل من خلال حساب إداري، سيكون هذا العنوان مطلوبًا ويجب ضبطه على الرقم التعريفي للعميل الخاص بالحساب الإداري.

https://googleads.googleapis.com/v12/customers/1234567890/campaignBudgets:mutate

يعادل ضبط login-customer-id اختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. إذا لم تضمّن هذا الرأس، سيتم ضبطه تلقائيًا على العميل المُشغّل.

الرقم التعريفي للعميل المرتبط

لا يستخدِم مقدّمو خدمة إحصاءات التطبيقات التابعة لجهة خارجية هذا العنوان إلا عند تحميل الإحالات الناجحة إلى حساب مرتبط على "إعلانات Google".

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

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

  • linked-customer-id: حساب تحليلات التطبيق التابع لجهة خارجية الذي يحمّل البيانات (الحساب B).
  • customer-id: حساب "إعلانات Google" الذي يتم تحميل البيانات إليه (الحساب A).
  • عنوان login-customer-id وعنوان Authorization: تركيبة من القيم لتحديد مستخدم لديه حق الوصول إلى الحساب B.

عناوين الاستجابة

يتم عرض العناوين التالية (أو grpcnext-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.

رقم تعريف الطلب

request-id عبارة عن سلسلة تعرّف هذا الطلب بشكل فريد.