أفضل الممارسات

يُرجى مراعاة أفضل الممارسات التالية عند استخدام Data Manager API.

إرسال جميع معرّفات المستخدمين

سواء كنت ترسل أعضاء في الجمهور أو أحداثًا باستخدام UserData، يجب تضمين أكبر عدد ممكن من user_identifiers، بما في ذلك إرسال معرّفات متعددة من النوع نفسه.

على سبيل المثال، إذا كان لديك عدة عناوين بريد إلكتروني لمستخدم، يمكنك تضمين UserIdentifier منفصل لكل عنوان بريد إلكتروني. وبالمثل، إذا كانت لديك معرّفات من أنواع مختلفة لمستخدم معيّن، مثل عناوين البريد الإلكتروني وأرقام الهواتف والعناوين، أضِف UserIdentifier منفصلاً لكل معرّف، بحدّ أقصى يساوي العدد الأقصى للمعرّفات.

تحسين الطلبات

للحدّ من احتمال تجاوز سقف الطلبات اليومية، يمكنك تجميع أكبر عدد ممكن من العناصر في كل طلب، بما يصل إلى سقف الطلب الواحد.

على سبيل المثال، إذا أردت إضافة 10,000 عضو في الجمهور إلى جمهور معيّن، أضِف جميع الأعضاء البالغ عددهم 10,000 في قائمة audience_members في IngestAudienceMembersRequest واحدة. إنّ تجميع كل الأعضاء البالغ عددهم 10,000 في طلب واحد أكثر كفاءة من إرسال طلب منفصل لإضافة كل عضو في الجمهور.

إرسال طلبات متزامنة

لتقليل الوقت الإجمالي المطلوب لنقل البيانات، أرسِل طلبات متزامنة إلى IngestionService. ننصح بإرسال ما يصل إلى 10 طلبات في الوقت نفسه لتقليل احتمالية تجاوز الحدّ الأقصى لعدد الطلبات في الدقيقة.

يمكنك إرسال طلبات متزامنة حتى إذا كانت الطلبات تحتوي على نفس destinations.

التحقّق من صحة البيانات من جهة العميل

تستخدم واجهة Data Manager API نموذجًا سريعًا لمعالجة الأخطاء. إذا تعذّر التحقّق من صحة أي سجلّ في طلب متزامن، سيتعذّر تنفيذ الطلب بالكامل ولن تتم معالجة أي من السجلّات. بالإضافة إلى ذلك، تتحقّق واجهة برمجة التطبيقات من صحة الطلبات في مراحل متسلسلة، لذا قد يؤدي إصلاح خطأ واحد إلى الكشف عن خطأ من مرحلة تحقّق لاحقة.

لتجنُّب تكرار عمليات الذهاب والعودة ورفض الطلبات، عليك التحقّق من صحة بياناتك وتنظيفها قبل إرسالها:

• إزالة القيم الفارغة قبل التجزئة: تحقَّق من حقول مثل email_address وphone_number بحثًا عن سلاسل فارغة أو سلاسل تحتوي على مسافات بيضاء فقط قبل احتساب تجزئات SHA-256. تؤدي تجزئة سلسلة فارغة إلى إنشاء تجزئة صالحة تجتاز عمليات التحقّق من البنية ولكنّها تضرّ بنِسب المطابقة.

• إسقاط العناصر المركّبة غير المكتملة: تأكَّد من أنّ العناصر المركّبة تحتوي على جميع الحقول المطلوبة قبل إضافتها إلى سجلّ. على سبيل المثال، إذا كان عنصر AddressInfo لا يتضمّن أيًا من حقوله الأربعة المطلوبة (given_name أو family_name أو region_code أو postal_code)، يجب حذف معرّف address بالكامل لتجنُّب أخطاء REQUIRED_FIELD_MISSING.

• التحقّق من صحة حقول الترميز والنص العادي: تأكَّد من أنّ الحقول المجزّأة تتطابق مع encoding المُعلَن عنه بدلاً من إرسال نص عادي أولي، وتأكَّد من أنّ الحقول التي يجب أن تظل نصًا عاديًا (مثل mobile_ids) غير مجزّأة.

• فلترة الطوابع الزمنية خارج النطاق: تأكَّد من أنّ الطوابع الزمنية ليست في المستقبل أو أقدم من فترة معاينة الإعلان في الوجهة.

  إذا كنت ترسل الطلبات باستخدام JSON، تأكَّد من أنّ سلاسل الطوابع الزمنية تستخدم تنسيق RFC 3339 مع إزاحة المنطقة الزمنية.

• تنظيف أرقام الهواتف: تأكَّد من أنّ أرقام الهواتف تتضمّن رمز البلد وتستخدم تنسيق E.164 قبل التجزئة.

• إزالة السجلّات الفارغة أو الكبيرة جدًا: يمكنك وضع حدّ أقصى لسمة user_identifiers وفقًا للحدّ الأقصى لكل سجلّ (10 معرّفات)، وإسقاط المَعلمات المخصّصة الفارغة، وحذف أي سجلّ لا يحتوي على معرّفات صالحة.

• التحقّق من متطلبات حالات الاستخدام: تأكَّد من أنّ كل حدث يتضمّن جميع الحقول الإلزامية لوجهته وحالة استخدامه (مثل transaction_id للإحالات الناجحة الإلكترونية في "إعلانات Google"). للاطّلاع على قائمة كاملة بالحقول المطلوبة حسب حالة الاستخدام، يُرجى مراجعة دليل إرسال الأحداث لوجهتك في نظرة عامة على الأحداث.

• استخدام validateOnly لاختبار الطلبات: أرسِل الطلبات مع ضبط validateOnly على true لرصد أخطاء الفشل السريع بدون نقل البيانات أو إزالتها. لا يضمن نجاح طلب التحقّق فقط عدم حدوث أخطاء أثناء المعالجة غير المتزامنة، لذا عليك مواصلة التحقّق من حالة الطلب وبيانات التشخيص بعد إرسال طلب عادي.

للاطّلاع على قواعد التوحيد والتجزئة المفصّلة، يُرجى مراجعة مقالة تنسيق بيانات المستخدمين.

الاطّلاع على حالة الطلب وبيانات التشخيص

احصل على request_id من كل IngestAudienceMembersResponse أو IngestEventsResponse، واستخدِم أرقام تعريف الطلبات للاطّلاع على حالة الطلب وبيانات التشخيص.

مراقبة الحصص والتنبيه بشأنها

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

النشر في قناة الإصدار العلني

عند الانتقال من الاختبار على الجهاز إلى أعباء العمل في مرحلة الإنتاج، استخدِم بيانات الاعتماد التلقائية للتطبيق مع حساب خدمة مرفق أو Workload Identity Federation لإجراء المصادقة بشكل غير تفاعلي وآمن.

لمعرفة تفاصيل حول ضبط المصادقة لبيئات التشغيل الفعلي المختلفة، يُرجى الاطّلاع على النشر في بيئة التشغيل الفعلي.