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