توقّفت مواقع Universal Analytics العادية (UA) عن معالجة البيانات في 1 تموز (يوليو) 2023. ستتوقّف مواقع Universal Analytics 360 عن معالجة البيانات في 1 تموز (يوليو) 2024، وسيتم إيقاف بعض ميزات Universal Analytics 360 نهائيًا قبل ذلك، وذلك بسبب نقلنا البيانات إلى "إحصاءات Google 4". استخدِم Data API للوصول إلى ميزات إعداد التقارير لمواقع "إحصاءات Google 4".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعدّدة القنوات - دليل المطوِّر

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

مقدمة

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

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

قبل البدء

يستخدِم هذا الدليل مكتبة عملاء Java للوصول إلى واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعدّدة القنوات. توفِّر كل مكتبة عملاء عنصر خدمة واحدًا في "إحصاءات Google" لطلب البيانات من واجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعدّدة القنوات. وإذا لم تكن تستخدم مكتبة عملاء للوصول إلى واجهة برمجة التطبيقات، يُرجى قراءة واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعددة القنوات - الدليل المرجعي.

لإنشاء عنصر خدمة "إحصاءات Google":

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

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

على سبيل المثال، يؤدي الرمز التالي إلى إنشاء عنصر خدمة معتمد من "إحصاءات Google":

Java

Analytics analytics = initializeAnalytics();

استخدِم عنصر خدمة "إحصاءات Google" analytics لطلب واجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعدّدة القنوات.

نظرة عامة

لاستخدام واجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعددة القنوات لاسترداد البيانات، اكتب طلبًا من أجل:

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

إرسال طلب إلى واجهة برمجة التطبيقات لإعداد تقارير "المسارات المتعدّدة القنوات"

لطلب البيانات من واجهة برمجة التطبيقات لإعداد تقارير "المسارات المتعدّدة القنوات":

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

إنشاء طلب بحث في واجهة برمجة التطبيقات لإعداد تقارير "المسارات المتعدّدة القنوات"

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

analytics.data.mcf.get()    // analytics is the Analytics service object

المعلمة الأولى المُقدَّمة إلى الطريقة هي رقم تعريف جدول فريد في شكل ga:XXXX، حيث يكون XXXX هو رقم تعريف ملف شخصي (ملف شخصي) في "إحصاءات Google" يحتوي على البيانات المطلوبة. استخدِم كائن طلب البحث لتحديد مَعلمات طلب البحث (أي setDimensions). على سبيل المثال:

Java

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

للحصول على قائمة بجميع مَعلمات طلب البحث، اطّلِع على ملخّص مَعلمات طلب البحث. تتيح لك مَعلمات المقاييس والسمات تحديد البيانات المطلوب استردادها من "المسارات المتعدّدة القنوات". للحصول على قائمة بجميع السمات والمقاييس، يُرجى الاطّلاع على مرجِع المقاييس والسمات.

تقديم طلب الحصول على بيانات واجهة برمجة التطبيقات لإعداد تقارير "المسارات المتعدّدة القنوات"

بعد إنشاء كائن طلب البحث، استدعِ الطريقة execute في الكائن لطلب البيانات من خوادم "المسارات متعددة القنوات". مثال:

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

إذا كنت تفضّل الوصول إلى استجابة واجهة برمجة التطبيقات الأولية بدلاً من ذلك، عليك طلب الإجراء executeUnparsed() في كائن طلب البحث:

HttpResponse response = apiQuery.executeUnparsed();

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

التعامل مع نتائج واجهة برمجة التطبيقات

إذا نجح طلب بحث "واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعدّدة القنوات"، سيعرِض بيانات إعداد التقارير والمعلومات المتعلّقة بالبيانات.

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

يعرض الاستعلام بيانات التقارير المجدولة التالية:

بيانات رأس العمود
بيانات الصف

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

تتضمّن استجابة طلب البحث حقلاً لرأس العمود يحتوي على معلومات عنوان الجدول. الحقل هو قائمة (أو مصفوفة) من عناصر ColumnHeaders، يحتوي كل منها على اسم العمود ونوع العمود ونوع بيانات العمود. ترتيب الأعمدة هو أعمدة السمات، متبوعة بأعمدة المقاييس بنفس الترتيب المحدد في طلب البحث الأصلي. على سبيل المثال، تطبع الطريقة التالية عناوين الأعمدة:

Java

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

بيانات الصف

يتم عرض البيانات الرئيسية التي يتم عرضها من واجهة برمجة التطبيقات على شكل List ثنائي الأبعاد من McfData.Rows. وتمثّل كل McfData.Rows خلية واحدة وهي إما قيمة أساسية من النوع String أو قيمة مسار إحالة ناجحة من النوع McfData.Rows.ConversionPathValue. يتطابق ترتيب الخلايا في الصف مع الحقول في كائن عنوان العمود الموضّح أعلاه.

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

على سبيل المثال، تطبع الطريقة التالية رؤوس الجدول والصفوف:

Java

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

يوضِّح المثال التالي كيفية تحليل كائن نوع تسلسل "المسارات المتعدّدة القنوات" وتحويله إلى سلسلة:

Java

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

معلومات التقرير

بالإضافة إلى بيانات إعداد التقارير، يعرض طلب البحث معلومات (على سبيل المثال، رقم تعريف التقرير) حول البيانات. على سبيل المثال، تطبع الطريقة التالية معلومات التقرير:

Java

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

يوضّح لك الحقل containsSampledData ما إذا كان الردّ على طلب البحث قد تم أخذ عينة منه. بما أنّ تحليل العيّنات يمكن أن يؤثر في نتائج طلب البحث، لا تتطابق قيم العيّنات التي يعرضها الطلب (واجهة برمجة التطبيقات) مع القيم المعروضة على واجهة الويب. راجِع تحليل عيّنات البيانات للحصول على مزيد من التفاصيل.

عرض معلومات (الملف الشخصي)

يتضمّن ردّ طلب البحث رقم تعريف موقع الويب، واسم الملف الشخصي، ورقم تعريفه، ورقم تعريف حساب "إحصاءات Google" الذي يحتوي على الملف الشخصي. على سبيل المثال، تطبعها الطريقة التالية على الوحدة الطرفية (الإخراج القياسي):

Java

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

معلومات طلب البحث

تتضمّن استجابة طلب البحث عنصر Query يحتوي على قيم كل مَعلمات طلب البحث لطلب البيانات. على سبيل المثال، تطبع الطريقة التالية قيم هذه المعلمات:

Java

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics());       // List of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

وإذا كانت هناك طرق أخرى غير query.getMetrics() وquery.getDimensions() وquery.getSort()، يتم عرض String. على سبيل المثال، تعرض السمة query.getStartDate() تاريخ بدء التقرير (وهو String).

معلومات التقسيم على صفحات

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

Java

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

تعرض طريقة استدعاء mcfData.getTotalResults() إجمالي عدد الصفوف للاستعلام، والذي يمكن أن يكون أكبر من إجمالي عدد الصفوف التي يعرضها الاستعلام. وتعرض طريقة استدعاء الطريقة mcfData.getItemsPerPage() الحد الأقصى لعدد الصفوف التي يمكن أن تحتوي عليها استجابة الاستعلام.

تؤدي طريقة استدعاء الطريقة mcfData.getPreviousLink() إلى عرض الرابط إلى الصفحة السابقة وعرض mcfData.getNextLink() للرابط إلى الصفحة التالية.

إجماليات كل النتائج

للحصول على القيم الإجمالية للمقاييس المطلوبة في جميع النتائج، وليس فقط النتائج التي تم عرضها في ردّ طلب البحث، استدعِ طريقة getTotalsForAllResults() في استجابة طلب البحث، وهي كائن McfData. استخدِم القيم الإجمالية لحساب المتوسطات

Java

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

عيّنة عملية

Java

مكتبة برامج Java في Google API نموذج واجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعددة القنوات