دليل المطوّر لاستيراد البيانات

تعمل واجهة برمجة التطبيقات لإدارة Google Analytics على تفعيل الوصول الآلي إلى ميزة استيراد البيانات في "إحصاءات Google".

مقدمة

تسمح لك Management API بتحميل الملفات المحمَّلة وإدراجها وحذفها وتحميلها، بالإضافة إلى مجموعات بيانات القوائم. للحصول على نظرة عامة عالية المستوى على فوائد ميزة استيراد البيانات، يُرجى الاطّلاع على مقالة لمحة عن استيراد البيانات في مركز المساعدة.

المصدران في Management API اللذان يفعّلان "استيراد البيانات" هما:

• مورد مصدر البيانات المخصص، الذي يُطلق عليه مجموعة البيانات في واجهة الويب، والذي يعمل كحاوية للملفات التي تم تحميلها. تمثّل مجموعة مصادر البيانات المخصّصة جميع مجموعات البيانات المرتبطة بموقع على "إحصاءات Google".
• المورد Upload (تحميل)، الذي يمثل ملفًا تم تحميله. تمثل مجموعة موارد التحميل جميع الملفات التي حمّلتها إلى مجموعة بيانات.

حالات الاستخدام

تحتوي ميزة استيراد البيانات على ثلاث فئات من المستوى الأعلى، لكل منها حالات استخدام خاصة بها. المؤسسة هي كما يلي:

• استيراد البيانات
  • بيانات ردّ الأموال
• استيراد البيانات الموسّعة
  • بيانات المستخدمين
  • بيانات الحملة
  • البيانات الجغرافية
  • بيانات المحتوى
  • بيانات المنتج
• استيراد البيانات الموجزة
  • بيانات التكلفة

استيراد بيانات النتائج

بيانات رد الأموال

يمكن تحميل معاملات التجارة الإلكترونية التي تم ردّ أموالها كليًا أو جزئيًا إلى "إحصاءات Google". ويسهِّل ذلك تسوية البيانات تلقائيًا في تقارير التجارة الإلكترونية في "إحصاءات Google" مع عمليات ردّ الأموال التي تمت معالجتها.

لمعرفة كيفية استيراد بيانات ردّ الأموال إلى "إحصاءات Google"، اطّلِع على مثال على استيراد بيانات ردّ الأموال.

استيراد البيانات الموسّعة

بيانات المستخدم

يمكنك تحميل بيانات المستخدمين التي لا تحدّد الهوية الشخصية من أدوات إدارة علاقات العملاء الخارجية وإنشاء شرائح جمهور تجديد النشاط التسويقي في "إعلانات Google" لشرائح المستخدمين الأكثر أهمية بالنسبة إليك.

لمعرفة كيفية استيراد بيانات المستخدِمين إلى "إحصاءات Google" لإنشاء شرائح جمهور تجديد النشاط التسويقي في "إعلانات Google"، اطّلِع على ما يلي:

• استيراد بيانات المستخدمين لإنشاء شرائح جمهور تجديد النشاط التسويقي في "إعلانات Google".

بيانات الحملة

يمكنك استيراد بيانات الحملات إلى "إحصاءات Google" لتخصيص تحليل أداء حملتك بما يتوافق مع نشاطك التجاري.

لمعرفة كيفية استيراد بيانات الحملات إلى "إحصاءات Google"، يمكنك الاطلاع على استيراد بيانات الحملة باستخدام Management API.

البيانات الجغرافية

يمكنك استيراد تعيينات أرقام التعريف الجغرافية إلى المناطق، ما يسمح بإعداد تقارير عن بيانات "إحصاءات Google" حسب المنطقة المخصّصة. على سبيل المثال، في الولايات المتحدة، قد تعمل في مجموعات من الولايات الشرقية والوسطى والغربية، وفي أوروبا، قد تعمل في مجموعات من البلدان الشمالية والوسطى والجنوبية. عند استيراد البيانات، يمكنك استخدام ga:regionId أو ga:cityId أو ga:countryIsoCode أو ga:subContinentCode كمفاتيح. يمكنك العثور على أرقام تعريف المدن وأرقام تعريف البلدان في جدول "الاستهداف الجغرافي". يمكن العثور على رمز ISO للبلد ورمز القارة الفرعية في الجدولَين ISO-3166-1 alpha-2 وUN M.49 على التوالي.

لمزيد من المعلومات حول استيراد البيانات الجغرافية، راجع مثال على استيراد البيانات الجغرافية.

بيانات المحتوى

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

لمعرفة كيفية استيراد بيانات المحتوى إلى "إحصاءات Google"، يُرجى الاطّلاع على المقالة مثال على استيراد بيانات المحتوى.

بيانات المنتج

يعمل استيراد بيانات المنتج إلى Google Analytics على تبسيط وتقليل كمية بيانات التجارة الإلكترونية التي تحتاج إلى إرسالها مع النتائج، مثل مشاهدات الصفحة على الويب والأحداث. يمكن ضم معرّف منتج واحد أو رمز تخزين تعريفي واحد مع بيانات المنتج المستورَدة لتعبئة أبعاد المنتج ومقاييسه في تقاريرك.

لمعرفة كيفية استيراد بيانات المنتجات إلى "إحصاءات Google"، يمكنك الاطّلاع على استيراد بيانات المنتجات باستخدام Management API.

استيراد البيانات الموجزة

بيانات التكلفة

ويمكنك تحميل بيانات التكلفة للحملات المدفوعة التي لا تتبع Google والاستفادة من منصة "إحصاءات Google" لإجراء تحليل عائد الاستثمار ومقارنة أداء الحملة بالنسبة إلى جميع الاستثمارات الإعلانية والتسويقية على الإنترنت.

لمعرفة كيفية استيراد بيانات التكلفة إلى Google Analytics، راجع استيراد بيانات التكلفة باستخدام Management API.

المفاهيم

حالة المعالجة

بعد تحميل الملف، ستكون حالة التحميل PENDING إلى أن يتم التحقّق من صحة التحميل ومعالجته. إذا تمت المعالجة بنجاح، ستتغيّر الحالة إلى COMPLETED.

إذا حدث خطأ أثناء المعالجة ولم تنجح عملية التحميل، ستكون حالة التحميل FAILED. سيتم توفير قائمة بالأخطاء لمساعدتك في تحديد المشاكل المتعلّقة بالملف. في ما يلي مثال على ردّ على عملية تحميل تعذّر التحقّق منها:

{
  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
  errors:
  [
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."
  ]
}

ملاحظة: يمكنك إجراء طلب بحث بشكل دوري في Management API من أجل إدراج عمليات التحميل والاطّلاع على الحقل status.

جمع بيانات التكلفة مقابل الاستبدال

عند إنشاء مصدر بيانات مخصص / مجموعة بيانات لبيانات التكلفة، يتوفر لك خيار تحديد كيفية التعامل مع الحالات التي يحتوي فيها ملف محمّل على صف من البيانات يحتوي على مفتاح (أي تاريخ ومصدر ووسيط) يتطابق مع صف موجود. تشمل الخيارات ما يلي:

• summation (تلقائية) - ستتم إضافة البيانات الجديدة إلى أي بيانات مطابقة سابقة وسيتم جمع المقاييس معًا.
• استبدال - ستحل البيانات الجديدة محل أي بيانات مطابقة سابقة.

لمعرفة النوع الذي تمّ ضبطه لمجموعة بيانات، استخدِم طريقة قائمة مصادر البيانات المخصّصة للتحقّق ممّا إذا تمّ ضبط السمة importBehavior على OVERWRITE أو SUMMATION.

مجموع البيانات على مستوى صف بيانات التكلفة مقابل الاستبدال

ويمكنك أيضًا تجاوز سلوك مجموعة البيانات لكل ملف تحمّله عن طريق تضمين عمود "ga:importBehavior" في العنوان. وعلى أساس كل صف، يمكنك ضبط القيمة ga:importBehavior على SUMMATION أو OVERWRITE.

على سبيل المثال، سيستبدل الملف التالي أي بيانات تكلفة سابقة في كلّ من Facebook/تكلفة النقرة وYahoo/تكلفة النقرة، ولكن ستتم إضافة صفّ Bing/تكلفة النقرة إلى أي بيانات تكلفة حالية لهذه المجموعة المحدّدة من التاريخ والمصدر/الوسيط.

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior
20140604,facebook,cpc,12.23,OVERWRITE
20140604,bing,cpc,3.23,SUMMATION
20140604,yahoo,cpc,11.23,OVERWRITE

التنسيق والقيود

لتحميل البيانات إلى "إحصاءات Google"، يجب أن تكون بتنسيق ملف CSV منسَّق بشكل صحيح. يصف هذا القسم القيود التي يجب استيفاؤها قبل اعتباره صالحًا للتحميل إلى جميع أنواع "استيراد البيانات".

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

القيود على الملف

• الترميز: UTF-8
• الحدّ الأقصى لحجم الملف: 1 غيغابايت

قيود العنوان

• يعتبر الصف الأول رأس عمود وهو مطلوب. يجب أن يُحدِّد الأبعاد والمقاييس التي سيتضمّنها عمود معيّن.

القيود على الصف

• الحدّ الأقصى لعدد الصفوف المسموح به هو 1 ميغابايت.

تنسيق الخلايا

• يمكن أن يصل طول الخلايا إلى 2048 حرفًا كحد أقصى.
• ستتم إزالة المسافات في البداية والنهاية لخلية.
• لتحديد فاصلة داخل خلية، يجب أن تكون قيمة الخلية داخل علامات الاقتباس المزدوجة. على سبيل المثال: source1,"medium,ether",group1,100 - قيمة الخلية الثانية هي medium,ether.
• لتحديد علامات اقتباس مزدوجة داخل خلية، بالإضافة إلى علامات اقتباس مزدوجة للبداية والنهاية، يمكنك تخطي علامة الاقتباس المزدوجة باقتباس مزدوج آخر. على سبيل المثال: source1,"medium""ether",group1,100 - قيمة الخلية الثانية هي medium"ether.