يصف هذا الدليل البنية المشتركة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة عميل للتفاعل مع واجهة برمجة التطبيقات، فلا داعي للقلق بشأن تفاصيل الطلب الأساسية. ومع ذلك، يمكن أن تكون معرفة بعض المعلومات عنها مفيدة عند الاختبار وتصحيح الأخطاء.
واجهة برمجة التطبيقات مع "إعلانات Google" هي واجهة برمجة تطبيقات gRPC، مع روابط REST. وهذا يعني أن هناك طريقتان لإجراء استدعاءات لواجهة برمجة التطبيقات.
[Preferred]يمكنك إنشاء نص الطلب باعتباره مخزنًا مؤقتًا للبروتوكول، وإرساله إلى الخادم باستخدام HTTP/2، ثم إلغاء ترتيب الاستجابة للمخزن المؤقت للبروتوكولات وتفسير النتائج. تصف معظم وثائقنا استخدام gRPC.
[اختياري] يمكنك إنشاء نص الطلب ككائن 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/v13/customers/1234567890/campaignBudgets:mutate
يعادل ضبط login-customer-id اختيار حساب في واجهة مستخدم "إعلانات 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 عبارة عن سلسلة تعرّف هذا الطلب بشكل فريد.