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

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

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

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

الطريقة المفضّلة:

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

تصف معظم مستنداتنا استخدام gRPC.

اختياري:

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

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

ملاحظة: يصف هذا الدليل بنية وعناوين النقل الشائعة لكلّ من بروتوكولَي gRPC وREST.

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

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

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

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

ملاحظة مهمة: يُرجى الاطّلاع على مستندات الموارد للاطّلاع على جميع الموارد المتوافقة وتمثيل المسار (resource_name). ويتم استخدام التنسيق نفسه للخدمات الأخرى.

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

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

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

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

ملاحظة: يُحظر مشاركة AdId بين مجموعات إعلانية متعدّدة. ويؤدي إنشاء AdGroupAd جديد يشير إلى AdId حالي في مجموعة إعلانية أخرى إلى ظهور الخطأ AdGroupAdError.AD_SHARING_NOT_ALLOWED.

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

هذه هي عناوين 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 access model.

مصطلح أساسي: **العميل الذي يتم العمل معه** هو رقم تعريف العميل في حمولة الطلب. على سبيل المثال، العميل الذي يتم العمل معه في الطلب التالي CampaignBudgetService هو 1234567890:

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

إنّ ضبط login-customer-id يعادل اختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. إذا لم يتم تضمين هذا العنوان، سيتم ضبطه تلقائيًا على العميل الذي يتم العمل معه.

ملاحظة: يمكنك استرداد قائمة الحسابات التي يمكن الوصول إليها مباشرةً باستخدام بيانات اعتماد OAuth من خلال إرسال طلب CustomerService.ListAccessibleCustomers. لا يكون login-customer-id مطلوبًا لهذا النوع من الطلبات، وليس له أي تأثير في قائمة العملاء المعروضة.

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) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تحديد الأخطاء وحلّها.

request-id

request-id هي سلسلة تحدّد هذا الطلب بشكل فريد. يُرجى تقديم هذه القيمة عند التواصل مع فريق الدعم للمساعدة في تحديد المشاكل وحلّها في طلبات واجهة برمجة التطبيقات التي تعذّر إرسالها أو غير المتوقّعة.