يوضّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتعامل مع واجهة برمجة التطبيقات، لن تحتاج إلى معرفة تفاصيل الطلب الأساسية. ومع ذلك، قد تكون بعض المعلومات حول بنية طلب البيانات من واجهة برمجة التطبيقات مفيدة عند الاختبار وتصحيح الأخطاء.
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) التي تصاحب النص الأساسي في الطلب:
التفويض
يجب تضمين رمز مميّز للوصول إلى OAuth2 بالتنسيق Authorization: Bearer
YOUR_ACCESS_TOKEN يحدّد إمّا حسابًا إداريًا يعمل نيابةً عن حساب عميل، أو معلِنًا يدير حسابه مباشرةً. يمكنك الاطّلاع على توجيهات حول استرداد رمز دخول في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة بعد الحصول عليه، وعند انتهاء صلاحيته، عليك إعادة تحميله لاسترداد رمز جديد.
يُرجى العلم أنّ مكتبات برامجنا تعيد تلقائيًا تحميل الرموز المميزة المنتهية الصلاحية.
في حال مواجهة أخطاء في التفويض، تأكَّد من استخدام بيانات الاعتماد الصحيحة ومن توفّر الأذونات الكافية. يشير الخطأ USER_PERMISSION_DENIED إلى أنّ المستخدم الذي تمت المصادقة عليه قد لا يكون لديه إذن بالوصول إلى حساب العميل المحدّد في الطلب. راجِع مقالة مستويات الوصول إلى "إعلانات Google" للحصول على تفاصيل حول إدارة الأذونات.
developer-token
الرمز المميز للمطوِّر هو سلسلة من 22 حرفًا تحدّد بشكلٍ فريد مطوِّر Google Ads API. مثال على سلسلة الرمز المميز للمطوِّر هو ABcdeFGH93KL-NOPQ_STUv. يجب تضمين الرمز المميز للمطوِّر بالتنسيق developer-token :
ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
هذا هو معرّف العميل المصرّح به الذي سيتم استخدامه في الطلب،
بدون واصلات (-). إذا كان بإمكانك الوصول إلى حساب العميل من خلال
حساب إداري، يكون هذا العنوان مطلوبًا ويجب ضبطه على معرّف العميل الخاص
بالحساب الإداري. إذا لم تضمّن login-customer-id عند المصادقة من خلال حساب إداري، سيؤدي ذلك إلى ظهور الخطأ AuthorizationError.USER_PERMISSION_DENIED. راجِع الأخطاء الشائعة للحصول على مزيد من المعلومات حول هذا النوع من الأخطاء.
https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate
يُعدّ ضبط login-customer-id مكافئًا لاختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. في حال عدم تضمين هذا العنوان، سيتم ضبطه تلقائيًا على العميل النشط.
linked-customer-id
هذا العنوان مطلوب ويستخدمه الشركاء (مثل مقدّمي خدمة إحصاءات التطبيقات التابعة لجهة خارجية أو شركاء البيانات) عند اتّخاذ إجراءات في حساب مرتبط على "إعلانات Google". يجب أن يحدّد هذا العنوان رقم تعريف العميل الخاص بحساب "إعلانات Google" الذي يتضمّن رابط المنتج.
لنفترض أنّ أحد الشركاء يحتاج إلى إجراء طلبات بيانات من واجهة برمجة التطبيقات إلى حساب على "إعلانات Google" استنادًا إلى رابط منتج.
- المعلِن: حساب "إعلانات Google" الذي تتم إدارته أو تعديله من خلال طلب واجهة برمجة التطبيقات. يتم تحديد رقم تعريف حساب المعلِن في الطلب. في REST،
هذه هي مَعلمة المسار
customerId(على سبيل المثال،customers/1111111111/...)، وفي gRPC، هذا هو الحقلcustomer_idفي الطلب. - الشريك: حساب الشريك (على سبيل المثال، مقدّم خدمة تحليلات التطبيقات التابع لجهة خارجية أو شريك البيانات)
- الحساب المرتبط: هو حساب "إعلانات Google" الذي تم إنشاء رابط منتج بينه وبين حساب الشريك، ما يمنح الشريك إذن الوصول إلى حساب المعلِن.
يُجري المستخدم الذي لديه إذن الوصول إلى "الشركاء" طلبات إلى واجهة برمجة التطبيقات للتصرّف في الكيانات في حساب المعلِن (على سبيل المثال، لتحميل الإحالات الناجحة أو إدارة قوائم المستخدمين). يمكن أن يكون الحساب المرتبط هو حساب المعلِن نفسه أو حسابًا إداريًا خاصًا بالمعلِن.
يجب ضبط عناوين الطلبات على النحو التالي:
Authorization: رمز OAuth2 لمستخدم لديه إذن الوصول إلى "الشركاء".developer-token: الرمز المميز للمطوّر لتطبيق واجهة برمجة التطبيقات، المرتبط عادةً بالشريك.-
login-customer-id: تمثّل هذه السمة رقم تعريف العميل الخاص بالشريك. يجب أن يكون لدى المستخدم الذي تم التحقّق من هويته إذن بالوصول إلى هذا الحساب. -
linked-customer-id: رقم تعريف العميل الخاص بالحساب المرتبط. يشير هذا العنوان إلى أنّ تفويض هذا الطلب يعتمد على ربط المنتج بالحساب المرتبط مع الشريك.
هناك سيناريوهان للربط:
- إذا كان "المعلِن" لديه رابط مباشر بالمنتج مع "الشريك"، يكون الحساب المرتبط هو حساب "المعلِن"، ويجب ضبط
linked-customer-idعلى رقم تعريف عميل "المعلِن". - إذا كان المعلِن يديره حساب إداري مرتبط بمنتج مع الشريك، يكون الحساب المرتبط هو الحساب الإداري، ويجب ضبط
linked-customer-idعلى رقم تعريف العميل الخاص بالحساب الإداري.
المثال 1: رابط مباشر
إذا كان المعلِن 1111111111 مرتبطًا مباشرةً بالشريك 2222222222، وكان طلب البيانات من واجهة برمجة التطبيقات يستهدف customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
المثال 2: رابط الحساب الإداري
إذا كان حساب المعلِن 1111111111 يديره حساب المدير 3333333333، وكان حساب المدير 3333333333 مرتبطًا بحساب الشريك 2222222222، وكان طلب البيانات من واجهة برمجة التطبيقات يستهدف customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
عناوين الاستجابة
يتم عرض العناوين التالية (أو grpc trailing-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.
request-id
request-id هي سلسلة تحدّد هذا الطلب بشكل فريد.