بنية طلب بيانات من واجهة برمجة التطبيقات

يوضّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.

إذا كنت تستخدم مكتبة برامج للتعامل مع واجهة برمجة التطبيقات، لن تحتاج إلى معرفة تفاصيل الطلب الأساسية. ومع ذلك، قد تكون بعض المعلومات حول بنية طلب البيانات من واجهة برمجة التطبيقات مفيدة عند الاختبار وتصحيح الأخطاء.

‫Google Ads API هي واجهة برمجة تطبيقات gRPC، مع عمليات ربط REST. وهذا يعني أنّ هناك طريقتَين لإرسال طلبات إلى واجهة برمجة التطبيقات.

الصيغة المفضّلة:

1. أنشئ نص الطلب كـ بروتوكول buffer.

2. أرسِلها إلى الخادم باستخدام HTTP/2.

3. إلغاء تسلسل الردّ إلى مخزن مؤقت للبروتوكول

4. تفسير النتائج.

توضّح معظم مستنداتنا كيفية استخدام gRPC.

اختياري:

1. أنشئ نص الطلب كعنصر JSON.

2. أرسِلها إلى الخادم باستخدام HTTP 1.1.

3. إلغاء تسلسل الردّ كعنصر JSON

4. تفسير النتائج.

يُرجى الرجوع إلى دليل واجهة 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/v23/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 هي سلسلة تحدّد هذا الطلب بشكل فريد.