Method: events.ingest

העלאה של רשימת Event משאבים מהקובץ Destination שסופק.

בקשת HTTP

POST https://datamanager.googleapis.com/v1/events:ingest

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
שדות
destinations[]

object (Destination)

חובה. רשימת היעדים שאליהם יישלחו האירועים.
events[]

object (Event)

חובה. רשימת האירועים שיישלחו ליעדים שצוינו. אפשר לשלוח עד 2,000 משאבים מסוג Event בבקשה אחת.
consent

object (Consent)

אופציונלי. הסכמה ברמת הבקשה תחול על כל המשתמשים בבקשה. הסכמה ברמת המשתמש מבטלת את ההסכמה ברמת הבקשה, ואפשר לציין אותה בכל Event.
validateOnly

boolean

אופציונלי. למטרות בדיקה. אם true, הבקשה מאומתת אבל לא מבוצעת. מוחזרות רק שגיאות, ולא תוצאות.
encoding

enum (Encoding)

אופציונלי. חובה להעלאות של UserData. סוג הקידוד של מזהי המשתמשים. עבור מזהי משתמשים שעברו גיבוב, זהו סוג הקידוד של המחרוזת שעברה גיבוב. במקרה של מזהי משתמשים מוצפנים עם גיבוב, זהו סוג הקידוד של המחרוזת החיצונית המוצפנת, אבל לא בהכרח של המחרוזת הפנימית עם הגיבוב. כלומר, המחרוזת הפנימית עם הגיבוב יכולה להיות מקודדת בצורה שונה מהמחרוזת החיצונית המוצפנת. המערכת מתעלמת מהשדה הזה בהעלאות שאינן UserData.
encryptionInfo

object (EncryptionInfo)

אופציונלי. מידע על ההצפנה של העלאות ב-UserData. אם לא מוגדר, ההנחה היא שהפרטים המזהים שהועלו מגובבים אבל לא מוצפנים. המערכת מתעלמת מהשדה הזה בהעלאות שאינן UserData.

גוף התשובה

תגובה מIngestEventsRequest.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "requestId": string
}
שדות
requestId

string

המזהה שנוצר אוטומטית של הבקשה.

היקפי הרשאה

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/datamanager

אירוע

אירוע שמייצג אינטראקציה של משתמש עם אתר או אפליקציה של מפרסם.

ייצוג ב-JSON 
{
  "destinationReferences": [
    string
  ],
  "transactionId": string,
  "eventTimestamp": string,
  "lastUpdatedTimestamp": string,
  "userData": {
    object (UserData)
  },
  "consent": {
    object (Consent)
  },
  "adIdentifiers": {
    object (AdIdentifiers)
  },
  "currency": string,
  "conversionValue": number,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  },
  "eventName": string,
  "clientId": string,
  "userId": string,
  "additionalEventParameters": [
    {
      object (EventParameter)
    }
  ]
}
שדות
destinationReferences[]

string

אופציונלי. מחרוזת הפניה שמשמשת לקביעת היעד. אם השדה ריק, האירוע יישלח לכל destinations בבקשה.
transactionId

string

אופציונלי. המזהה הייחודי של האירוע. חובה להשתמש בפרמטר הזה כשעוקבים אחרי המרות שמבוססות על מספר מקורות נתונים.
eventTimestamp

string (Timestamp format)

חובה. השעה שבה האירוע התרחש.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים מלבד Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
lastUpdatedTimestamp

string (Timestamp format)

אופציונלי. הפעם האחרונה שבה האירוע עודכן.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים מלבד Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
userData

object (UserData)

אופציונלי. חלקים מפרטים שהמשתמשים סיפקו, שמייצגים את המשתמש שהאירוע משויך אליו.
consent

object (Consent)

אופציונלי. מידע על כך שהמשתמש המשויך סיפק סוגים שונים של הסכמה.
adIdentifiers

object (AdIdentifiers)

אופציונלי. מזהים ומידע אחר שמשמשים להתאמה של אירוע ההמרה לפעילות אונליין אחרת (כמו קליקים על מודעות).
currency

string

אופציונלי. קוד המטבע שמשויך לכל הערכים הכספיים באירוע הזה.
conversionValue

number

אופציונלי. ערך ההמרה שמשויך לאירוע, להמרות מבוססות-ערך.
eventSource

enum (EventSource)

אופציונלי. אות שמציין איפה האירוע קרה (באינטרנט, באפליקציה, בחנות וכו').
eventDeviceInfo

object (DeviceInfo)

אופציונלי. מידע שנאסף על המכשיר שבו נעשה שימוש (אם בכלל) כשהאירוע קרה.
cartData

object (CartData)

אופציונלי. מידע על העסקה ועל הפריטים שמשויכים לאירוע.
customVariables[]

object (CustomVariable)

אופציונלי. מידע נוסף על זוגות של מפתח/ערך לשליחה למאגרי התגים של ההמרות (פעולת המרה או פעילות FL).
experimentalFields[]

object (ExperimentalField)

אופציונלי. רשימה של צמדי מפתח/ערך לשדות ניסיוניים שעשויים בסופו של דבר להיכלל ב-API.
userProperties

object (UserProperties)

אופציונלי. מידע שהמפרסם העריך לגבי המשתמש בזמן שהאירוע התרחש.
eventName

string

אופציונלי. שם האירוע. חובה לאירועים ב-GA4.
clientId

string

אופציונלי. מזהה ייחודי של מופע המשתמש של לקוח אינטרנט במקור הנתונים הזה של GA4 לאתר.
userId

string

אופציונלי. מזהה ייחודי של משתמש, כפי שהוגדר על ידי המפרסם.
additionalEventParameters[]

object (EventParameter)

אופציונלי. מאגר של פרמטרים של אירועים שצריך לכלול באירוע, שלא צוינו כבר באמצעות שדות מובנים אחרים.

AdIdentifiers

מזהים ומידע אחר שמשמשים להתאמה של אירוע ההמרה לפעילות אונליין אחרת (כמו קליקים על מודעות).

ייצוג ב-JSON 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  }
}
שדות
sessionAttributes

string

אופציונלי. מאפייני סשן לשיוך אירועים ולבניית מודלים.
gclid

string

אופציונלי. מספר הקליק ב-Google‏ (gclid) שמשויך לאירוע הזה.
gbraid

string

אופציונלי. המזהה של קליקים שמשויכים לאירועים באפליקציה ומגיעים ממכשירי iOS בגרסה 14 ואילך.
wbraid

string

אופציונלי. המזהה של קליקים שמשויכים לאירועים באתר ומגיעים ממכשירי iOS בגרסה 14 ואילך.
landingPageDeviceInfo

object (DeviceInfo)

אופציונלי. מידע שנאסף על המכשיר שבו נעשה שימוש (אם יש כזה) בזמן הנחיתה באתר של המפרסם אחרי אינטראקציה עם המודעה.

DeviceInfo

מידע על המכשיר שבו נעשה שימוש (אם יש כזה) כשהאירוע קרה.

ייצוג ב-JSON 
{
  "userAgent": string,
  "ipAddress": string
}
שדות
userAgent

string

אופציונלי. מחרוזת סוכן המשתמש של המכשיר בהקשר הנתון.
ipAddress

string

אופציונלי. כתובת ה-IP של המכשיר בהקשר הנתון.

הערה: מערכת Google Ads לא תומכת בהתאמה של כתובות IP למשתמשי קצה באזור הכלכלי האירופי (EEA), בבריטניה (UK) או בשווייץ (CH). צריך להוסיף לוגיקה כדי להחריג באופן מותנה את שיתוף כתובות ה-IP של משתמשים מהאזורים האלה, ולוודא שאתם מספקים למשתמשים מידע ברור ומקיף לגבי הנתונים שאתם אוספים באתרים, באפליקציות ובנכסים אחרים שלכם, ומקבלים מהם הסכמה כנדרש על פי חוק או על פי מדיניות Google הרלוונטית. פרטים נוספים זמינים בדף מידע על ייבוא של נתוני המרות אופליין (OCI).

EventSource

מקור האירוע.

טיפוסים בני מנייה (enum)
EVENT_SOURCE_UNSPECIFIED מקור האירוע לא צוין. אסור להשתמש בו.
WEB האירוע נוצר מדפדפן אינטרנט.
APP האירוע נוצר מאפליקציה.
IN_STORE האירוע נוצר מעסקה בחנות.
PHONE האירוע נוצר משיחת טלפון.
OTHER האירוע נוצר ממקורות אחרים.

CartData

נתוני עגלת הקניות שמשויכים לאירוע.

ייצוג ב-JSON 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ]
}
שדות
merchantId

string

אופציונלי. מספר החשבון ב-Merchant Center שמשויך לפריטים.
merchantFeedLabel

string

אופציונלי. תווית הפיד ב-Merchant Center שמשויכת לפיד הפריטים.
merchantFeedLanguageCode

string

אופציונלי. קוד השפה לפי תקן ISO 639-1 שמשויך לפיד ב-Merchant Center שאליו מועלים הפריטים.
transactionDiscount

number

אופציונלי. סכום כל ההנחות שמשויכות לעסקה.
items[]

object (Item)

אופציונלי. רשימת הפריטים שמשויכים לאירוע.

פריט

מייצג פריט בעגלת הקניות שמשויך לאירוע.

ייצוג ב-JSON 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number,
  "itemId": string,
  "additionalItemParameters": [
    {
      object (ItemParameter)
    }
  ]
}
שדות
merchantProductId

string

אופציונלי. מזהה המוצר בחשבון Merchant Center.
quantity

string (int64 format)

אופציונלי. מספר הפריט שמשויך לאירוע.
unitPrice

number

אופציונלי. מחיר היחידה, לא כולל מס, משלוח והנחות ברמת העסקה.
itemId

string

אופציונלי. מזהה ייחודי לציון הפריט.
additionalItemParameters[]

object (ItemParameter)

אופציונלי. מאגר של פרמטרים של אירועים שקשורים לפריט שרוצים לכלול באירוע, שלא צוינו כבר באמצעות שדות מובנים אחרים.

ItemParameter

מאגר של פרמטרים של אירועים שקשורים לפריט שרוצים לכלול באירוע, שלא צוינו כבר באמצעות שדות מובנים אחרים.

ייצוג ב-JSON 
{
  "parameterName": string,
  "value": string
}
שדות
parameterName

string

חובה. שם הפרמטר שבו רוצים להשתמש.
value

string

חובה. הייצוג של ערך הפרמטר שרוצים להגדיר כמחרוזת.

CustomVariable

משתנה מותאם אישית להמרות ממודעות.

ייצוג ב-JSON 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
שדות
variable

string

אופציונלי. השם של המשתנה המותאם אישית שרוצים להגדיר. אם המשתנה לא נמצא ביעד שצוין, המערכת תתעלם ממנו.
value

string

אופציונלי. הערך שרוצים לאחסן במשתנה המותאם אישית.
destinationReferences[]

string

אופציונלי. מחרוזת הפניה שמשמשת לקביעה לאיזה מבין Event.destination_references צריך לשלוח את המשתנה המותאם אישית. אם לא תציינו ערך בשדה הזה, המערכת תשתמש בערך Event.destination_references.

ExperimentalField

שדה ניסיוני שמייצג שדות לא רשמיים.

ייצוג ב-JSON 
{
  "field": string,
  "value": string
}
שדות
field

string

אופציונלי. שם השדה שבו רוצים להשתמש.
value

string

אופציונלי. הערך של השדה שרוצים להגדיר.

UserProperties

מידע שהמפרסם העריך לגבי המשתמש בזמן שהאירוע התרחש. פרטים נוספים זמינים בכתובת https://support.google.com/google-ads/answer/14007601.

ייצוג ב-JSON 
{
  "customerType": enum (CustomerType),
  "customerValueBucket": enum (CustomerValueBucket),
  "additionalUserProperties": [
    {
      object (UserProperty)
    }
  ]
}
שדות
customerType

enum (CustomerType)

אופציונלי. סוג הלקוח שמשויך לאירוע.
customerValueBucket

enum (CustomerValueBucket)

אופציונלי. הערך של הלקוח לפי הערכת המפרסם.
additionalUserProperties[]

object (UserProperty)

אופציונלי. מאגר של מאפייני משתמש נוספים שמשויכים למשתמש שקשור לאירוע הזה.

CustomerType

סוג הלקוח שמשויך לאירוע.

טיפוסים בני מנייה (enum)
CUSTOMER_TYPE_UNSPECIFIED לא צוין סוג לקוח. אסור להשתמש בו.
NEW הלקוח חדש למפרסם.
RETURNING הלקוח חוזר אל המפרסם.
REENGAGED הלקוח יצר אינטראקציה חוזרת עם המפרסם.

CustomerValueBucket

הערך של הלקוח לפי הערכת המפרסם.

טיפוסים בני מנייה (enum)
CUSTOMER_VALUE_BUCKET_UNSPECIFIED ‫Unspecified CustomerValueBucket. אסור להשתמש בו.
LOW הלקוח הוא בעל ערך נמוך.
MEDIUM הלקוח הוא בעל ערך בינוני.
HIGH הלקוח רווחי.

UserProperty

מאגר של מאפייני משתמש נוספים שמשויכים למשתמש שקשור לאירוע הזה.

ייצוג ב-JSON 
{
  "propertyName": string,
  "value": string
}
שדות
propertyName

string

חובה. השם של מאפיין המשתמש שבו רוצים להשתמש.
value

string

חובה. ייצוג המחרוזת של הערך של מאפיין המשתמש שבו רוצים להשתמש.

EventParameter

פרמטר אירוע לאירועים ב-GA4.

ייצוג ב-JSON 
{
  "parameterName": string,
  "value": string
}
שדות
parameterName

string

חובה. שם הפרמטר שבו רוצים להשתמש.
value

string

חובה. הייצוג של ערך הפרמטר שרוצים להגדיר כמחרוזת.