يوضّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتفاعل مع واجهة برمجة التطبيقات، لن تحتاج إلى معرفة تفاصيل الطلب الأساسية. ومع ذلك، قد تكون بعض المعلومات حول بنية طلب البيانات من واجهة برمجة التطبيقات مفيدة عند الاختبار وتصحيح الأخطاء.
Google Ads API هي واجهة برمجة تطبيقات gRPC، مع روابط REST. وهذا يعني أنّ هناك طريقتَين لإجراء طلبات البيانات من واجهة برمجة التطبيقات.
الخيار المفضّل:
أنشئ نص الطلب كـ مخزن مؤقت للبروتوكول.
أرسِلها إلى الخادم باستخدام HTTP/2.
إلغاء تسلسل الردّ إلى مخزن مؤقت للبروتوكول
تفسير النتائج.
توضّح معظم مستنداتنا كيفية استخدام gRPC.
اختياري:
أنشئ نص الطلب كعنصر JSON.
أرسِلها إلى الخادم باستخدام HTTP 1.1.
إلغاء تسلسل الردّ كعنصر JSON
تفسير النتائج.
يُرجى الرجوع إلى دليل واجهة REST للحصول على مزيد من المعلومات حول استخدام REST.
أسماء الموارد
يتم تحديد معظم العناصر في واجهة برمجة التطبيقات من خلال سلاسل أسماء الموارد. تعمل هذه السلاسل أيضًا كعناوين URL عند استخدام واجهة REST. راجِع أسماء الموارد في واجهة REST لمعرفة بنيتها.
ويتم استخدام التنسيق نفسه للخدمات الأخرى.أرقام التعريف المركّبة
إذا لم يكن معرّف أحد العناصر فريدًا على مستوى العالم، يتم إنشاء معرّف مركّب لهذا العنصر من خلال إضافة معرّف العنصر الرئيسي وعلامة المد (~) في البداية.
على سبيل المثال، بما أنّ رقم تعريف إعلان المجموعة الإعلانية ليس فريدًا على مستوى العالم، نضيف إليه رقم تعريف العنصر الرئيسي (المجموعة الإعلانية) لإنشاء معرّف مركّب فريد:
-
AdGroupIdمن123+~+AdGroupAdIdمن45678= رقم تعريف المجموعة الإعلانية المركّبة123~45678
عناوين الطلبات
في ما يلي عناوين HTTP (أو بيانات وصفية لبروتوكول استدعاء الإجراء البعيد (RPC) من Google) التي تتضمّن النص الأساسي في الطلب:
التفويض
يجب تضمين رمز مميّز للوصول إلى OAuth2 بالتنسيق
Authorization: Bearer YOUR_ACCESS_TOKEN يحدّد إما حسابًا إداريًا يعمل نيابةً عن أحد العملاء، أو معلِنًا يدير حسابه مباشرةً. يمكنك الاطّلاع على تعليمات استرداد رمز الدخول في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة بعد الحصول عليه. وعند انتهاء صلاحيته، عليك إعادة تحميل رمز الدخول لاسترداد رمز جديد. يُرجى العِلم أنّ مكتبات برامجنا تعيد تلقائيًا تحميل الرموز المميزة المنتهية الصلاحية.
developer-token
الرمز المميز للمطوِّر هو سلسلة من 22 حرفًا تحدّد بشكل فريد مطوِّر Google Ads API. في ما يلي مثال على سلسلة الرمز المميز للمطوِّر:
ABcdeFGH93KL-NOPQ_STUv. يجب تضمين رمز المطوّر المميز في النموذج developer-token : ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
هذا هو معرّف العميل المصرّح به الذي سيتم استخدامه في الطلب،
بدون واصلات (-). إذا كان بإمكانك الوصول إلى حساب العميل من خلال
حساب إداري، يكون هذا العنوان مطلوبًا ويجب ضبطه على معرّف العميل الخاص
بالحساب الإداري.
https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate
يُعدّ ضبط login-customer-id مكافئًا لاختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. في حال عدم تضمين هذا العنوان، سيتم ضبطه تلقائيًا على العميل النشط.
linked-customer-id
لا يتم استخدام هذا العنوان إلا من قِبل [مقدّمي خدمة إحصاءات التطبيقات التابعين لجهة خارجية عند تحميل الإحالات الناجحة إلى حساب مرتبط على "إعلانات Google".
لنفترض أنّ المستخدمين في الحساب A يمنحون إذن الوصول للقراءة والتعديل
إلى عناصره للحساب B من خلال
ThirdPartyAppAnalyticsLink.
بعد الربط، يمكن لمستخدم في الحساب B إجراء طلبات إلى واجهة برمجة التطبيقات في الحساب A،
مع مراعاة الأذونات التي يوفّرها الربط. في هذه الحالة، يتم تحديد أذونات استدعاء واجهة برمجة التطبيقات للحساب A من خلال رابط الحساب B التابع لجهة خارجية، وليس من خلال العلاقة بين الحساب الإداري والحساب، والتي يتم استخدامها في طلبات أخرى لواجهة برمجة التطبيقات.
يُجري مقدّم خدمة تحليلات التطبيقات التابع لجهة خارجية طلب بيانات من واجهة برمجة التطبيقات على النحو التالي:
linked-customer-id: حساب "إحصاءات التطبيقات التابعة لجهات خارجية" الذي يتم تحميل البيانات منه (الحسابB).customer-id: حساب "إعلانات Google" الذي يتم تحميل البيانات إليه (الحسابA)- عنوانا
login-customer-idوAuthorization: هما مزيج من القيم لتحديد مستخدم لديه إذن الوصول إلى الحسابB.
عناوين الاستجابة
يتم عرض العناوين التالية (أو grpc trailing-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.
request-id
request-id هي سلسلة تحدّد هذا الطلب بشكل فريد.