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

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

مقدمة

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

المصدران في واجهة برمجة تطبيقات الإدارة اللذان يتيحان استيراد البيانات هما:

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

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

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

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

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

يمكن تحميل معاملات التجارة الإلكترونية التي تم ردّ أموالها كليًا أو جزئيًا إلى "إحصاءات 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"، راجع استيراد بيانات التكلفة باستخدام 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."
  ]
}

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

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

  • 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.