המדריך הזה עוסק במשאבים לפתרון בעיות ב-RTB, המאפשרים לגשת באופן פרוגרמטי למדדים של קמפיינים לבידינג בזמן אמת שנחשפים גם דרך הכלי מעברון מסוג RTB שנמצא בממשק המשתמש של Authorized Buyers. הערכים האלה כוללים את bidders.filterSets, את bidders.accounts.filterSets ואת
כל המשאבים בהיררכיה.
באמצעות מדדים מהמשאבים לפתרון בעיות ב-RTB, אפשר לקבל תובנות לגבי הזדמנויות שהוחמצו להשגת חשיפות ולבצע אופטימיזציה של הקמפיין לבידינג בזמן אמת.
שינויים במבנה ובסגנון של ה-API
המשאבים לפתרון בעיות ב-RTB כוללים כמה שינויים שנועדו לציין באופן מפורש את הבעלות ואת הגישה, לספק שליטה מפורטת יותר על הנתונים שה-API מחזיר, ולהתאים בצורה טובה יותר לשיטות התכנון של Google API.
משאבים ברמת מגיש הצעת המחיר וברמת החשבון
המשאבים מובְנים גם ב-bidders וגם ב-bidders.accounts. הרשימות האלה מאפשרות לכם לציין
אם קריאה ל-API מטרגטת מגיש הצעות מחיר (שנקרא גם חשבון הורה) ולכל חשבונות הצאצא המשויכים אליו או לחשבונות Authorized Buyers ספציפיים. בהקשר של פתרון בעיות בבידינג בזמן אמת (RTB),
משאבים שמובְנים ב-bidders.filterSets יחזירו מדדים נצברים
לגבי מגיש הצעות המחיר הזה וכל חשבונות הצאצא שמשויכים אליו. לעומת זאת, חשבונות מתחת
ל-bidders.accounts.filterSets יחזירו מדדים רק לגבי החשבון שצוין,
לא משנה אם זה חשבון של מגיש הצעות מחיר או של חשבון צאצא.
הערה: חשבונות שמאצילים את הבידינג לקונה אחר הם לא חשבונות של מגישי הצעות מחיר, ולכן הם לא יכולים לגשת למשאבים ברמת מגיש הצעות המחיר. כמו כן, לחשבונות שאינם מגישי הצעות מחיר אין גישה
למשאבים ברמת החשבון: impressionMetrics, filteredBidResponses, bidResponseErrors
ו-bidResponsesWithoutBids.
חדש: שמות של משאבים כמזהים ייחודיים
שמות משאבים משמשים כמזהים ייחודיים ולא כמזהים של מספרים שלמים או מחרוזות. כשיוצרים מופע חדש של סוג משאב מסוים, צריך לציין שם משאב יחסי באמצעות נתיב ה-URI של המשאב ואחריו מזהה המשאב המועדף. השמות הבאים הם דוגמאות לשמות שרלוונטיים למשאבים לפתרון בעיות ב-RTB:
| משאב | דוגמה לשם |
|---|---|
| bidders.filterSets | bidders/12345678/filterSets/fset_1 |
| bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
הערה: מזהה המשאב שצוין עבור bidders בשם חייב להיות מספר חשבון Authorized Buyers של מגיש הצעות המחיר. ב-accounts, מזהה המשאב חייב להיות מזהה חשבון של
מגיש הצעות המחיר או חשבון צאצא שמנוהל על ידיו. אם לא ידוע לך אילו חשבונות Authorized Buyers משויכים לחשבון Google שלך, אפשר לחפש אותם באמצעות השיטה
accounts.list.
קבוצות סינון
קבוצת מסננים היא ייצוג של אפשרויות הסינון הזמינות, ואפשר ליצור אותה ברמת מגיש הצעות המחיר או ברמת החשבון. הוא משמש לסינון התוצאות ברשימה של משאבים לפתרון בעיות ב-RTB שמאחזרים מדדים מקמפיינים בבידינג בזמן אמת.
המסנן שיוחל במהלך אחזור המדדים הוא החיתוך של כל מסנן בקבוצת המסננים
שצוינה. מסנני רשימות, כגון platforms, מתפרשים כאיחוד של כל אחד מהפריטים ברשימה.
קבוצות של מסננים ברמת החשבון ומגיש הצעות המחיר נפרדות, וניתן לגשת אליהן רק מהרמה שבה הן נוצרו. לא משנה באיזה חשבון השתמשת כדי ליצור אותן. קבוצות של מסננים לשיתוף חשבון של מגיש הצעות מחיר ושל חשבון צאצא שנוצרו ברמת החשבון, ואילו רק מגיש הצעות המחיר יכול לגשת למשאבים ברמת מגיש הצעות המחיר. הטבלה הבאה מסכמת איך חשבונות של מגישי הצעות מחיר וחשבונות צאצא יכולים לגשת למשאבים בכל אחת מהרמות:
| bidders.filterSets | bidders.accounts.filterSets | |
|---|---|---|
| חשבון מגיש הצעות מחיר | קריאה ל-API משפיעה רק על קבוצות מסננים ברמת מגיש הצעות המחיר. | קריאה ל-API משפיעה רק על קבוצות מסננים ברמת החשבון. |
| חשבון צאצא | הקריאה הזו ל-API תחזיר הודעת שגיאה. | קריאה ל-API משפיעה רק על קבוצות מסננים ברמת החשבון. |
יצירת קבוצת מסננים
כשיוצרים קבוצת מסננים, צריך לציין טווח זמן כ-relativeDateRange,
absoluteDateRange או כ-realtimeTimeRange. במהלך אחזור מדדים, התנהגות ברירת המחדל היא שכל הנתונים יסופקו לכל טווח הזמן. אם רוצים לקבל פירוט של סדרת זמנים לאורך טווח הזמן, אפשר לציין timeSeriesGranularity
כדי לציין מרווחי זמן של HOURLY או DAILY.
אם רוצים להגדיר מסננים רק לפרק זמן קצר, אפשר להגדיר את פרמטר השאילתה isTransient ל-true. כאן יצוין שקבוצת המסננים היא זמנית, כלומר היא לא תיושם באופן סופי. קבוצות מסננים זמניות יהיו זמינות למשך שעה לפחות לאחר יצירתן, אבל בסופו של דבר הן יימחקו. כברירת מחדל, קבוצות מסננים אינן זמניות.
דוגמה ברמת מגיש הצעות המחיר
כדי ליצור קבוצת מסננים חדשה ברמת מגיש הצעות המחיר, צריך לשלוח בקשת POST ל-URI של המשאב bidders.filterSets, בפורמט הבא:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
אזהרה: אי אפשר לסנן קבוצות מסננים ברמת מגיש הצעות המחיר לפי קריאייטיב או מזהי עסקאות. אם מציינים את המסננים האלה כשיוצרים קבוצת מסננים ברמת מגיש הצעות המחיר, תתקבל הודעת שגיאה.
שליחת בקשהדוגמה לבקשת POST שיוצרת קבוצת מסננים חדשה ברמת מגיש הצעות המחיר:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
תשובה
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס 200 OK. גוף התגובה יכלול את המשאב של קבוצת המסננים שנוצרה, שיהיה זהה לקבוצת המסננים שנשלחה בבקשה.
דוגמה ברמת החשבון
כדי ליצור קבוצת מסננים חדשה ברמת החשבון, צריך לשלוח בקשת POST
ל-URI של המשאב bidders.accounts.filterSets, בפורמט הבא:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
הערה: מזהה המשאב שצוין ל-accounts יכול להיות
מספר החשבון של כל חשבון Authorized Buyers נגיש לחשבון מגיש הצעות המחיר
שצוין ב-URI, כולל החשבון עצמו של מגיש הצעות המחיר.
דוגמה לבקשת POST שיוצרת קבוצת מסננים חדשה ברמת החשבון, שאינה זמנית:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
תשובה
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס 200 OK. גוף התגובה יכלול את המשאב של קבוצת המסננים שנוצרה, שיהיה זהה לקבוצת המסננים שנשלחה בבקשה.
השג קבוצת מסננים
שיטת אחזור יכולה לקבל קבוצת מסננים רק באותה רמה שבה היא נוצרה. לדוגמה, חשבון של מגיש הצעות מחיר צריך להשתמש ב-bidders.accounts.filterSets.get כדי לאחזר קבוצת מסננים שנוצרה ברמת החשבון ולא בשיטה bidders.filterSets.get.
ברמת מגיש הצעות המחיר
כדי לאחזר מסנן שהוגדר ברמת מגיש הצעות המחיר, יש לשלוח בקשת HTTP GET ל-URI של המשאב bidders.filterSets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
בקשה
לדוגמה:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsתשובה
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס HTTP 200 OK ומערך המסננים שאוחזר:
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
ברמת החשבון
ניתן לאחזר מסנן ברמת החשבון שהוגדר על ידי שליחה של בקשת GET HTTP ל-URI של המשאב bidders.accounts.filterSets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
בקשה
לדוגמה:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsתשובה
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס HTTP 200 OK ומערך המסננים שאוחזר:
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
קבוצות של מסנני רשימה
שיטת הרשימה תחזיר רק קבוצות מסננים שניתן לגשת אליהן מהרמה שאליה היא נקראת.
לדוגמה, חשבון של מגיש הצעות מחיר לא יראה קבוצות מסננים שנוצרו לעצמו דרך
bidders.accounts.filterSets.create כשמפעילים את bidders.filterSets.list.
ברמת מגיש הצעות המחיר
ניתן לאחזר את כל קבוצות המסננים ברמת מגיש הצעות המחיר עבור מגיש הצעות מחיר נתון על ידי שליחה של בקשת GET HTTP אל ה-URI של המשאב bidders.filtersets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
בקשה
הנה דוגמה של כל קבוצות המסננים ברמת מגיש הצעות המחיר של מגיש הצעות מחיר עם מספר חשבון 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsתשובה
{
"filterSets": [{
"filterSetId": "99994",
"name": "bidders/12345678/filterSets/test-b-1",
"relativeDateRange": {
"durationDays": 30
}
},
{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-15T12:30:30.072831583Z"
},
"filterSetId": "99995",
"name": "bidders/12345678/filterSets/test-b-2",
"timeSeriesGranularity": "HOURLY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 12,
"month": 3,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99996",
"name": "bidders/12345678/filterSets/bidder-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["TABLET", "MOBILE"],
"environment": "APP",
"format": "DISPLAY"
}
]
}
ברמת החשבון
אפשר לאחזר את כל קבוצות המסננים ברמת החשבון עבור חשבון נתון על ידי שליחה של בקשת HTTP GET
ל-URI של המשאב bidders.accounts.filtersets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
בקשה
הנה דוגמה של כל קבוצות המסננים ברמת החשבון עבור חשבון צאצא שמספר החשבון שלו הוא 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsתשובה
{
"filterSets": [{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-19T04:24:43.252893487Z"
},
"filterSetId": "99997",
"name": "bidders/12345678/accounts/87654321/filterSets/test-a-1",
"timeSeriesGranularity": "DAILY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 3,
"month": 12,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99998",
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["DESKTOP"],
"environment": "WEB",
"format": "VIDEO"
}
]
}
מחיקה של קבוצת מסננים
אפשר להשתמש בשיטה delete כדי להסיר קבוצות מסננים לא זמניות שכבר אין בהן צורך. ניתן להסיר קבוצות מסננים שניתן לגשת אליהן רק מהרמה שבה היא נקראת. לדוגמה, חשבון של מגיש הצעות מחיר לא יכול למחוק קבוצת מסננים שנוצרה באמצעות bidders.accounts.filterSets.create
עם הערך bidders.filterSets.delete.
ברמת מגיש הצעות המחיר
כדי למחוק קבוצת מסננים ברמת מגיש הצעות המחיר עבור חשבון נתון, יש לשלוח בקשת HTTP DELETE
ל-URI של המשאב bidders.filtersets, בפורמט הבא:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
בקשה
לפניכם דוגמה למחיקה של קבוצת מסננים ברמת מגיש הצעות המחיר:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2תשובה
אם הביצוע יהיה תקין, גוף הבקשה יהיה ריק. לא ניתן יהיה לגשת יותר לקבוצת המסננים שצוינה.
ברמת החשבון
כדי למחוק קבוצת מסננים ברמת החשבון עבור חשבון נתון, יש לשלוח בקשת HTTP DELETE
ל-URI של המשאב bidders.accounts.filtersets, בפורמט הבא:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
בקשה
הנה דוגמה למחיקת קבוצת מסננים ברמת החשבון:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1תשובה
אם הביצוע יהיה תקין, גוף הבקשה יהיה ריק. לא ניתן יהיה לגשת יותר לקבוצת המסננים שצוינה.
אחזור מדדים של פתרון בעיות ב-RTB
כל המשאבים לפתרון בעיות ב-RTB שמשמשים לקבלת מדדים פועלים באופן דומה – יש להם שיטה אחת לפירוט המדדים של קבוצת המסננים שצוינה באמצעות פרמטר נתיב
filterSetName. קבוצת המסננים שצוינה תקבע אילו מסננים והגדרות יחולו
בעת שליחת שאילתות על המדדים. קריאה למשאבים האלה ברמת מגיש הצעות המחיר תחזיר מדדים נצברים
מהחשבון של מגיש הצעות המחיר ומכל חשבונות הצאצא המשויכים. לעומת זאת, קריאה ברמת החשבון
תחזיר מדדים רק לגבי חשבון פרטי.
ערכי הצעות מחיר
המשאב bidMetrics משמש לאחזור מדדים שנמדדים
במספר הצעות המחיר. לדוגמה, אפשר להשתמש במידע הזה כדי לקבוע את המספר הכולל של הצעות המחיר
בטווח תאריכים נתון, וכמה מהן לא סוננו מהמכרז, זכו בחשיפה
וכו'. כמו כל המשאבים האחרים לפתרון בעיות ב-RTB שמשמשים לאיסוף מדדים, יש לו רק שיטה list.
הצגת רשימה של מדדי הצעות מחיר ברמת מגיש הצעות המחיר
אפשר להציג מדדי הצעות מחיר ברמת מגיש הצעות המחיר עבור קבוצת מסנן נתונה על ידי שליחה של בקשת HTTP GET
ל-URI של המשאב bidders.filtersets.bidMetrics, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics
בקשה
דוגמה למדדי הצעות מחיר ברמת מגיש הצעות המחיר:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsתשובה
אם הבקשה תתבצע בהצלחה, השרת יחזיר קוד סטטוס 200 OK וגוף שמכיל שורות של מדדים למאפיינים ולרמת הפירוט שצוינו.
{
"bidMetricsRows": [{
"bids": {
"value": "6160"
},
"bidsInAuction": {
"value": "5698"
},
"billedImpressions": {
"value": "1196"
},
"impressionsWon": {
"value": "2920"
},
"measurableImpressions": {
"value": "1160"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-29T08:00:00Z",
"startTime": "2017-11-28T08:00:00Z"
}
},
"viewableImpressions": {
"value": "683"
}
},
{
"bids": {
"value": "104288"
},
"bidsInAuction": {
"value": "94016"
},
"billedImpressions": {
"value": "99"
},
"impressionsWon": {
"value": "125"
},
"measurableImpressions": {
"value": "94"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-30T08:00:00Z",
"startTime": "2017-11-29T08:00:00Z"
}
},
"viewableImpressions": {
"value": "87"
}
},
{
"bids": {
"value": "3999"
},
"bidsInAuction": {
"value": "3631"
},
"billedImpressions": {
"value": "618"
},
"impressionsWon": {
"value": "1819"
},
"measurableImpressions": {
"value": "604"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "369"
}
},
{
"bids": {
"value": "15"
},
"bidsInAuction": {
"value": "3"
},
"billedImpressions": {},
"impressionsWon": {
"value": "3"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
הערה: שדות שהוגדרו ל-0 למדד נתון לא יופיעו בתשובה.
המדדים הריקים billedImpressions ו-measurableImpressions שלמעלה
מציינים שגם הערך וגם השונות של אלה מוגדרים ל-0.
אזהרה: בתגובה לכל פירוט של נתונים בתשובה, התשובה לא תכלול שורות אם הן לא מכילות לפחות מדד אחד שאינו אפס. לדוגמה, אם מציינים timeSeriesGranularity, התגובה לא תכלול שורות של timeInterval בטווח הזמן שצוין בקבוצת המסננים, שבו כל המדדים הם אפס.
הצגת רשימה של מדדי הצעות מחיר ברמת החשבון
ניתן להציג מדדי הצעות מחיר ברמת החשבון עבור קבוצת מסננים נתונה על ידי שליחה של בקשת HTTP GET
ל-URI של המשאב bidders.accounts.filtersets.bidMetrics, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics
בקשה
הנה דוגמה למדדי הצעות מחיר ברמת החשבון:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsתשובה
אם הבקשה תתבצע בהצלחה, השרת יחזיר קוד סטטוס 200 OK וגוף שמכיל שורות של מדדים למאפיינים ולרמת הפירוט שצוינו.
{
"bidMetricsRows": [{
"bids": {
"value": "1748"
},
"bidsInAuction": {
"value": "1421"
},
"billedImpressions": {
"value": "301"
},
"impressionsWon": {
"value": "915"
},
"measurableImpressions": {
"value": "298"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "172"
}
},
{
"bids": {
"value": "6"
},
"bidsInAuction": {
"value": "2"
},
"billedImpressions": {},
"impressionsWon": {
"value": "1"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
הערה: שדות שהוגדרו ל-0 למדד נתון לא יופיעו בתשובה. הערכים הריקים billedImpressions ו-measurableImpressions שלמעלה מציינים
שהערך והשונות של אלה מוגדרים ל-0.
אזהרה: בתגובה לכל פירוט של נתונים בתגובה, התגובה לא תכלול שורות אם הן לא מכילות לפחות מדד אחד שאינו אפס. לדוגמה, אם מציינים timeSeriesGranularity, התגובה לא תכלול שורות של timeInterval בטווח הזמן שצוין בקבוצת המסננים, שבו כל המדדים הם אפס.