تتضمّن Google Ads API آلية موحَّدة لإعداد التقارير عن المقاييس واسترداد السمات تسمح لك بإنشاء طلبات بحث باستخدام لغة طلب البحث في "إعلانات Google". ويتيح ذلك طلبات البحث المعقّدة التي يمكن أن تعرض كميات كبيرة من البيانات حول حسابات "إعلانات Google" الفردية.
يمكنك إنشاء طلبات بحث باستخدام أيّ من الطريقتَين Search أو SearchStream.
تتيح كلتا الطريقتين استخدام نفس الاستعلامات وتعرض نتائج مكافئة. تعرض الطريقة
Search البيانات في صفحات بحجم ثابت يبلغ 10,000 صف، ما يتيح لك
التنقّل في مجموعة نتائج باستخدام تقسيم الصفحات. وقد يكون ذلك مفيدًا في حالات معدّل نقل البيانات المنخفض أو ظروف الشبكة غير الموثوق بها، على سبيل المثال، لتقسيم مجموعة نتائج كبيرة إلى ردود أصغر يمكن إعادة جلبها في حال انقطاع الاتصال. من ناحية أخرى، تعمل طريقة SearchStream على بث مجموعة النتائج بالكامل في ردّ واحد، ما قد يكون أكثر فعالية في استرداد البيانات المجمّعة.
يستخدم كلّ من Search وSearchStream عنوان URL الأساسي نفسه:
https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds
POST /v18/customers/CUSTOMER_ID/googleAds:search 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'" }
إذا كان هناك أكثر من 10,000 صف في النتائج، يتم عرض nextPageToken
في الردّ:
{ "results": [ // ... // ... // ... ], "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B", "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status" }
يؤدي تكرار طلب البحث نفسه مع إضافة pageToken مع القيم من
الطلب السابق إلى جلب الصفحة التالية من النتائج:
POST /v18/customers/CUSTOMER_ID/googleAds:search 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'", "pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" }
لاستخدام طريقة SearchStream التي تعرض جميع النتائج في استجابة واحدة يتم بثها، عليك تغيير طريقة الخدمة في عنوان URL إلى searchStream
(pageToken غير مطلوبة من خلال SearchStream):
POST /v18/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'" }