קובצי קריאה לישויות (ERF) הם ייצוגי JSON של אובייקטים בקמפיין של שותף, שנוצרים מדי יום וזמינים דרך Google Cloud Storage, על פי בקשה.
קרנות ERF הוצאו משימוש ביוני 2021. החל מ-31 באוקטובר 2024, תכנון משאבים ארגוניים (ERF) ייסגר באופן רשמי ולא יופק יותר. אנחנו ממליצים לכל המשתמשים הקיימים בקובץ קריאת ישויות לעבור ל-Display & Video 360 API כדי להמשיך לאחזר משאבים ב-Display & Video 360.
במדריך הזה מוסבר איך לבצע את המעבר מקובצי קריאה של ישויות אל Display & Video 360 API באמצעות:
- הצגת סקירה כללית על ההבדלים בין שני הממשקים
- השוואה בין טבלאות ERF לשירותי API
- מתן הדרכה על אחזור ישויות באמצעות ה-API
- אישור פערי נתונים קיימים
- הצגת מיפוי של כל שדות ERF לשדות משאבי API דומים
סקירה כללית
במעבר מ-ERF ל-Display & Video 360 API יש כמה הבדלים עיקריים, כולל:
- עדכניות הנתונים. משתני ERF נוצרים מדי יום בכמות גדולה בזמן שה-API מאחזר את הגרסה העדכנית ביותר של המשאב.
- מבנה המשאבים. ה-API משתמש במבנים של JSON שונים מ-ERF כדי לייצג את אותם סוגי משאבים. משאבים מסוימים, כמו הגדרות מיקוד ציבורי, עשויים להשתמש במרחב מזהה אחר.
- שיטת אחזור. ב-Display & Video 360 API אפשר לאחזר משאבים רק בנפרד, ברשימות מחולקות לדפים, או באמצעות העברות של נתונים ב-BigQuery, בניגוד לקובצי ה-JSON הגולמיים שמקבלים מ-ERF.
- היקף. בניגוד ל-ERF, בהיקף לפי מזהה שותף, רוב משאבי ה-API מוגבלים לפי מזהה המפרסם. המשאבים הכלולים בתשובות מוגבלים למשאבים שבהיקף הזה.
ייצוג של נתוני ERF ב-API
קובצי קריאה של ישויות מופרדים בטבלאות 'גלוי לכולם' ו'פרטי'. טבלאות ציבוריות מספקות מידע זמין ורלוונטי לכל המשתמשים, כמו ערכי טירגוט. טבלאות פרטיות מספקות נתונים ספציפיים לשותף, כמו קריאייטיב או משאבים של פריטים.
ב-Display & Video 360 API לא נעשה שימוש בדיכוטומיה הזו, אלא מאפשר אחזור של כל המידע הזה דרך שירותים שונים ושימוש במבני JSON שונים. בקטע הזה נשווה בין המידע שמסופק דרך טבלאות ERF ציבוריות ופרטיות, למידע שזמין דרך משאבים ושירותים של Display & Video 360 API.
מידע ציבורי
טבלאות ציבוריות של ERF מספקות חומרי עזר לשימושם של המשתמשים כאשר הם מפרשים את הגדרות הטירגוט של המשאבים הפרטיים שלהם שאוחזרו ומקצים טירגוט דרך קבוצת משנה של גרסאות של קובצי נתונים מובְנים (SDF) שהועלו דרך ממשק המשתמש. חומרי העזר זהים לכל המשתמשים, וכוללים מזהה מספרי שמשמש למיפוי ופרטים תיאוריים יותר כמו השם המוצג.
כשמשתמשים ב-Display & Video 360 API, אפשר לאחזר את פרטי העזר של הטירגוט דרך השירות targetingTypes.targetingOptions
. בדומה לטבלאות הציבוריות, השירות הזה מספק את המזהים והפרטים של אפשרויות המיקוד לסוג מיקוד ספציפי. תוכלו לעיין בדף הקיים הגדרת טירגוט עם דוגמה לקוד שמדגים אחזור של מזהה אפשרות טירגוט.
טבלאות ציבוריות ו-SDF
לפני SDF v7, קבצים של ישויות שנקראו וקובצי נתונים מובְנים משתמשים באותו מרחב מזהה להגדרות הטירגוט. אם אתם משתמשים בטבלאות ציבוריות של ERF כדי לפרש או להקצות הגדרות טירגוט באמצעות SDF, תוכלו במקום זאת להוריד את חומר העזר הזה בפורמט CSV דרך ממשק המשתמש של Display & Video 360.
החל מגרסה 7, המרחבים המזהים שמשמשים קבוצת משנה של עמודות של קובצי נתונים מובְנים עודכנו כדי להפריד בין ה-SDF מ-ERF, כדי שיתאימו יותר ל-Display & Video 360 API. למידע נוסף, אפשר לעיין במדריך להעברת נתונים (מיגרציה) ובמסמכי התיעוד.
משאבים פרטיים
טבלאות פרטיות של ERF מספקות תמונת מצב יומית של ההגדרות הנוכחיות של משאבים פרטיים שבבעלות שותף. בגלל הכמות העצומה של משאבים שאפשר ליצור בעזרת שותף יחיד, הקבצים האלה עלולים להיות גדולים מאוד וקשים להורדה ולעיבוד.
ב-API, לכל טבלה פרטית יש שירות תואם שמספק נקודות קצה לאחזור ולניהול של סוג המשאב הזה. אפשר לאחזר משאבים בכמות גדולה באמצעות שיטת הרשימה המתאימה לכל שירות. מבנה ה-JSON לכל משאב שונה ב-API בהשוואה ל-ERF, באמצעות שמות שדות שונים ומשאבים משותפים.
חלק מהמידע שזמין בייצוג ERF של משאב, כמו הגדרות טירגוט של משאב או אתרים של ערוץ, מיוצג ב-API כצאצאים של המשאב המקורי, וצריך לאחזר אותו באמצעות בקשות API נוספות.
אחזור ישויות ב-API
אפשר לאחזר משאבים ב-Display & Video 360 באמצעות בקשות ישירות ל-API או באמצעות ייבוא אוטומטי אל BigQuery.
בקשות API ישירות
כל סוג משאב ניתן לאחזר דרך שירות API אחר. אפשר לאחזר משאבים בנפרד או בכמות גדולה באמצעות שיטת get או list של השירות המתאים, בהתאמה. המאפיינים החשובים של שיטות ליצירת רשימות ב-Display & Video 360 API כוללים:
- היקף נדרש. בניגוד למסגרות ERF, בהיקף של שותף, רוב המשאבים ב-API מוקצים על ידי מפרסם. אחזור של כל סוג משאב, כמו פריטים, במסגרת שותף, עשוי לדרוש בקשה נפרדת לכל מפרסם צאצא של אותו שותף. מקרים חריגים כוללים צאצאים ישירים של שותף, כמו מפרסמים וערוצים בבעלות שותפים.
- עימוד. בשיטות רשימת API נעשה שימוש בעימוד כדי להבטיח שהתגובות יהיו בגודל סביר, ומגבילות את רוב התגובות הנפרדות לבקשות או הדפים ל-100 משאבים. במקרה שמספר המשאבים הרלוונטיים גדול מהגודל של הדף, יש צורך בקריאות רצופות לרשימה כדי לאחזר את הדפים הבאים של התשובה המלאה לרשימה. קטע לדוגמה של קוד לשליחת תגובה של רשימה מופיע בקטע בדף המדריך למיקוד, בנוגע לאחזור אפשרויות מיקוד זמינות .
- בקשות נוספות שנדרשות כדי לטרגט אחזור הגדרות הטירגוט של משאב מסוים לא נכללות באובייקט ה-API של ה-API, אלא משאבים צאצאים שנקראים אפשרויות טירגוט שהוקצו. צריך לאחזר את המשאבים הצאצאים באמצעות בקשה נפרדת. לדוגמה, לכל פריט שאוחזר בבקשת
advertisers.lineItems.list
, צריך להגיש בקשה נפרדת ל-advertisers.lineItems.bulkListAssignedTargetingOptions
כדי לאחזר את כל פרטי הטירגוט.
אופטימיזציה לאחזור משאבים
ייתכן ש-Display & Video 360 API יחייב מספר בקשות כדי לאחזר את אותה כמות של מידע שזמינה בקובץ קריאה יחיד של ישות. אופטימיזציה של אופן אחזור המשאבים יכולה לעזור לכם לאחזר את הנתונים הדרושים לכם ביעילות רבה יותר:
- שליחת בקשות בו-זמניות ל-API. Display & Video 360 API מגן על התשתית באמצעות מגבלות על מספר הבקשות למפרסם לכל פרויקט. מבנה המכסות הזה מאפשר לכם להטמיע פתרון עם מספר שרשורים אצל כמה מפרסמים, וכך לקצר את הזמן הכולל שנדרש כדי לאחזר את כל המשאבים הנדרשים. העימוד מחייב שכל המשאבים מסוג בטווח מסוים יאוחזרו באמצעות קריאות עוקבות, אבל אפשר לאחזר בו-זמנית משאבים בהיקף אחר או מסוג אחר.
- שימוש במסננים ובסדר לפי פרמטרים בקריאות לרשימה כדי לאחזר רק משאבים רלוונטיים. לדוגמה, אם אתם מתעניינים רק בפריטים שעודכנו ביום האחרון, אפשר להשתמש בפרמטר
filter
של השיטהadvertisers.lineItems.list
כדי להחזיר רק פריטים עםupdateTime
גדול מחותמת זמן נתונה. מצב כזה יכול לצמצם משמעותית את מספר הבקשות שצריך לשלוח. - מומלץ לשמור מזהים שמשתמשים בהם באופן קבוע כדי למנוע בקשות API מיותרות. פרטי עזר מסוימים, כמו מזהים של אפשרויות טירגוט ומזהים של קהלים ב-Google, הם יציבים יחסית ואפשר לאחסן אותם בבטחה כדי שלא יהיה צורך באחזור בכל שימוש. עם זאת, יש לבדוק את הערכים שנשמרו במטמון על בסיס שבועי, כדי להביא בחשבון שינויים או מוציאים משימוש לא תכופים.
מידע נוסף על גישה יעילה ל-Display & Video 360 API זמין במדריך לאופטימיזציה של מכסות.
ייבוא אל BigQuery
מחבר Display & Video 360 API BigQuery מאפשר לייבא באופן אוטומטי הגדרות של משאבי Display & Video 360 ישירות ל-BigQuery על בסיס יומי. ההגדרות נשמרות ב-BigQuery באמצעות תכנון המשאבים של Display & Video 360 API. יש תמיכה בקבוצת משנה של משאבי API.
כדי לקבל מידע נוסף על השימוש ב-Display & Video 360 API BigQuery Connector, תוכלו להיעזר במסמכי התיעוד הבאים בענן:
- מהו שירות העברת נתונים ל-BigQuery?
- תזמון העברה ב-Display & Video 360
- טרנספורמציה של נתונים ב-Display & Video 360
פערי נתונים ידועים ב-API
יש פערי נתונים משמעותיים שאתם עשויים להיתקל בהם במהלך המעבר מ-ERF ל-Display & Video 360 API, כמו:
- הזמנות קמפיינים של סטוריז. לא ניתן לאחזר הזמנות קמפיין דרך ה-API, וצריך לאחזר אותן דרך ממשק המשתמש של Display & Video 360.
- קבוצת משנה של שדות משאבים. מספר קטן של שדות משאבים שנמצאים באובייקטים של ERF לא זמינים במשאבים המתאימים שאוחזרו דרך Display & Video 360 API.
נספח: מיפוי שדות ERF ל-API
מיפוי טבלה ציבורית
בטבלאות שבהמשך מתבצע מיפוי של השדות בטבלאות ציבוריות של ERF לשדות קיימים של אפשרויות טירגוט ושל אפשרויות טירגוט ב-Display & Video 360 API. הערך של שדה אחד עשוי להיות ממופה לשדה אחר, אבל לא מובטח שייעשה שימוש באותו סוג נתונים, באותו ערך 'טיפוסים בני מנייה (enum)' או באותו מרחב מזהה.
אוסף אפליקציות
ניתן לאחזר בקטע 'סוג טירגוט'
TARGETING_TYPE_APP_CATEGORY
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
name |
TargetingOption.appCategoryDetails.displayName
.
|
דפדפן
ניתן לאחזר לפי סוג הטירגוט TARGETING_TYPE_BROWSER
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
is_mobile | לא זמין. |
name |
TargetingOption.browserDetails.displayName
.
|
DataPartner
אין משאבים או שדות מקבילים שזמינים ב-Display & Video 360 API.
DeviceCriteria
ניתן לאחזר בקטע 'סוגי טירגוט'
TARGETING_TYPE_OPERATING_SYSTEM
,
TARGETING_TYPE_DEVICE_MAKE_MODEL
ו-TARGETING_TYPE_DEVICE_TYPE
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
או
DeviceType
טיפוסים בני מנייה (enum).
|
is_mobile | לא זמין. |
name |
TargetingOption.operatingSystemDetails.displayName
,
TargetingOption.deviceMakeModelDetails.displayName
או
DeviceType
טיפוסים בני מנייה (enum), בהתאם לסוג הטירגוט.
|
criteria_type |
TargetingOption.targetingType
.
|
operating_system_id | לא זמין. |
mobile_brand_name | לא זמין. |
mobile_model_name | לא זמין. |
mobile_make_model_id | לא זמין. |
device_type |
DeviceType
'טיפוסים בני מנייה (enum)'.
|
GeoLocation
ניתן לאחזר לפי סוג הטירגוט TARGETING_TYPE_GEO_REGION
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
canonical_name |
TargetingOption.geoRegionDetails.displayName
.
|
geo_name | לא זמין. |
country_code | לא זמין. |
region_code | לא זמין. |
city_name | לא זמין. |
postal_name | לא זמין. |
dma_code | לא זמין. |
Isp
ניתן לאחזר לפי סוג הטירגוט TARGETING_TYPE_CARRIER_AND_ISP
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
is_mobile | לא זמין. |
name |
TargetingOption.carrierAndIspDetails.displayName
.
|
secondary_criteria_id |
TargetingOption.targetingOptionId
.
|
שפה
ניתן לאחזר לפי סוג הטירגוט TARGETING_TYPE_LANGUAGE
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
name | לא זמין. השם המוצג המלא של שפה כלשהי זמין בשדה
TargetingOption.languageDetails.displayName
.
|
SiteToPlacementId
אין משאבים או שדות מקבילים שזמינים ב-Display & Video 360 API.
SupportedExchange
ניתן לאחזר לפי סוג הטירגוט TARGETING_TYPE_EXCHANGE
.
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
Exchange
'טיפוסים בני מנייה (enum)'.
|
name |
Exchange
'טיפוסים בני מנייה (enum)'.
|
UniversalSite
אין משאבים או שדות מקבילים שזמינים ב-Display & Video 360 API. אפשר לטרגט אתרים ואפליקציות ספציפיים ישירות לפי סוגי הטירגוט TARGETING_TYPE_URL
ו-TARGETING_TYPE_APP
, בהתאמה.
ב-Display & Video 360 ניתן לטרגט לכל אפליקציה או כתובת URL, אבל לא ניתן לדווח על כל אפליקציה או כתובת URL. כדי להסיר מההוצאות אפליקציות וכתובות URL שלא ניתן לדווח עליהן, צריך לפעול לפי ההוראות במרכז העזרה של DV360.
מיפוי השדות בטבלה פרטית
בטבלאות הבאות מתבצע מיפוי של השדות של טבלאות פרטיות של ERF לשדות או לשירותים קיימים ב-Display & Video 360 API. הערך של שדה אחד עשוי להיות ממופה לשדה אחר, אבל זה לא מבטיח שישתמשו באותו סוג נתונים, באותו ערך 'טיפוסים בני מנייה (enum)' או באותו מרחב מזהה.
מפרסם
קמפיין
שם שדה ERF | זמינות של DV360 API |
---|---|
common_data.id |
Campaign.campaignId
.
|
common_data.name |
Campaign.displayName
.
|
common_data.active |
Campaign.entityStatus
.
|
common_data.integration_code | לא זמין. |
advertiser_id |
Campaign.advertiserId
.
|
תקציב |
Campaign.campaignFlight
ו-
Campaign.campaignBudgets
.
|
frequency_cap |
Campaign.frequencyCap
.
|
default_target_list | ניתן לאחזר באמצעות שיטת
advertisers.campaigns.bulkListCampaignAssignedTargetingOptions
.
|
uses_video_creatives | לא זמין. |
uses_display_creatives | לא זמין. |
uses_audio_creatives | לא זמין. |
יעד |
Campaign.campaignGoal.campaignGoalType
.
|
ערך |
Campaign.campaignGoal.performanceGoal.performanceGoalType
.
|
objective_description |
Campaign.campaignGoal.performanceGoal.performanceGoalString
.
|
metric_amount_micros |
Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros
.
|
קריאייטיב
שם שדה ERF | זמינות של DV360 API |
---|---|
common_data.id |
Creative.creativeId
.
|
common_data.name |
Creative.displayName
.
|
common_data.active |
Creative.entityStatus
.
|
common_data.integration_code |
Creative.integrationCode
.
|
advertiser_id |
Creative.advertiserId
.
|
dcm_placement_id |
Creative.cmPlacementId
.
|
width_pixels |
Creative.dimensions.widthPixels
.
|
height_pixels |
Creative.dimensions.heightPixels
.
|
approval_status |
Creative.reviewStatus
.
|
expanding_direction |
Creative.expandingDirection
.
|
creative_type |
Creative.creativeType
.
|
CustomAffinity
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
CustomList.customListId
.
|
name |
CustomList.displayName
.
|
תיאור | לא זמין. |
advertiser_id | לא זמין. |
FloodlightActivity
שם שדה ERF | זמינות של DV360 API |
---|---|
common_data.id |
FloodlightActivity.floodlightActivityId
.
|
common_data.name |
FloodlightActivity.displayName
.
|
common_data.active |
FloodlightActivity.servingStatus
.
|
common_data.integration_code | לא זמין. |
advertiser_id |
בשדה
FloodlightActivity.advertiserIds
מפורטים כל המפרסמים שיש להם גישה לפעילות של Floodlight
במסגרת השותף הנתון.
|
partner_id | סופק על ידי המשתמש בעת שליחת בקשה לשירות floodlightGroups.floodlightActivities . |
remarketing_enabled |
בשדה
FloodlightActivity.remarketingConfigs
מפורטת ההגדרה הזו לכל מפרסם שיש לו גישה
לפעילות של Floodlight במסגרת השותף הנתון.
|
ssl_required |
FloodlightActivity.sslRequired
.
|
InsertionOrder
שם שדה ERF | זמינות של DV360 API |
---|---|
common_data.id |
InsertionOrder.insertionOrderId
.
|
common_data.name |
InsertionOrder.displayName
.
|
common_data.active |
InsertionOrder.entityStatus
.
|
common_data.integration_code |
InsertionOrder.integrationDetails.integrationCode
.
|
advertiser_id |
InsertionOrder.advertiserId
.
|
campaign_id |
InsertionOrder.campaignId
.
|
overall_budget | לא זמין. אפשר לחשב את הערך הזה באמצעות התוכן של השדה
InsertionOrder.budget.budgetSegments
.
|
scheduled_segments |
InsertionOrder.budget.budgetSegments
.
|
frequency_cap |
InsertionOrder.frequencyCap
.
|
default_partner_costs |
InsertionOrder.partnerCosts
.
|
default_target_list | ניתן לאחזר באמצעות שיטת
advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions
.
|
InventorySource
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
InventorySource.inventorySourceId
.
|
ללא סיווג | לא זמין. |
inventory_name |
InventorySource.displayName
.
|
exchange_id |
InventorySource.exchange
.
|
accessing_advertisers |
InventorySource.readWriteAccessors
ו-
InventorySource.readAdvertiserIds
.
|
external_id |
InventorySource.dealId
.
|
min_cpm_micros |
InventorySource.rateDetails.rate.nanos
, בהתאם לערך בשדה
InventorySource.rateDetails.inventorySourceRateType
.
|
min_cpm_currency_code |
InventorySource.rateDetails.rate.currencyCode
.
|
LineItem
NegativeKeywordList
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
NegativeKeywordList.negativeKeywordListId
.
|
name |
NegativeKeywordList.displayName
.
|
advertiser_id |
NegativeKeywordList.advertiserId
.
|
שותף/ה
שם שדה ERF | זמינות של DV360 API |
---|---|
common_data.id |
Partner.partnerId
.
|
common_data.name |
Partner.displayName
.
|
common_data.active |
Partner.entityStatus
.
|
common_data.integration_code | לא זמין. |
currency_code |
Partner.generalConfig.currencyCode
.
|
exchange_settings |
Partner.exchangeConfig.enabledExchanges
.
|
default_partner_costs | לא זמין. |
default_partner_revenue | לא זמין. |
default_target_list | לא זמין. |
Pixel
אין משאבים או שדות מקבילים שזמינים ב-Display & Video 360 API.
UniversalChannel
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
Channel.channelId
.
|
name |
Channel.displayName
.
|
site_ids | ניתן לאחזר באמצעות
advertisers.channels.sites.list
ושיטות
partners.channels.sites.list
, בהתאם לסוג
owner
.
|
accessing_advertisers | לא זמין. |
is_deleted | לא זמין. |
is_brand_safe_channel | לא זמין. |
UserList
שם שדה ERF | זמינות של DV360 API |
---|---|
id |
FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId
.
|
name |
FirstAndThirdPartyAudience.displayName
.
|
data_partner_id | לא זמין. |
accessing_advertisers | לא זמין. |
partner_pricing | לא זמין. |
advertiser_pricings | לא זמין. |