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