Google Ads API دارای یک مکانیسم یکپارچه بازیابی ویژگی و گزارش سنجه است که به شما امکان می دهد با استفاده از زبان جستجوی Google Ads پرس و جو ایجاد کنید. این درخواست‌های پیچیده را فعال می‌کند که می‌توانند مقادیر زیادی از داده‌ها را در مورد حساب‌های Google Ads فردی برگردانند.
می توانید با استفاده از یکی از روش های Search یا SearchStream کوئری ایجاد کنید. هر دو روش از پرس و جوهای یکسانی پشتیبانی می کنند و نتایج معادل را برمی گردانند. روش Search داده‌ها را در صفحات با اندازه ثابت 10000 ردیفی برمی‌گرداند و به شما امکان می‌دهد با استفاده از صفحه‌بندی روی یک مجموعه نتایج تکرار کنید. این می تواند در شرایط شبکه با پهنای باند کم یا غیرقابل اعتماد مفید باشد، به عنوان مثال، برای تقسیم یک مجموعه نتیجه بزرگ به پاسخ های کوچکتر که می توانند در صورت قطع اتصال دوباره واکشی شوند. از سوی دیگر، روش SearchStream ، کل نتیجه مجموعه را در یک پاسخ پخش می‌کند، که می‌تواند برای بازیابی اطلاعات انبوه کارآمدتر باشد.
هر دو Search و SearchStream از یک URL اصلی استفاده می کنند:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
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
{
"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'"
}
اگر بیش از 10000 ردیف در نتایج وجود داشته باشد 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
{
"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'"
}