ל-Google Ads API יש מנגנון מאוחד לאחזור מאפיינים ולדיווח על מדדים, שמאפשר ליצור שאילתות באמצעות שפת השאילתה ב-Google Ads. כך מתאפשרות שאילתות מורכבות שיכולות להחזיר כמויות גדולות של נתונים לגבי חשבונות Google Ads נפרדים.
אפשר ליצור שאילתות באמצעות אחת מהשיטות Search או SearchStream.
שתי שיטות ההעברה תומכות באותן שאילתות ומחזירות תוצאות מקבילות. ה-method Search מחזירה נתונים בגודלי דפים שניתן להתאים אישית, וכך אפשר לחזור על קבוצת תוצאות באמצעות החלוקה לדפים. זה יכול להיות שימושי בגלל רוחב פס נמוך או תנאי רשת לא אמינים, לדוגמה, לפילוח תוצאה גדולה ליצירת תשובות קטנות יותר שאפשר לאחזר מחדש אם החיבור מתנתק. לעומת זאת, ה-method SearchStream משדרת את התוצאה כולה בתגובה אחת, והיא יכולה להיות יעילה יותר לאחזור נתונים בכמות גדולה.
Search ו-SearchStream משתמשים באותה כתובת URL בסיסית:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
שיטת החיפוש מבוססת-הדף מקבלת פרמטר pageSize אופציונלי, שמגביל את מספר התוצאות שמוחזרות בתגובה אחת מה-API.
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'"
}