يصف هذا الدليل البنية المشتركة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتفاعل مع واجهة برمجة التطبيقات، لن تحتاج إلى القلق بشأن تفاصيل الطلب الأساسية. ومع ذلك، فإن معرفة القليل عنها يمكن أن تكون مفيدة عند الاختبار وتصحيح الأخطاء.
Google Ads API هي واجهة gRPC API تتضمّن عمليات ربط RST. وهذا يعني أن هناك طريقتان لإجراء استدعاءات واجهة برمجة التطبيقات.
[مفضل] يمكنك إنشاء نص الطلب باعتباره مخزنًا مؤقتًا للبروتوكول، وإرساله إلى الخادم باستخدام HTTP/2، وإلغاء تسلسل الاستجابة إلى مخزن بروتوكولات مؤقت، وتفسير النتائج. تصف معظم وثائقنا استخدام gRPC.
[اختياري] يمكنك إنشاء نص الطلب ككائن JSON، وإرساله إلى الخادم باستخدام HTTP 1.1، وإلغاء تسلسل الاستجابة ككائن JSON، وتفسير النتائج. يُرجى الرجوع إلى دليل واجهة ReST للحصول على مزيد من المعلومات حول استخدام 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/v16/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
السمة request-id هي سلسلة تعرِّف هذا الطلب بشكل فريد.