העברה מקובצי קריאה של ישויות

קובצי קריאה לישויות (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, תוכלו להיעזר במסמכי התיעוד הבאים בענן:

פערי נתונים ידועים ב-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 Advertiser.advertiserId .
common_data.name Advertiser.displayName .
common_data.active Advertiser.entityStatus .
common_data.integration_code Advertiser.integrationDetails.integrationCode .
partner_id Advertiser.partnerId .
currency_code Advertiser.generalConfig.currencyCode .
timezone_code Advertiser.generalConfig.timeZone .
landing_page_url Advertiser.generalConfig.domainUrl .
available_channel_ids ניתן לאחזר באמצעות שיטת advertisers.channels.list .
blacklist_channel_id ניתן לאחזר אותו בשיטת advertisers.targetingTypes.assignedtargetingOptions.list בסוג הטירגוט TARGETING_TYPE_CHANNEL . אם AssignedTargetingOption.channelDetails.negative נכון, הערוץ מטורגט באופן שלילי.
dcm_configuration לא זמין.
dcm_network_id Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id בשדה Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds מפורטים מזהי המפרסמים ב-CM360 שיש להם את הגדרות Floodlight ב-CM360.
dcm_floodlight_group_id Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags לא זמין.

קמפיין

שם שדה 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

שם שדה ERFזמינות של DV360 API
common_data.id LineItem.lineItemId .
common_data.name LineItem.displayName .
common_data.active LineItem.entityStatus .
common_data.integration_code LineItem.integrationDetails.integrationCode .
line_item_type LineItem.lineItemType .
insertion_order_id LineItem.insertionOrderId .
creative_ids LineItem.creativeIds .
max_cpm_advertiser_micros LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros או LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , בהתאם לסכמת האסטרטגיה שבה נעשה שימוש.
performance_goal LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType או LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , בהתאם לסכמת האסטרטגיה שבה נעשה שימוש.
goal_advertiser_micros LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model LineItem.partnerRevenueModel .
cost_tracking_pixels LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec LineItem.flight.dateRange.startDate .
budget.end_time_usec LineItem.flight.dateRange.endDate .
budget.max_impressions LineItem.budget.maxAmount אם LineItem.budget.budgetUnit הוא BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros LineItem.budget.maxAmount אם LineItem.budget.budgetUnit הוא BUDGET_UNIT_CURRENCY .
budget.pacing_type LineItem.pacing.pacingPeriod .
budget.pacing_max_impressions LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution LineItem.pacing.pacingType .
frequency_cap LineItem.frequencyCap .
partner_costs LineItem.partnerCosts .
target_list ניתן לאחזר באמצעות שיטת advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

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 לא זמין.