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

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

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

‫Google Ads API هي gRPC API مع عمليات ربط 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 في مجموعات إعلانية متعددة. AdGroupAdError.AD_SHARING_NOT_ALLOWED.

يتعذّر إنشاء AdGroupAd جديد يشير إلى AdId حالي في مجموعة إعلانية أخرى، ويظهر الخطأ

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

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

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

request-id

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