بنية استدعاء واجهة برمجة التطبيقات

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

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

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

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

1. أنشئ نص الطلب على شكل Protocol Buffers.
2. أرسِلها إلى الخادم باستخدام HTTP/2.
3. إلغاء تسلسل الردّ إلى مخزن مؤقت للبروتوكول
4. تفسير النتائج.

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

اختياري:

1. أنشِئ نص الطلب كعنصر JSON.
2. أرسِلها إلى الخادم باستخدام HTTP 1.1.
3. إلغاء تسلسل الردّ كعنصر JSON
4. تفسير النتائج.

يُرجى الرجوع إلى دليل واجهة REST للحصول على مزيد من المعلومات حول استخدام REST.

معرّفات الموارد

يتمّ تحديد عناوين العناصر في Google Ads API باستخدام أسماء موارد منظَّمة ومعرّفات مركّبة.

أسماء الموارد

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

أرقام التعريف المركّبة

إذا لم يكن رقم تعريف أحد العناصر فريدًا على مستوى العالم، يتم إنشاء رقم تعريف مركّب لهذا العنصر من خلال إضافة رقم تعريف العنصر الأصل وعلامة المدة (~) في البداية.

على سبيل المثال، يحتوي AdGroupAd على نمط اسم المورد customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. بما أنّ المعرّف المركّب يجمع بين معرّف المجموعة الإعلانية الرئيسية (ad_group.id) ومعرّف الإعلان الأساسي (ad_group_ad.ad.id)، نضيف معرّف المجموعة الإعلانية إلى معرّف الإعلان:

• ‫AdGroupId من 123 + ~ + AdId من 45678 = مجموعة إعلانية مركّبة معرّف الإعلان 123~45678

عناوين الطلبات

في ما يلي عناوين HTTP (أو بيانات gRPC الوصفية) التي تصاحب النص الأساسي في الطلب:

التفويض

يجب تضمين رمز مميّز للوصول إلى OAuth 2.0 بالتنسيق Authorization: Bearer YOUR_ACCESS_TOKEN يحدّد إما حسابًا إداريًا يعمل نيابةً عن حساب عميل، أو معلِنًا يدير حسابه مباشرةً. يمكنك الاطّلاع على توجيهات حول كيفية استرداد رمز دخول في دليل OAuth2. يكون رمز الدخول صالحًا لمدة ساعة واحدة بعد الحصول عليه. وعند انتهاء صلاحيته، عليك إعادة تحميل رمز الدخول لاسترداد رمز جديد. يُرجى العِلم أنّ مكتبات برامجنا تعيد تلقائيًا تحميل الرموز المميزة المنتهية الصلاحية.

إذا واجهت أخطاء في التفويض، تأكَّد من استخدام بيانات الاعتماد الصحيحة ومن توفّر الأذونات الكافية. يشير الخطأ USER_PERMISSION_DENIED إلى أنّ المستخدم الذي تمت المصادقة عليه قد لا يكون لديه إذن بالوصول إلى حساب العميل المحدّد في الطلب. إذا تمت الموافقة على مشروعك على Google Cloud لاستخدام Test فقط وأرسلت طلبًا يستهدف حسابًا على الإصدار العلني، ستعرض واجهة برمجة التطبيقات الرمز AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION في الإصدار 25 والإصدارات الأحدث (أو AuthorizationError.ACTION_NOT_PERMITTED في الإصدار 24 والإصدارات الأقدم). راجِع مقالة مستويات الوصول في "إعلانات Google" للحصول على تفاصيل حول إدارة الأذونات.

login-customer-id

هذا هو رقم تعريف العميل المفوّض الذي سيتم استخدامه في الطلب، بدون واصلات (-). إذا كان بإمكانك الوصول إلى حساب العميل من خلال حساب إداري، يكون هذا العنوان مطلوبًا ويجب ضبطه على رقم تعريف العميل الخاص بالحساب الإداري. إذا لم تضمّن login-customer-id عند المصادقة من خلال حساب إداري، سيؤدي ذلك إلى حدوث الخطأ AuthorizationError.USER_PERMISSION_DENIED. راجِع الأخطاء الشائعة لمزيد من المعلومات حول هذا النوع من الأخطاء. للحصول على شرح مفصّل حول كيفية حلّ مشكلة الوصول إلى الحساب، يُرجى الرجوع إلى دليل نموذج الوصول إلى OAuth.

https://googleads.googleapis.com/v25/customers/1234567890/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 خاص بمستخدم لديه إذن الوصول إلى "الشركاء"
• استبدِل 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 هي سلسلة تحدّد هذا الطلب بشكل فريد. يجب تقديم هذه القيمة عند التواصل مع فريق الدعم للمساعدة في تحديد المشاكل وحلّها في طلبات واجهة برمجة التطبيقات الفاشلة أو غير المتوقّعة.