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

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

المقدمة

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

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

قبل البدء

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

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

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

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

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

Java

Analytics analytics = initializeAnalytics();

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

نظرة عامة

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

  1. واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعددة القنوات.
  2. يمكنك استخدام النتائج التي تعرضها واجهة برمجة التطبيقات.

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

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

  1. إنشاء كائن طلب بحث لواجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعددة القنوات.
  2. يمكنك استخدام كائن طلب البحث لطلب البيانات من خوادم المسارات المتعددة القنوات.

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

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

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 نموذج واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعددة القنوات