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

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

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

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

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

  1. [Preference]أنشئ نص الطلب باعتباره مخزن مؤقت للبروتوكول، وأرسله إلى الخادم باستخدام 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" بشكل فريد. مثال على سلسلة الرموز المميّزة للمطوِّر هي ABcdeFGH93KL-NOPQ_STUv. ويجب تضمين الرمز المميّز لمطوّر البرامج بالشكل developer-token : ABcdeFGH93KL-NOPQ_STUv.

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

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

https://googleads.googleapis.com/v11/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.

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

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

معرّف الطلب

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