ב-Google Ads API יש מנגנון מאוחד לאחזור מאפיינים ולדיווח על מדדים שמאפשר ליצור שאילתות באמצעות שפת השאילתות של Google Ads. כך מתאפשרות שאילתות מורכבות שיכולות להחזיר כמויות גדולות של נתונים לגבי חשבונות Google Ads נפרדים.
אפשר ליצור שאילתות באמצעות אחת מהשיטות Search או SearchStream.
שתי השיטות תומכות באותן שאילתות ומחזירות תוצאות זהות. השיטה Search מחזירה נתונים בדפים בגודל קבוע של 10,000 שורות, ומאפשרת לבצע איטרציה על קבוצת תוצאות באמצעות חלוקה לדפים. זה יכול להיות שימושי במקרה של רוחב פס נמוך או תנאי רשת לא אמינים, לדוגמה, כדי לפלח תוצאה גדולה המוגדרת לתגובות קטנות יותר, שאפשר לאחזר מחדש אם החיבור מתנתק. לעומת זאת, ה-method 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'" }