يوضِّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتفاعل مع واجهة برمجة التطبيقات، لن يكون عليك القلق بشأن تفاصيل الطلب الأساسية. ومع ذلك، فإن معرفة القليل عنها يمكن أن تكون مفيدة عند الاختبار وتصحيح الأخطاء.
Google Ads API هي إحدى واجهات gRPC API مع عمليات ربط REST. وهذا يعني أنّ هناك طريقتان لإجراء طلبات بيانات من واجهة برمجة التطبيقات.
[Preferred] يمكنك إنشاء نص الطلب باعتباره مخزنًا مؤقتًا للبروتوكول، وإرساله إلى الخادم باستخدام HTTP/2، وإلغاء تسلسل الاستجابة إلى مخزن مؤقت للبروتوكولات، وتفسير النتائج. تصف معظم وثائقنا استخدام gRPC.
[اختياري] يمكنك إنشاء نص الطلب على هيئة كائن JSON، وإرساله إلى الخادم باستخدام HTTP 1.1، وإلغاء تسلسل الاستجابة ككائن JSON، وتفسير النتائج. يمكنك الرجوع إلى دليل واجهة RST للحصول على مزيد من المعلومات عن استخدام RST.
أسماء الموارد
ويتم تعريف معظم العناصر في واجهة برمجة التطبيقات من خلال سلاسل أسماء الموارد الخاصة بها. تعمل هذه السلاسل أيضًا كعناوين URL عند استخدام واجهة REST. اطلع على أسماء موارد واجهة REST لمعرفة بنيتها.
أرقام التعريف المركّبة
إذا لم يكن معرّف الكائن فريدًا عالميًا، يتم إنشاء معرّف مركب لهذا الكائن عن طريق إضافة معرِّف الأصل وتلدة (~) في البداية.
على سبيل المثال، نظرًا لأن رقم تعريف إعلان المجموعة الإعلانية ليس فريدًا عمومًا، فإننا نضيف معرّف العنصر الرئيسي (المجموعة الإعلانية) إليه لإنشاء رقم تعريف مركب فريد:
AdGroupIdمن123+~+AdGroupAdIdمن45678= الرقم التعريفي لإعلان المجموعة الإعلانية المركّبة123~45678.
عناوين الطلبات
وفي ما يلي عناوين HTTP (أو البيانات الوصفية grpc) التي تصاحب النص في الطلب:
التفويض
يجب تضمين رمز الدخول OAuth2 في شكل Authorization: Bearer YOUR_ACCESS_TOKEN، وهو يحدّد إمّا حساب إداري يتصرّف نيابةً عن عميل أو معلن يدير حسابه الخاص مباشرةً. يمكن العثور على اتجاهات استرداد رمز الدخول
في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة بعد الحصول عليه، وعند انتهاء صلاحيته، أعِد تحميل رمز الدخول لاسترداد رمز جديد. تجدر الإشارة إلى أنّ مكتبات العملاء تعيد تحميل الرموز المميّزة المنتهية الصلاحية تلقائيًا.
الرمز المميّز للمطوّر
الرمز المميز للمطوِّر هو سلسلة تتكوّن من 22 حرفًا وتُعرِّف بشكل فريد مطوّر برامج Google Ads API. مثال على سلسلة الرمز المميز للمطوِّر هي
ABcdeFGH93KL-NOPQ_STUv. ويجب تضمين الرمز المميز للمطوِّر
في شكل developer-token : ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
هذا هو الرقم التعريفي للعميل المفوَّض لاستخدامه في الطلب،
بدون واصلات (-). إذا كان إذن وصولك إلى حساب العميل من خلال
حساب إداري، يكون هذا العنوان مطلوبًا ويجب ضبطه على الرقم التعريفي للعميل
للحساب الإداري.
https://googleads.googleapis.com/v17/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 tracking-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء
request-id
والسمة request-id هي سلسلة تعرِّف هذا الطلب بشكل فريد.