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

يُرجى مراعاة أفضل الممارسات التالية عند استخدام 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 للمصادقة بشكل غير تفاعلي وآمن.

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