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

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

استخدِم request_id الذي تم عرضه مع RetrieveRequestStatus للتحقّق من حالة التحميل ومراجعة بيانات التشخيص.

في ما يلي سير العمل المقترَح للتحقّق من حالة طلباتك والتأكّد من سلامة عمليات تحميل الأحداث والجمهور:

1. إصدار طلبات لإرسال الأحداث أو إرسال أو إزالة عضو في الجمهور.

2. التحقّق من الحالة العامة لكل طلب نقل بيانات يحتوي الطلب الناجح على Status مع code يساوي 0 (قيمة التعداد OK، استجابة HTTP‏ 200 OK)، ويعرض IngestEventsResponse أو IngestAudienceMembersResponse أو RemoveAudienceMembersResponse.

   إذا لم يتم تنفيذ الطلب بنجاح، عدِّله لمعالجة الخطأ وأرسِله مرة أخرى.

   إذا نجح الطلب، احفظ request_id من الاستجابة لتتمكّن من استخدامه للتحقّق من حالة المعالجة في الخطوة التالية.

   ملاحظة: يمكنك فقط التحقّق من الحالة واسترداد بيانات التشخيص للطلبات التي تنجح ولا يتم ضبط validate_only فيها على true.

3. يُرجى الانتظار لمدة 30 دقيقة، ثم إرسال طلب RetrieveRequestStatus لكل عملية request_id ناجحة.

   يتطلّب RetrieveRequestStatusRequest قيمة واحدة من النوع request_id. أرسِل طلب حالة منفصلاً لكل معرّف طلب حصلت عليه من طلب استيعاب ناجح.

   ملاحظة: جرِّب إرسال طلب في متصفّحك باستخدام "مستكشف واجهات برمجة التطبيقات".

   كرِّر هذه الخطوة بشكل دوري لكل request_id إلى أن تصل حالة الوجهة لكل وجهة إلى SUCCESS أو PARTIAL_SUCCESS أو FAILED. اتّبِع استراتيجية الاستطلاع المقترَحة للانتظار بين كل طلب.

4. راجِع كل RetrieveRequestStatusResponse للتأكّد من أنّ عمليات التحميل تعمل بشكل صحيح وتحديد أي مشاكل في بياناتك.

5. حلّ المشاكل المتعلّقة بالبيانات

6. ارجع إلى الخطوة 1 وكرِّرها إلى أن تتم معالجة جميع المشاكل في عمليات التحميل.

التحقّق من حالة الوجهة بشكل عام

يحتوي العنصر request_status_per_destination في RetrieveRequestStatusResponse على إدخال منفصل لكل وجهة في طلب نقل البيانات المقابل.

على سبيل المثال، إذا كان IngestAudienceMembersRequest يحتوي على 3 إدخالات في قائمة destinations لإرسال البيانات إلى 3 شرائح جمهور مختلفة، ستحتوي استجابة الحالة على 3 إدخالات في request_status_per_destination (إدخال واحد لكل شريحة جمهور).

تحقَّق من حقل request_status في كل RequestStatusPerDestination لتحديد ما إذا كانت واجهة Data Manager API قد انتهت من معالجة البيانات لتلك الوجهة.

في ما يلي القيم المحتمَلة لسمة request_status:

• ‫PROCESSING: لا تزال بيانات الوجهة قيد المعالجة. لا تتم تعبئة التحذيرات والأخطاء للوجهة في هذه المرحلة. يجب مواصلة الاستطلاع إلى أن تصل الحالة إلى حالة نهائية.

• ‫SUCCESS: اكتملت معالجة الطلب للوجهة بدون أي أخطاء. ابحث عن التحذيرات التي تم الإبلاغ عنها أثناء المعالجة.

• FAILED: تعذّر نقل جميع السجلّات إلى الوجهة بسبب أخطاء. تحقَّق من التحذيرات والأخطاء لتحديد سبب تعذُّر جميع السجلات. تحقَّق أيضًا من التحذيرات التي تم الإبلاغ عنها أثناء المعالجة.

• PARTIAL_SUCCESS: نجحت بعض السجلات للوجهة، ولكن فشلت سجلات أخرى بسبب أخطاء. تحقَّق من الأخطاء لمعرفة سبب تعذُّر نقل بعض السجلات. يُرجى أيضًا التحقّق من التحذيرات التي تم الإبلاغ عنها أثناء المعالجة.

مراجعة بيانات التشخيص

عندما يصل request_status لوجهة معيّنة إلى SUCCESS أو FAILED أو PARTIAL_SUCCESS، راجِع بيانات التشخيص التفصيلية في الردّ للتحقّق من الأعداد وتحديد المشاكل وحلّها.

الاطّلاع على حالة الحدث أو شريحة الجمهور لكل وجهة

افحص حقل الحالة الذي يتوافق مع نوع طلب نقل البيانات. يتم ضبط حقل واحد فقط من الحقول التالية في كل RequestStatusPerDestination:

• events_ingestion_status

• audience_members_ingestion_status

• audience_members_removal_status

حالة عرض الأحداث

تتم تعبئة الحقل events_ingestion_status إذا كان الطلب IngestEventsRequest.

تحقَّق من record_count في IngestEventStatus للتأكّد من أنّ إجمالي عدد السجلّات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة والفاشلة.

حالة نقل بيانات أعضاء الجمهور

تتم تعبئة الحقل audience_members_ingestion_status إذا كان الطلب IngestAudienceMembersRequest. في ما يلي حقل IngestAudienceMembersStatus الذي يجب التحقّق منه لكل نوع من بيانات الجمهور. يتم ضبط حقل واحد فقط من هذه الحقول.

composite_data_ingestion_status

يُرجى التحقّق من record_count في IngestCompositeDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

يُرجى مراجعة data_type_counts للتأكّد من أنّ عدد المعرّفات يتطابق مع توقعاتك. تقدّم هذه القائمة تفاصيل عن جميع المعرّفات التي تلقّاها DataType (مثل عنوان البريد الإلكتروني ورقم الهاتف والعنوان الجغرافي وعنوان IP).

إذا كان الطلب يحتوي على عدد كافٍ من السجلات، يحتوي الحقل upload_match_rate_range على نطاق نسبة المطابقة للسجلات في الطلب.

google_user_id_data_ingestion_status

تحقَّق من record_count في IngestGoogleUserIdDataStatus للتأكّد من أنّ إجمالي عدد السجلّات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

يُرجى مراجعة google_user_id_count للتأكّد من أنّ عدد أرقام تعريف مستخدمي Google التي تم تلقّيها يتطابق مع توقعاتك.

mobile_data_ingestion_status

يُرجى التحقّق من record_count في IngestMobileDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

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

pair_data_ingestion_status

تحقَّق من record_count في IngestPairDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

يُرجى مراجعة pair_id_count للتأكّد من أنّ عدد معرّفات PAIR التي تم تلقّيها يتطابق مع توقعاتك.

partner_provided_id_data_ingestion_status

تحقَّق من record_count في IngestPartnerProvidedIdDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

يُرجى مراجعة partner_provided_id_count للتأكّد من أنّ عدد المعرّفات التي قدّمها الشريك والتي تم تلقّيها يتطابق مع توقعاتك.

ppid_data_ingestion_status

تحقَّق من record_count في IngestPpidDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

تحقَّق من ppid_count للتأكّد من أنّ عدد معرّفات PPID التي تم تلقّيها يتطابق مع توقعاتك.

user_data_ingestion_status

تحقَّق من record_count في IngestUserDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

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

إذا كان الطلب يحتوي على عدد كافٍ من السجلات، يحتوي الحقل upload_match_rate_range على نطاق نسبة المطابقة للسجلات في الطلب.

user_id_data_ingestion_status

تحقَّق من record_count في IngestUserIdDataStatus للتأكّد من أنّ إجمالي عدد السجلات التي تم تلقّيها يتطابق مع توقعاتك. يتضمّن record_count السجلّات الناجحة وغير الناجحة.

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

حالة إزالة عضو في الجمهور

تتم تعبئة الحقل audience_members_removal_status إذا كان الطلب RemoveAudienceMembersRequest. في ما يلي حقل RemoveAudienceMembersStatus الذي يجب التحقّق منه لكل نوع من بيانات الجمهور. يتم ضبط حقل واحد فقط من هذه الحقول.

composite_data_removal_status

حالة الإزالة للبيانات المركّبة

google_user_id_data_removal_status

حالة إزالة بيانات رقم تعريف مستخدم Google

mobile_data_removal_status

حالة الإزالة لبيانات الجوّال

pair_data_removal_status

حالة إزالة بيانات PAIR

partner_provided_id_data_removal_status

حالة الإزالة لبيانات مستندات التعريف المقدَّمة من الشريك

ppid_data_removal_status

حالة إزالة بيانات معرّف الجمهور المقدَّم من الناشر (PPID)

user_data_removal_status

حالة إزالة بيانات المستخدم

user_id_data_removal_status

حالة إزالة بيانات رقم تعريف المستخدم

يُرجى مراجعة record_count للتأكّد من أنّ إجمالي عدد السجلات المستلَمة يتطابق مع توقعاتك. يتضمّن record_count كلاً من السجلات الناجحة والفاشلة.

بالإضافة إلى ذلك، يمكنك مراجعة user_identifier_count أو mobile_id_count أو pair_id_count أو ppid_count أو user_id_count أو google_user_id_count أو partner_provided_id_count لتأكيد العدد الإجمالي للمعرّفات التي تم تلقّيها.

بالنسبة إلى البيانات المركّبة، يُرجى مراجعة data_type_counts للتأكّد من أنّ عدد المعرّفات يتطابق مع توقعاتك. تقدّم هذه القائمة تفاصيل عن جميع المعرّفات التي تلقّتها DataType (مثل عنوان البريد الإلكتروني ورقم الهاتف والعنوان الجغرافي وعنوان IP).

التحقّق من التحذيرات والأخطاء

بالإضافة إلى حقول الحالة للوجهة ونوع الطلب، يحتوي RetrieveRequestStatusResponse على تفاصيل التحذيرات والأخطاء الخاصة بالطلب.

• يشير الخطأ إلى أنّ واجهة برمجة التطبيقات رفضت السجلّ بالكامل.

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

على سبيل المثال، إذا كان Event يحتوي على بيانات UserIdentifier مشفّرة وAdIdentifiers مثل gclid، وتعذّر فك تشفير بيانات UserIdentifier، ستواصل Data Manager API معالجة السجلّ باستخدام AdIdentifiers، ولكنّها ستعرض التحذير PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR.

ومع ذلك، إذا لم يتضمّن Event السمة AdIdentifiers وتعذّر فك تشفير بيانات UserIdentifier، ترفض واجهة برمجة التطبيقات Data Manager API السجلّ بالكامل وتُبلغ عن الخطأ PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR لأنّ السمة Event الصالحة يجب أن تتضمّن السمة ad_identifiers أو user_data على الأقل.

في ما يلي حقول الاستجابة التي تحتوي على معلومات التحذير والخطأ. تتم تعبئة هذه الحقول عندما تصل الحالة الإجمالية للوجهة إلى SUCCESS أو PARTIAL_SUCCESS أو FAILED.

warning_info

وهو يمثّل عنصر WarningInfo. يحتوي حقل warning_counts على قائمة بعناصر WarningCount. يحتوي كل WarningCount على reason يتضمّن نوع التحذير، وrecord_count يشير إلى عدد السجلات التي تتضمّن هذا النوع من التحذير.

يُرجى التحقّق من warning_info حتى إذا كانت الحالة العامة للوجهة هي SUCCESS.

error_info

وهو يمثّل عنصر ErrorInfo. يحتوي حقل error_counts على قائمة من عناصر ErrorCount. يحتوي كل ErrorCount على reason مع نوع الخطأ، وrecord_count يشير إلى عدد السجلات التي تعذّر نقلها بسبب هذا النوع من الخطأ.

استراتيجية الاستطلاع

أرسِل RetrieveRequestStatusRequest بشكل دوري باستخدام خوارزمية الرقود الأسي الثنائي إلى أن يصل request_status إلى SUCCESS أو FAILED أو PARTIAL_SUCCESS لكل وجهة في الطلب الأصلي. قد يستغرق ذلك مدة تصل إلى 24 ساعة، مع أنّ واجهة برمجة التطبيقات Data Manager API قد تنتهي من معالجة بعض الطلبات في غضون 30 دقيقة فقط.

في ما يلي مثال على إعدادات معقولة لوقت الانتظار الأولي وإعادة المحاولة توازن بين الاستجابة واستخدام الحصة:

الإعداد	القيمة
وقت الانتظار قبل طلب بيانات التشخيص الأول (بالدقائق)	30
مُضاعِف التراجع	1.3
الحد الأقصى للتراجع (بالدقائق)	‫‎60 (ساعة واحدة)
الحد الأقصى لإجمالي الوقت (بالدقائق)	1440 (24 ساعة)

في ما يلي تسلسل الطلبات والوقت المنقضي مع هذه الإعدادات:

رسم بياني للدالة

البيانات

المحاولة	الوقت منذ طلب نقل البيانات (ساعة:دقيقة)	المهلة قبل المحاولة	ملاحظات
1	00:30	‫30.0 دقيقة	التحقّق أولاً من توفّر الحالة
2	01:09	‫39.0 دقيقة
3	01:59	‫50.7 دقيقة
4	02:59	‫60.0 دقيقة	تم تحديد الحد الأقصى للتأخير بساعة واحدة
5	03:59	‫60.0 دقيقة
6	04:59	‫60.0 دقيقة
7	05:59	‫60.0 دقيقة
8	06:59	‫60.0 دقيقة
9	07:59	‫60.0 دقيقة
10	08:59	‫60.0 دقيقة
11	09:59	‫60.0 دقيقة
12	10:59	‫60.0 دقيقة
13	11:59	‫60.0 دقيقة	‫12 ساعة
14	12:59	‫60.0 دقيقة
15	13:59	‫60.0 دقيقة
16	14:59	‫60.0 دقيقة
17	15:59	‫60.0 دقيقة
18	16:59	‫60.0 دقيقة
19	17:59	‫60.0 دقيقة
20	18:59	‫60.0 دقيقة
21	19:59	‫60.0 دقيقة
22	20:59	‫60.0 دقيقة
23	21:59	‫60.0 دقيقة
24	22:59	‫60.0 دقيقة
25	23:59	‫60.0 دقيقة	آخر طلب قبل بلوغ الحد الأقصى لإجمالي الوقت وهو 24 ساعة

أضِف مقدارًا عشوائيًا صغيرًا من التشويش إلى تأخيرات التراجع لتجنُّب مشكلة "الازدحام الشديد" التي تحدث عندما يحاول العديد من العملاء إعادة المحاولة في الوقت نفسه.

متطلبات التفويض

لا يقبل RetrieveRequestStatusRequest حسابات الوجهة أو عناوين الطلبات. بدلاً من ذلك، تحدّد Data Manager API الوجهات من طلب نقل البيانات الأصلي المرتبط بـ request_id وتتحقّق من أنّ المتصل لديه إذن الوصول إلى operating_account على كل Destination.

للتحقّق من حالة طلب معيّن، يجب أن تستوفي بيانات الاعتماد المستخدَمة في RetrieveRequestStatusRequest المتطلبات التالية لـ operating_account لكل وجهة من طلب نقل البيانات الأصلي:

• مسار الوصول نفسه: يجب أن تتيح بيانات الاعتماد الوصول إلى كل operating_account باستخدام مسار الوصول نفسه المحدّد في طلب نقل البيانات الأصلي.

  على سبيل المثال، إذا حدّد طلب نقل البيانات لحساب "إعلانات Google" operating_account حساب مدير رئيسي على أنّه login_account، يجب أن تملك بيانات الاعتماد أيضًا إذن الوصول إلى operating_account من خلال حساب المدير نفسه. حتى إذا كان حساب Google المرتبط ببيانات الاعتماد لديه إذن وصول مباشر إلى الحساب الفرعي operating_account، سيتعذّر تنفيذ الطلب وسيظهر الخطأ PERMISSION_DENIED إذا لم يكن لدى هذا الحساب إذن وصول من خلال حساب المدير login_account المحدّد أثناء عملية نقل البيانات.

• مستوى وصول كافٍ: يجب أن يكون لحساب Google المرتبط ببيانات الاعتماد مستوى وصول أو دور يمنحه الإذن بنقل البيانات إلى operating_account.

  على سبيل المثال، في "إعلانات Google"، يجب أن يكون لدى حساب Google مستوى الوصول الإداري أو العادي. يؤدي الطلب الذي يتضمّن بيانات اعتماد لحساب بمستوى الوصول للقراءة فقط إلى ظهور الخطأ PERMISSION_DENIED.