Method: events.ingest

تحميل قائمة بموارد Event من Destination المقدَّمة

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل 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,
  "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)
    }
  ],
  "conversionValue": number
}
الحقول
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

اختياريّ. رمز العملة المرتبط بجميع القيم النقدية ضِمن هذا الحدث.
eventSource

enum (EventSource)

اختياريّ. إشارة إلى مكان وقوع الحدث (على الويب أو في التطبيق أو داخل المتجر أو غير ذلك)
eventDeviceInfo

object (DeviceInfo)

اختياريّ. معلومات يتم جمعها عن الجهاز المستخدَم (إن وُجد) عند وقوع الحدث
cartData

object (CartData)

اختياريّ. معلومات عن المعاملة والسلع المرتبطة بالحدث
customVariables[]

object (CustomVariable)

اختياريّ. معلومات إضافية عن أزواج المفاتيح/القيم لإرسالها إلى حاويات الإحالات الناجحة (إجراء الإحالة الناجحة أو نشاط Floodlight)
experimentalFields[]

object (ExperimentalField)

اختياريّ. قائمة بأزواج المفتاح/القيمة للحقول التجريبية التي قد تتم ترقيتها في النهاية لتصبح جزءًا من واجهة برمجة التطبيقات.
userProperties

object (UserProperties)

اختياريّ. معلومات يقدّمها المعلِن عن المستخدِم في وقت وقوع الحدث.
eventName

string

اختياريّ. اسم الحدث مطلوب لأحداث "إحصاءات Google‏ 4".
clientId

string

اختياريّ. معرّف فريد لمثيل المستخدم لعميل ويب في مصدر بيانات الويب هذا على "إحصاءات Google‏ 4"
userId

string

اختياريّ. معرّف فريد للمستخدِم، كما يحدّده المعلِن.
additionalEventParameters[]

object (EventParameter)

اختياريّ. مجموعة من أي مَعلمات أحداث سيتم تضمينها في الحدث ولم يتم تحديدها من قبل باستخدام حقول منظَّمة أخرى
conversionValue

number

اختياريّ. قيمة الإحالة الناجحة المرتبطة بالحدث، وذلك للإحالات الناجحة المستندة إلى القيمة

AdIdentifiers

المعرّفات والمعلومات الأخرى المستخدَمة لمطابقة حدث الإحالة الناجحة مع النشاط الآخر على الإنترنت (مثل النقرات على الإعلانات)

تمثيل JSON 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  }
}
الحقول
sessionAttributes

string

اختياريّ. سمات الجلسة لتحديد مصدر الأحداث ووضع نماذج لها
gclid

string

اختياريّ. معرّف النقرة من Google ‏ (gclid) المرتبط بهذا الحدث.
gbraid

string

اختياريّ. معرّف النقرة للنقرات المرتبطة بأحداث التطبيق والتي تأتي من أجهزة iOS بدءًا من الإصدار 14 من نظام التشغيل iOS
wbraid

string

اختياريّ. معرّف النقرة للنقرات المرتبطة بالأحداث على الموقع الإلكتروني والتي تأتي من أجهزة iOS بدءًا من الإصدار 14 من نظام التشغيل iOS
landingPageDeviceInfo

object (DeviceInfo)

اختياريّ. المعلومات التي يتم جمعها عن الجهاز المستخدَم (إن وُجد) عند الوصول إلى الموقع الإلكتروني للمعلِن بعد التفاعل مع الإعلان

DeviceInfo

معلومات عن الجهاز المستخدَم (إن وُجد) عند وقوع الحدث

تمثيل JSON 
{
  "userAgent": string,
  "ipAddress": string
}
الحقول
userAgent

string

اختياريّ. سلسلة وكيل المستخدم للجهاز في السياق المحدّد
ipAddress

string

اختياريّ. عنوان IP للجهاز في السياق المحدّد

ملاحظة:لا تتيح "إعلانات Google" مطابقة عناوين IP للمستخدِمين النهائيين في المنطقة الاقتصادية الأوروبية أو المملكة المتحدة أو سويسرا. أضِف منطقًا لاستبعاد مشاركة عناوين IP من المستخدِمين في هذه المناطق بشكلٍ مشروط، وتأكَّد من تزويد المستخدِمين بمعلومات واضحة وشاملة حول البيانات التي تجمعها على مواقعك الإلكترونية وتطبيقاتك والمواقع الأخرى، والحصول على موافقتهم حيثما يقتضي القانون أو أي سياسات سارية من Google. اطّلِع على صفحة لمحة عن عمليات استيراد الإحالات الناجحة غير الإلكترونية لمزيد من التفاصيل.

EventSource

تمثّل هذه السمة مصدر الحدث.

عمليات التعداد
EVENT_SOURCE_UNSPECIFIED لم يتم تحديد EventSource. يجب عدم استخدامها مطلقًا.
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

الحقل مطلوب. تمثيل السلسلة لقيمة المَعلمة المطلوب ضبطها.

المتغيّر المخصّص

متغيّر مخصّص للإحالات الناجحة من الإعلانات

تمثيل 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

نوع العميل المرتبط بالحدث.

عمليات التعداد
CUSTOMER_TYPE_UNSPECIFIED Unspecified CustomerType. يجب عدم استخدامها مطلقًا.
NEW العميل جديد بالنسبة إلى المعلِن.
RETURNING يعود العميل إلى المعلِن.
REENGAGED تفاعل العميل مجددًا مع المعلِن.

CustomerValueBucket

قيمة العميل التي يحدّدها المعلِن

عمليات التعداد
CUSTOMER_VALUE_BUCKET_UNSPECIFIED Unspecified CustomerValueBucket. يجب عدم استخدامها مطلقًا.
LOW العميل ذو قيمة منخفضة.
MEDIUM العميل متوسط القيمة.
HIGH العميل بارز.

UserProperty

حزمة من أي خصائص مستخدم إضافية للمستخدم المرتبط بهذا الحدث

تمثيل JSON 
{
  "propertyName": string,
  "value": string
}
الحقول
propertyName

string

الحقل مطلوب. اسم خاصيّة المستخدِم المطلوب استخدامها
value

string

الحقل مطلوب. تمثّل هذه السلسلة قيمة خاصية المستخدم التي سيتم استخدامها.

EventParameter

مَعلمة الحدث لأحداث "إحصاءات Google‏ 4".

تمثيل JSON 
{
  "parameterName": string,
  "value": string
}
الحقول
parameterName

string

الحقل مطلوب. اسم المَعلمة التي سيتم استخدامها.
value

string

الحقل مطلوب. تمثيل السلسلة لقيمة المَعلمة المطلوب ضبطها.