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