تتضمّن Google Ads API آلية موحَّدة لإعداد التقارير عن المقاييس واسترداد السمات تسمح لك بإنشاء طلبات بحث باستخدام لغة طلب البحث في "إعلانات Google". ويتيح ذلك طلبات البحث المعقّدة التي يمكن أن تعرض كميات كبيرة من البيانات حول حسابات "إعلانات Google" الفردية.
يمكنك إنشاء طلبات بحث باستخدام إحدى الطريقتَين Search
أو SearchStream
.
تتيح كلتا الطريقتين استخدام نفس الاستعلامات وتعرض نتائج مكافئة. وتعرض طريقة Search
البيانات بأحجام صفحات قابلة للتخصيص، ما يتيح لك تكرار مجموعة النتائج باستخدام التقسيم على صفحات. وقد يفيد ذلك في انخفاض معدل نقل البيانات أو ظروف الشبكة غير الموثوقة، فعلى سبيل المثال، لتقسيم مجموعة نتائج كبيرة إلى استجابات أصغر يمكن إعادة جلبها في حالة فقدان الاتصال. أمّا طريقة
SearchStream
، فتُعرض مجموعة النتائج بالكامل في
رد واحد، ما قد يكون أكثر فعالية في استرداد البيانات المجمّعة.
يستخدم كل من Search
وSearchStream
عنوان URL الأساسي نفسه:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
تستخدم طريقة البحث المستند إلى الصفحة مَعلمة pageSize
اختيارية تحدّ من عدد النتائج التي يتم عرضها في استجابة واحدة من واجهة برمجة التطبيقات.
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "pageSize": 10000, "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'" }
إذا كان هناك صفوف أكثر من pageSize
في النتائج، يتم عرض nextPageToken
في الرد:
{ "results": [ // ... // ... // ... ], "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B", "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status" }
يؤدي تكرار طلب البحث نفسه مع إضافة pageToken
بالقيمة أعلاه إلى جلب
صفحة النتائج التالية:
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "pageSize": 10000, "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'", "pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" }
لاستخدام طريقة SearchStream
التي تعرض جميع النتائج في رد مباشر واحد، ما عليك سوى تغيير طريقة الخدمة في عنوان URL إلى searchStream
(لا يلزم استخدام pageSize
وpageToken
في SearchStream
):
POST /v17/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'" }