تتضمّن Google Ads API آلية موحّدة لإعداد التقارير عن المقاييس واسترداد السمات تتيح لك إنشاء طلبات بحث باستخدام لغة طلب البحث في "إعلانات Google". يؤدي ذلك إلى تفعيل طلبات البحث المعقّدة التي يمكنها عرض كميات كبيرة من البيانات حول حسابات "إعلانات Google" الفردية.
يمكنك إنشاء طلبات بحث باستخدام إحدى الطريقتَين Search
أو SearchStream
.
تتيح كلتا الطريقتين طلبات البحث نفسها وتعرض نتائج مكافئة. تعرض طريقة
Search
بيانات بأحجام صفحات قابلة للتخصيص، ما يتيح لك التكرار على مجموعة نتائج باستخدام التقسيم على صفحات. وقد يكون هذا مفيدًا في حالة انخفاض معدل نقل البيانات أو ظروف الشبكة غير الموثوق بها، كتقسيم نتيجة كبيرة مثلاً إلى استجابات أصغر يمكن إعادة جلبها في حال انقطاع الاتصال. من ناحية أخرى، تبث طريقة SearchStream
مجموعة النتائج بأكملها في استجابة واحدة، ما قد يكون أكثر فعالية في استرداد البيانات المجمّعة.
يستخدم كل من Search
وSearchStream
عنوان URL الأساسي نفسه:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds
تستخدم طريقة البحث المستنِدة إلى الصفحات معلَمة pageSize
اختيارية لتحديد عدد النتائج المعروضة في استجابة واحدة من واجهة برمجة التطبيقات.
POST /v16/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 /v16/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
(لا تتطلّب السمة SearchStream
وpageSize
pageToken
):
POST /v16/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'" }