تتضمّن Google Ads API آلية موحّدة لاسترداد السمات وإعداد تقارير المقاييس تتيح لكم إنشاء طلبات بحث باستخدام لغة طلبات البحث في إعلانات Google. ويتيح ذلك إنشاء طلبات بحث معقّدة يمكنها عرض كميات كبيرة من البيانات حول حسابات فردية على "إعلانات Google".
يمكنكم إنشاء طلبات بحث باستخدام إحدى الطريقتَين Search أو SearchStream.
وتتيح كلتا الطريقتَين طلبات البحث نفسها وتعرضان نتائج متطابقة. تعرض الطريقة Search البيانات في صفحات ذات حجم ثابت تضمّ 10,000 صف، ما يتيح لكم تكرار مجموعة النتائج باستخدام تقسيم الصفحات. وقد يكون ذلك مفيدًا في حالات النطاق الترددي المنخفض أو ظروف الشبكة غير الموثوق بها، مثلاً لتقسيم مجموعة نتائج كبيرة إلى استجابات أصغر يمكن إعادة جلبها في حال فقدان الاتصال. في المقابل، تنقل الطريقة SearchStream مجموعة النتائج بأكملها في استجابة واحدة، ما قد يكون أكثر فعالية لاسترداد البيانات المجمّعة.
تستخدم الطريقتان Search وSearchStream عنوان URL الأساسي نفسه:
https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds
POST /v26/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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 /v26/customers/CUSTOMER_ID/googleAds:search HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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 (لا تتطلّب SearchStream استخدام pageToken):
POST /v26/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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'" }