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,
  "conversionValue": number,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  }
}
الحقول
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)

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

object (ExperimentalField)

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

object (UserProperties)

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

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
}
الحقول
merchantProductId

string

اختيارية: معرّف المنتج في حساب Merchant Center
quantity

string (int64 format)

اختيارية: عدد هذه السلعة المرتبطة بالحدث
unitPrice

number

اختيارية: سعر الوحدة غير شامل للضرائب أو تكاليف الشحن أو أيّ خصومات على مستوى المُعاملة.

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

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

تمثيل 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)
}
الحقول
customerType

enum (CustomerType)

اختيارية: نوع العميل المرتبط بالحدث.
customerValueBucket

enum (CustomerValueBucket)

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

CustomerType

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

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

CustomerValueBucket

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

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