تتضمّن 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'"
}