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