يوضّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتعامل مع واجهة برمجة التطبيقات، لن تحتاج إلى معرفة تفاصيل الطلب الأساسية. ومع ذلك، قد تكون بعض المعلومات حول بنية طلبات البيانات من واجهة برمجة التطبيقات مفيدة عند الاختبار وتصحيح الأخطاء.
Google Ads API هي واجهة برمجة تطبيقات gRPC، مع عمليات ربط REST. وهذا يعني أنّ هناك طريقتَين لإجراء طلبات إلى واجهة برمجة التطبيقات.
الخيار المفضّل:
- أنشئ نص الطلب كـ Protocol Buffers.
- أرسِلها إلى الخادم باستخدام HTTP/2.
- إلغاء تسلسل الردّ إلى مخزن مؤقت للبروتوكول
- تفسير النتائج.
توضّح معظم مستنداتنا كيفية استخدام gRPC.
اختياري:
- أنشئ نص الطلب كعنصر JSON.
- أرسِلها إلى الخادم باستخدام HTTP 1.1.
- إلغاء تسلسل الردّ كعنصر JSON
- تفسير النتائج.
راجِع دليل واجهة REST للحصول على مزيد من المعلومات حول استخدام REST.
أسماء الموارد
يتم تحديد معظم العناصر في واجهة برمجة التطبيقات من خلال سلاسل أسماء الموارد. تعمل هذه السلاسل أيضًا كعناوين URL عند استخدام واجهة REST. يمكنك الاطّلاع على بنية هذه الأسماء في قسم أسماء الموارد ضمن واجهة REST.
أرقام التعريف المركّبة
إذا لم يكن رقم تعريف أحد العناصر فريدًا على مستوى العالم، يتم إنشاء رقم تعريف مركّب لهذا العنصر من خلال إضافة رقم تعريف العنصر الرئيسي وعلامة المد (~) في البداية.
على سبيل المثال، بما أنّ رقم تعريف إعلان المجموعة الإعلانية ليس فريدًا على مستوى العالم، نضيف إليه رقم تعريف العنصر الرئيسي (المجموعة الإعلانية) لإنشاء معرّف مركّب فريد:
-
AdGroupIdمن123+~+AdGroupAdIdمن45678= رقم تعريف المجموعة الإعلانية المركّبة123~45678
عناوين الطلبات
في ما يلي عناوين HTTP (أو بيانات وصفية لبروتوكول grpc) التي تصاحب النص الأساسي في الطلب:
التفويض
يجب تضمين رمز مميّز للوصول إلى OAuth 2.0 بالتنسيق Authorization: Bearer
YOUR_ACCESS_TOKEN يحدّد إما حسابًا إداريًا يعمل نيابةً عن حساب عميل، أو معلِنًا يدير حسابه مباشرةً. يمكنك الاطّلاع على توجيهات حول استرداد رمز دخول في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة واحدة بعد الحصول عليه. وعند انتهاء صلاحيته، عليك إعادة تحميل رمز الدخول للحصول على رمز جديد. يُرجى العِلم أنّ مكتبات البرامج الخاصة بالعملاء تعيد تلقائيًا تحميل الرموز المميزة المنتهية الصلاحية.
في حال مواجهة أخطاء في التفويض، تأكَّد من استخدام بيانات الاعتماد الصحيحة ومن توفّر الأذونات الكافية. يشير الخطأ USER_PERMISSION_DENIED إلى أنّ المستخدم الذي تمت المصادقة عليه قد لا يكون لديه إذن بالوصول إلى حساب العميل المحدّد في الطلب. راجِع مقالة مستويات الوصول في "إعلانات Google"
للحصول على تفاصيل حول إدارة الأذونات.
login-customer-id
هذا هو معرّف العميل المصرّح به الذي سيتم استخدامه في الطلب،
بدون واصلات (-). إذا كان بإمكانك الوصول إلى حساب العميل من خلال
حساب إداري، يكون هذا العنوان مطلوبًا ويجب ضبطه على معرّف العميل
الخاص بالحساب الإداري. إذا لم تضمّن login-customer-id عند المصادقة من خلال حساب إداري، سيؤدي ذلك إلى ظهور الخطأ AuthorizationError.USER_PERMISSION_DENIED. راجِع الأخطاء الشائعة للحصول على مزيد من المعلومات عن نوع الخطأ هذا. للحصول على شرح مفصّل حول كيفية حلّ مشكلة الوصول إلى الحساب، يُرجى الرجوع إلى دليل نموذج الوصول إلى OAuth.
https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate
يُعدّ ضبط login-customer-id مكافئًا لاختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة.
في حال عدم تضمين هذا العنوان، سيتم ضبطه تلقائيًا على العميل المشغّل.
linked-customer-id
هذا العنوان مطلوب ويستخدمه الشركاء (مثل مقدّم خدمة إحصاءات التطبيقات التابعة لجهة خارجية أو شركاء البيانات) عند اتّخاذ إجراءات في حساب مرتبط على "إعلانات Google". يجب أن يحدّد هذا العنوان رقم تعريف العميل الخاص بحساب "إعلانات Google" الذي يتضمّن رابط المنتج.
لنفترض أنّ أحد الشركاء يحتاج إلى إجراء طلبات بيانات من واجهة برمجة التطبيقات إلى حساب على "إعلانات Google" استنادًا إلى رابط منتج.
- المعلِن: حساب "إعلانات Google" الذي تتم إدارته أو تعديله من خلال طلب البيانات من واجهة برمجة التطبيقات.
يتم تحديد رقم تعريف حساب المعلِن في الطلب. في REST، تكون هذه المَعلمة هي مَعلمة المسار
customerId(على سبيل المثال،customers/1111111111/...)، وفي gRPC، يكون هذا هو الحقلcustomer_idفي الطلب. - الشريك: حساب الشريك (على سبيل المثال، مقدّم خدمة تحليلات تطبيقات تابع لجهة خارجية أو شريك بيانات).
- الحساب المرتبط: هو حساب "إعلانات Google" الذي تم إنشاء رابط منتج بينه وبين "الشريك"، ما يمنح "الشريك" إذن الوصول إلى "المعلِن".
يُجري مستخدم لديه إذن الوصول إلى حساب الشريك طلبات إلى واجهة برمجة التطبيقات لتنفيذ إجراءات على عناصر في حساب المعلن (مثل تحميل الإحالات الناجحة أو إدارة قوائم المستخدمين). يمكن أن يكون الحساب المرتبط هو حساب المعلِن نفسه، أو حسابًا إداريًا تابعًا لحساب المعلِن.
يجب ضبط عناوين الطلبات على النحو التالي:
- استبدِل
Authorizationبرمز مميّز للوصول إلى OAuth 2.0 خاص بمستخدم لديه إذن بالوصول إلى Partner. -
login-customer-id: رقم تعريف العميل الخاص بالشريك. يجب أن يكون لدى المستخدم الذي تم إثبات هويته إذن بالوصول إلى هذا الحساب. -
linked-customer-id: رقم تعريف العميل للحساب المرتبط. يشير هذا العنوان إلى أنّ الإذن بهذا الطلب يعتمد على ربط حساب المنتج بحساب الشريك.
هناك سيناريوهان للربط:
- إذا كان حساب المعلِن مرتبطًا مباشرةً بحساب الشريك، سيكون الحساب المرتبط هو حساب المعلِن، ويجب ضبط
linked-customer-idعلى رقم تعريف العميل الخاص بحساب المعلِن. - إذا كان حساب المعلن مُدارًا بواسطة حساب إداري مرتبط بحساب الشريك من خلال رابط منتج، يكون الحساب المرتبط هو الحساب الإداري، ويجب ضبط
linked-customer-idعلى رقم تعريف العميل الخاص بالحساب الإداري.
المثال 1: رابط مباشر
إذا كان حساب المعلِن 1111111111 مرتبطًا مباشرةً بحساب الشريك 2222222222، وكان طلب البيانات من واجهة برمجة التطبيقات يستهدف customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
المثال 2: رابط المدير
إذا كان حساب المعلِن 1111111111 تتم إدارته من خلال الحساب الإداري 3333333333، وكان الحساب الإداري 3333333333 مرتبطًا بحساب الشريك 2222222222، وكان طلب البيانات من واجهة برمجة التطبيقات يستهدف customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
عناوين الاستجابة
يتم عرض العناوين التالية (أو grpc trailing-metadata) مع نص الردّ. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.
request-id
request-id هي سلسلة تحدّد هذا الطلب بشكل فريد.