Package google.ads.datamanager.v1

الفهرس

IngestionService

خدمة لإرسال بيانات الجمهور إلى الوجهات المتوافقة

IngestAudienceMembers

rpc IngestAudienceMembers(IngestAudienceMembersRequest) returns (IngestAudienceMembersResponse)

تحميل قائمة بموارد AudienceMember إلى Destination المقدَّم

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

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

rpc IngestEvents(IngestEventsRequest) returns (IngestEventsResponse)

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

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

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

rpc RemoveAudienceMembers(RemoveAudienceMembersRequest) returns (RemoveAudienceMembersResponse)

تزيل هذه الطريقة قائمة بموارد AudienceMember من Destination المقدَّمة.

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

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

AdIdentifiers

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

الحقول
session_attributes

string

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

string

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

string

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

string

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

DeviceInfo

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

AddressInfo

معلومات العنوان الخاصة بالمستخدم

الحقول
given_name

string

مطلوب. الاسم الأول للمستخدم، بأحرف صغيرة فقط، بدون علامات ترقيم، وبدون مسافات بيضاء في البداية أو النهاية، ومجزّأ باستخدام SHA-256
family_name

string

مطلوب. اسم العائلة للمستخدم، بأحرف صغيرة فقط، بدون علامات ترقيم، وبدون مسافات بيضاء في البداية أو النهاية، ومجزّأ باستخدام خوارزمية SHA-256
region_code

string

مطلوب. يشير ذلك إلى رمز المنطقة المكوّن من حرفَين حسب المعيار ISO-3166-1 alpha-2 الخاص بعنوان المستخدِم.
postal_code

string

مطلوب. الرمز البريدي لعنوان المستخدم

AudienceMember

تمثّل هذه السمة الفرد من الجمهور الذي سيتم إجراء العملية عليه.

الحقول
consent

Consent

اختياريّ. إعداد الموافقة للمستخدم
حقل الدمج data نوع البيانات التعريفية المطلوب إجراء عملية عليها يمكن أن تكون data إحدى القيم التالية فقط:
user_data

UserData

البيانات المقدَّمة من المستخدم والتي تحدّد هويته
pair_data

PairData

معرّفات Publisher Advertiser Identity Reconciliation (PAIR)
mobile_data

MobileData

بيانات تحدّد الأجهزة الجوّالة للمستخدم.

CartData

بيانات سلة التسوّق المرتبطة بالحدث.

الحقول
merchant_id

string

اختياريّ. معرّف Merchant Center المرتبط بالسلع.
merchant_feed_label

string

اختياريّ. تصنيف الخلاصة في Merchant Center المرتبط بخلاصة السلع
merchant_feed_language_code

string

اختياريّ. رمز اللغة بتنسيق ISO 639-1 المرتبط بخلاصة Merchant Center التي تمّ تحميل سلعك فيها.
transaction_discount

double

اختياريّ. مجموع كل الخصومات المرتبطة بالمعاملة.
items[]

Item

اختياريّ. قائمة السلع المرتبطة بالحدث.

إعدادات الموافقة بموجب قانون الأسواق الرقمية (DMA) للمستخدم

الحقول
ad_user_data

ConsentStatus

اختياريّ. تمثّل هذه السمة ما إذا كان المستخدم يوافق على بيانات مستخدمي الإعلانات.
ad_personalization

ConsentStatus

اختياريّ. تمثّل ما إذا كان المستخدِم يوافق على تخصيص الإعلانات.

ConsentStatus

تمثّل هذه السمة ما إذا كان المستخدم قد منح الموافقة أو رفضها أو لم يحدّدها.

عمليات التعداد
CONSENT_STATUS_UNSPECIFIED لم يتم تحديد أي قيمة.
CONSENT_GRANTED تمت الموافقة.
CONSENT_DENIED مرفوض

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

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

الحقول
variable

string

اختياريّ. اسم المتغيّر المخصّص الذي سيتمّ ضبطه. إذا لم يتم العثور على المتغيّر للوجهة المحدّدة، سيتم تجاهله.
value

string

اختياريّ. القيمة المطلوب تخزينها للمتغير المخصّص.
destination_references[]

string

اختياريّ. سلسلة مرجعية تُستخدَم لتحديد Event.destination_references التي يجب إرسال المتغيّر المخصّص إليها. إذا كان الحقل فارغًا، سيتم استخدام Event.destination_references.

CustomerType

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

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

CustomerValueBucket

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

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

الوجهة

منتج Google الذي ترسل البيانات إليه على سبيل المثال، حساب على "إعلانات Google".

الحقول
reference

string

اختياريّ. معرّف مورد Destination هذا، وهو معرّف فريد ضمن الطلب. يُستخدم للإشارة إلى Destination هذا في IngestEventsRequest.
login_account

ProductAccount

اختياريّ. الحساب المستخدَم لإجراء طلب البيانات هذا من واجهة برمجة التطبيقات لإضافة بيانات إلى operating_account أو إزالتها منه، يجب أن يكون login_account هذا لديه إذن الكتابة في operating_account. على سبيل المثال، حساب إداري تابع لـ operating_account، أو حساب مرتبط بـ operating_account.
linked_account

ProductAccount

اختياريّ. حساب يمكن للمستخدم الذي يجري الاتصال الوصول إليه من خلال login_account، وذلك من خلال ربط الحسابات. على سبيل المثال، قد يكون لدى login_account أحد شركاء البيانات إذن الوصول إلى linked_account أحد العملاء. قد يستخدم الشريك هذا الحقل لإرسال البيانات من linked_account إلى operating_account آخر.
operating_account

ProductAccount

مطلوب. الحساب الذي سيتم إرسال البيانات إليه أو إزالتها منه
product_destination_id

string

مطلوب. العنصر المطلوب إدخاله في حساب المنتج على سبيل المثال، معرّف شريحة جمهور في "إعلانات Google" أو معرّف شريحة جمهور في "مساحة العرض والفيديو 360".

DeviceInfo

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

الحقول
user_agent

string

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

string

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

الترميز

نوع الترميز للمعلومات التعريفية المجزأة

عمليات التعداد
ENCODING_UNSPECIFIED نوع الترميز غير محدَّد. يجب عدم استخدامها مطلقًا.
HEX الترميز السداسي
BASE64 ترميز Base 64

EncryptionInfo

معلومات التشفير للبيانات التي يتم استيعابها.

الحقول
حقل الدمج wrapped_key المفتاح المغلف المستخدَم لتشفير البيانات يمكن أن تكون wrapped_key إحدى القيم التالية فقط:
gcp_wrapped_key_info

GcpWrappedKeyInfo

معلومات حول المفتاح المغلف في Google Cloud Platform

الحدث

حدث يمثّل تفاعل مستخدم مع موقع إلكتروني أو تطبيق لأحد المعلِنين.

الحقول
destination_references[]

string

اختياريّ. سلسلة مرجعية تُستخدَم لتحديد الوجهة. إذا كان هذا الحقل فارغًا، سيتم إرسال الحدث إلى جميع destinations في الطلب.
transaction_id

string

مطلوب. المعرّف الفريد لهذا الحدث.
event_timestamp

Timestamp

مطلوب. الوقت الذي وقع فيه الحدث
last_updated_timestamp

Timestamp

اختياريّ. آخر مرة تم فيها تعديل الحدث
user_data

UserData

اختياريّ. أجزاء من البيانات المقدَّمة من المستخدِم، وتمثّل المستخدِم المرتبط بالحدث.
consent

Consent

اختياريّ. معلومات عمّا إذا كان المستخدم المرتبط قد قدّم أنواعًا مختلفة من الموافقة.
ad_identifiers

AdIdentifiers

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

string

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

double

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

EventSource

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

DeviceInfo

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

CartData

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

CustomVariable

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

ExperimentalField

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

UserProperties

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

EventSource

مصدر الحدث

عمليات التعداد
EVENT_SOURCE_UNSPECIFIED لم يتم تحديد EventSource. يجب عدم استخدامها مطلقًا.
WEB تم إنشاء الحدث من متصفّح ويب.
APP تم إنشاء الحدث من تطبيق.
IN_STORE تم إنشاء الحدث من معاملة داخل المتجر.
PHONE تم إنشاء الحدث من مكالمة هاتفية.
OTHER تم إنشاء الحدث من مصادر أخرى.

ExperimentalField

حقل تجريبي يمثّل الحقول غير الرسمية.

الحقول
field

string

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

string

اختياريّ. القيمة التي سيتم ضبط الحقل عليها.

GcpWrappedKeyInfo

معلومات عن المفتاح المغلف في Google Cloud Platform

الحقول
key_type

KeyType

مطلوب. نوع الخوارزمية المستخدَمة لتشفير البيانات
wip_provider

string

مطلوب. موفِّر مجموعة Workload Identity المطلوب لاستخدام مفتاح تشفير المفاتيح (KEK)
kek_uri

string

مطلوب. معرّف مورد Cloud Key Management Service على Google Cloud Platform
encrypted_dek

string

مطلوب. مفتاح تشفير البيانات المشفّر المشفّر base64

KeyType

نوع الخوارزمية المستخدَمة لتشفير البيانات

عمليات التعداد
KEY_TYPE_UNSPECIFIED نوع المفتاح غير محدَّد. يجب عدم استخدامها مطلقًا.
XCHACHA20_POLY1305 الخوارزمية XChaCha20-Poly1305

IngestAudienceMembersRequest

طلب تحميل أعضاء الجمهور إلى الوجهات المقدَّمة تعرض هذه السمة IngestAudienceMembersResponse.

الحقول
destinations[]

Destination

مطلوب. قائمة الوجهات التي سيتم إرسال أعضاء الجمهور إليها.
audience_members[]

AudienceMember

مطلوب. قائمة المستخدمين الذين سيتم إرسالهم إلى الوجهات المحدّدة يمكن إرسال 10,000 مورد AudienceMember كحدّ أقصى في طلب واحد.
consent

Consent

اختياريّ. موافقة على مستوى الطلب تنطبق على جميع المستخدمين في الطلب تتجاوز موافقة المستخدم الموافقة على مستوى الطلب، ويمكن تحديدها في كل AudienceMember.
validate_only

bool

اختياريّ. لأغراض الاختبار إذا كانت القيمة true، يتم التحقّق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط، وليس النتائج.
encoding

Encoding

اختياريّ. هذا الحقل مطلوب لتحميل المحتوى إلى UserData. نوع الترميز لمعرّفات المستخدمين بالنسبة إلى معرّفات المستخدمين المجزّأة، هذا هو نوع الترميز للسلسلة المجزّأة. بالنسبة إلى معرّفات المستخدمين المجزّأة والمشفّرة، هذا هو نوع الترميز للسلسلة الخارجية المشفّرة، ولكن ليس بالضرورة السلسلة الداخلية المجزّأة، ما يعني أنّه يمكن ترميز السلسلة الداخلية المجزّأة بطريقة مختلفة عن السلسلة الخارجية المشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.
encryption_info

EncryptionInfo

اختياريّ. معلومات التشفير لعمليات التحميل في UserData في حال عدم ضبط هذا الخيار، يُفترض أنّ المعلومات التعريفية المحمَّلة مجزّأة ولكنّها غير مشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.
terms_of_service

TermsOfService

اختياريّ. بنود الخدمة التي قبلها المستخدم أو رفضها.

IngestAudienceMembersResponse

ردّ من IngestAudienceMembersRequest

الحقول
request_id

string

المعرّف الذي يتم إنشاؤه تلقائيًا للطلب.

IngestEventsRequest

طلب تحميل أعضاء الجمهور إلى الوجهات المقدَّمة تعرض هذه السمة IngestEventsResponse.

الحقول
destinations[]

Destination

مطلوب. قائمة الوجهات التي سيتم إرسال الأحداث إليها.
events[]

Event

مطلوب. قائمة الأحداث المطلوب إرسالها إلى الوجهات المحدّدة يمكن إرسال 2,000 مورد Event كحدّ أقصى في طلب واحد.
consent

Consent

اختياريّ. موافقة على مستوى الطلب تنطبق على جميع المستخدمين في الطلب تتجاوز موافقة المستخدم الموافقة على مستوى الطلب، ويمكن تحديدها في كل Event.
validate_only

bool

اختياريّ. لأغراض الاختبار إذا كانت القيمة true، يتم التحقّق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط، وليس النتائج.
encoding

Encoding

اختياريّ. هذا الحقل مطلوب لتحميل المحتوى إلى UserData. نوع الترميز لمعرّفات المستخدمين بالنسبة إلى معرّفات المستخدمين المجزّأة، هذا هو نوع الترميز للسلسلة المجزّأة. بالنسبة إلى معرّفات المستخدمين المجزّأة والمشفّرة، هذا هو نوع الترميز للسلسلة الخارجية المشفّرة، ولكن ليس بالضرورة السلسلة الداخلية المجزّأة، ما يعني أنّه يمكن ترميز السلسلة الداخلية المجزّأة بطريقة مختلفة عن السلسلة الخارجية المشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.
encryption_info

EncryptionInfo

اختياريّ. معلومات التشفير لعمليات التحميل في UserData في حال عدم ضبط هذا الخيار، يُفترض أنّ المعلومات التعريفية المحمَّلة مجزّأة ولكنّها غير مشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.

IngestEventsResponse

ردّ من IngestEventsRequest

الحقول
request_id

string

المعرّف الذي يتم إنشاؤه تلقائيًا للطلب.

المنتج/الخدمة

تمثّل هذه السمة سلعة في سلّة التسوّق مرتبطة بالحدث.

الحقول
merchant_product_id

string

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

int64

اختياريّ. عدد هذه السلعة المرتبطة بالحدث
unit_price

double

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

MobileData

معرّفات الأجهزة الجوّالة للجمهور يجب توفير معرّف جهاز جوّال واحد على الأقل.

الحقول
mobile_ids[]

string

مطلوب. قائمة بمعرّفات الأجهزة الجوّالة (المعرّف الإعلاني/IDFA) يمكن تقديم 10 mobileIds كحدّ أقصى في AudienceMember واحد.

PairData

معرّفات PAIR للجمهور يجب توفير رقم تعريف PAIR واحد على الأقل.

الحقول
pair_ids[]

string

مطلوب. بيانات تحديد الهوية الشخصية المقدَّمة من Clean Room، والتي تمّت تجزئتها باستخدام SHA256 وتشفيرها باستخدام تشفير تبادلي لمنحنى إهليلجي باستخدام مفتاح الناشر لقائمة مستخدمي PAIR يمكن تقديم 10 pairIds كحدّ أقصى في AudienceMember واحد.

المنتج

تمثّل هذه السمة منتجًا معيّنًا من Google. يُستخدم لتحديد مواقع الحسابات والوجهات.

عمليات التعداد
PRODUCT_UNSPECIFIED منتج غير محدّد يجب عدم استخدامها مطلقًا.
GOOGLE_ADS إعلانات Google
DISPLAY_VIDEO_PARTNER شريك "مساحة العرض والفيديو 360"
DISPLAY_VIDEO_ADVERTISER مُعلِن على "مساحة العرض والفيديو 360"
DATA_PARTNER شريك البيانات

ProductAccount

تمثّل حسابًا محدّدًا.

الحقول
product

Product

مطلوب. المنتج الذي ينتمي إليه الحساب مثلاً: GOOGLE_ADS
account_id

string

مطلوب. رقم تعريف الحساب على سبيل المثال، رقم تعريف حسابك على "إعلانات Google".

RemoveAudienceMembersRequest

طلب إزالة مستخدمين من شريحة جمهور في الوجهات المقدَّمة تعرض هذه الدالة RemoveAudienceMembersResponse.

الحقول
destinations[]

Destination

مطلوب. قائمة الوجهات التي ستتم إزالة المستخدمين منها.
audience_members[]

AudienceMember

مطلوب. قائمة المستخدمين المطلوب إزالتهم
validate_only

bool

اختياريّ. لأغراض الاختبار إذا كانت القيمة true، يتم التحقّق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط، وليس النتائج.
encoding

Encoding

اختياريّ. هذا الحقل مطلوب لتحميل المحتوى إلى UserData. نوع الترميز لمعرّفات المستخدمين ينطبق ذلك فقط على الترميز الخارجي لمعرّفات المستخدمين المشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.
encryption_info

EncryptionInfo

اختياريّ. معلومات التشفير لعمليات التحميل في UserData في حال عدم ضبط هذا الخيار، يُفترض أنّ المعلومات التعريفية المحمَّلة مجزّأة ولكنّها غير مشفّرة. بالنسبة إلى عمليات التحميل غير UserData، يتم تجاهل هذا الحقل.

RemoveAudienceMembersResponse

ردّ من RemoveAudienceMembersRequest

الحقول
request_id

string

المعرّف الذي يتم إنشاؤه تلقائيًا للطلب.

TermsOfService

بنود الخدمة التي قبلها المستخدم أو رفضها.

الحقول
customer_match_terms_of_service_status

TermsOfServiceStatus

اختياريّ. بنود خدمة "مطابقة العملاء": https://support.google.com/adspolicy/answer/6299717 يجب قبول ذلك لجميع عمليات التحميل إلى قوائم مستخدمي "مطابقة العملاء".

TermsOfServiceStatus

تمثّل هذه السمة قرار المتصل بقبول بنود الخدمة أو رفضها.

عمليات التعداد
TERMS_OF_SERVICE_STATUS_UNSPECIFIED لم يتم تحديد أي قيمة.
ACCEPTED حالة تشير إلى أنّ المتصل اختار قبول بنود الخدمة.
REJECTED حالة تشير إلى أنّ المتصل اختار رفض بنود الخدمة.

UserData

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

الحقول
user_identifiers[]

UserIdentifier

مطلوب. معرّفات المستخدم يمكن تقديم عدة أمثلة من نوع البيانات نفسه (مثل عناوين بريد إلكتروني متعددة). لزيادة احتمال حدوث مطابقة، قدِّم أكبر عدد ممكن من المعرّفات. يمكن تقديم 10 userIdentifiers كحدّ أقصى في AudienceMember أو Event واحد.

UserIdentifier

معرّف واحد للمستخدم.

الحقول
حقل الدمج identifier يجب تحديد قيمة واحدة بالضبط. يمكن أن تكون identifier إحدى القيم التالية فقط:
email_address

string

عنوان بريد إلكتروني مجزّأ باستخدام دالة التجزئة SHA-256 بعد التسوية
phone_number

string

رقم الهاتف المجزّأ باستخدام دالة التجزئة SHA-256 بعد التسوية (معيار E164)
address

AddressInfo

المكوّنات المعروفة لعنوان المستخدم تحتوي على مجموعة من المعرّفات التي تتم مطابقتها كلها في آنٍ واحد.

UserProperties

معلومات يقدّمها المعلِن عن المستخدِم في وقت وقوع الحدث. لمزيد من التفاصيل، يُرجى الانتقال إلى https://support.google.com/google-ads/answer/14007601.

الحقول
customer_type

CustomerType

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

CustomerValueBucket

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