API گزارش قیف چند کانالی - راهنمای برنامه‌نویس

این سند نحوه استفاده از API گزارش قیف چند کانالی را برای دسترسی به داده های قیف چند کانالی توضیح می دهد.

معرفی

API گزارش قیف های چند کاناله دسترسی به داده های جدولی در گزارش های استاندارد و سفارشی قیف های چند کانالی را فراهم می کند. برای دسترسی به داده ها، یک پرس و جو ایجاد می کنید که مشخص می کند: نمای (نمایه)، تاریخ شروع و پایان، و ابعاد و معیارهایی که سرصفحه های ستون را در جدول تشکیل می دهند. این پرس و جو به API گزارش قیف های چند کاناله ارسال می شود و API گزارش قیف های چند کاناله تمام داده ها را به صورت جدول برمی گرداند.

اگر با API تازه کار هستید، برای آشنایی با هدف API گزارش قیف چند کانالی و داده‌هایی که ارائه می‌کند، مروری بر API گزارش قیف‌های چند کانالی را بخوانید.

قبل از اینکه شروع کنی

این راهنما از کتابخانه سرویس گیرنده جاوا برای دسترسی به API گزارش قیف چند کانالی استفاده می کند. هر کتابخانه سرویس گیرنده یک شیء سرویس Analytics را برای فراخوانی API گزارش قیف چند کانالی برای دریافت داده ها فراهم می کند. اگر از کتابخانه سرویس گیرنده برای دسترسی به API استفاده نمی کنید، API گزارش قیف چند کانالی - راهنمای مرجع را بخوانید.

برای ایجاد شیء سرویس Analytics:

  1. برنامه خود را در Google API Console ثبت کنید.
  2. اجازه دسترسی به داده های Google Analytics را بدهید.
  3. برای ایجاد شی سرویس Analytics کد بنویسید.

اگر این مراحل را کامل نکرده‌اید، توقف کرده و آموزش Hello Analytics API را بخوانید، که شما را در مراحل اولیه ساخت یک برنامه Google Analytics API راهنمایی می‌کند. پس از اتمام آموزش، به خواندن راهنمای زیر ادامه دهید.

به عنوان مثال، کد زیر یک شیء مجاز سرویس Analytics را ایجاد می کند :

جاوا

Analytics analytics = initializeAnalytics();

از analytics شیء سرویس Analytics برای فراخوانی API گزارش قیف چند کانالی استفاده کنید.

بررسی اجمالی

برای استفاده از API گزارش قیف چند کانالی برای بازیابی داده ها، یک برنامه کاربردی بنویسید:

  1. API گزارش قیف چند کانالی را پرس و جو کنید.
  2. با نتایج برگردانده شده از API کار کنید.

API گزارش قیف چند کانالی را پرس و جو کنید

برای درخواست داده از API گزارش قیف چند کانالی:

  1. یک شی پرس و جوی API گزارش قیف چند کانالی بسازید.
  2. از شی پرس و جو برای درخواست داده از سرورهای قیف چند کانالی استفاده کنید.

یک جستار API گزارش قیف چند کانالی بسازید

برای ساختن یک شی پرس و جوی API گزارش قیف چند کانالی، این متد را فراخوانی کنید:

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

اولین پارامتر ارائه شده به روش یک شناسه جدول منحصر به فرد به شکل ga:XXXX است که در آن XXXX شناسه نمای آنالیتیکس (نمایه) حاوی داده های درخواستی است. از شی پرس و جو برای تعیین پارامترهای پرس و جو استفاده کنید (یعنی setDimensions ). مثلا:

جاوا

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);

برای فهرستی از تمام پارامترهای پرس و جو، به خلاصه پارامترهای پرس و جو مراجعه کنید. پارامترهای معیارها و ابعاد به شما امکان می‌دهند مشخص کنید چه داده‌هایی از قیف‌های چند کانالی بازیابی شود. برای فهرستی از همه ابعاد و معیارها، به مرجع ابعاد و معیارها مراجعه کنید.

ایجاد یک درخواست داده API گزارش قیف چند کانالی

پس از ایجاد آبجکت query، متد execute را برای درخواست داده از سرورهای Multi-Channel Funnels روی شی فراخوانی کنید. مثلا:

جاوا

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();
}

اگر ترجیح می دهید به جای آن به پاسخ API خام دسترسی داشته باشید، متد executeUnparsed() را در شی query فراخوانی کنید:

HttpResponse response = apiQuery.executeUnparsed();

در صورت موفقیت آمیز بودن پرس و جو، داده های درخواستی را برمی گرداند. اگر خطایی رخ دهد، متد execute یک استثنا شامل یک کد وضعیت برای خطا و شرح خطا می‌زند. برنامه باید استثنا را بگیرد و رسیدگی کند.

با نتایج API کار کنید

اگر درخواست API گزارش قیف چند کانالی موفقیت آمیز باشد، داده های گزارش و اطلاعات مربوط به داده ها را برمی گرداند.

داده های گزارش قیف های چند کانالی

پرس و جو داده های گزارش جدولی زیر را برمی گرداند:

  • داده های هدر ستون
  • داده ردیف

داده های هدر ستون

پاسخ پرس و جو دارای یک فیلد سرصفحه ستون است که حاوی اطلاعات سرصفحه جدول است. این فیلد یک لیست (یا آرایه) از اشیاء ColumnHeaders است که هر کدام شامل نام ستون، نوع ستون و نوع داده ستون است. ترتیب ستون ها ابعاد ستون هایی است که به دنبال آن ستون های متریک به همان ترتیبی که در جستار اصلی مشخص شده است. به عنوان مثال، روش زیر هدر ستون ها را چاپ می کند:

جاوا

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());
  }
}

داده ردیف

داده های اصلی بازگردانده شده از API به عنوان یک List دو بعدی از McfData.Rows برگردانده می شود. هر McfData.Rows یک سلول واحد را نشان می دهد که یا یک مقدار اولیه از نوع String است یا یک مقدار مسیر تبدیل از نوع McfData.Rows.ConversionPathValue . ترتیب سلول ها در یک ردیف مانند فیلدهای موجود در شی هدر ستون است که در بالا توضیح داده شد.

از آنجایی که داده‌ها در هر سلول یا به‌عنوان یک رشته یا به‌عنوان یک نوع توالی قیف چند کانالی بازگردانده می‌شوند، فیلد DataType در هر شی هدر ستون به‌ویژه برای تجزیه مقادیر به انواع مناسب مفید است. راهنمای مرجع برای همه انواع داده های ممکن را ببینید.

به عنوان مثال، روش زیر سرصفحه ها و ردیف های جدول را چاپ می کند:

جاوا

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");
  }
}

مثال زیر نشان می دهد که چگونه یک شی از نوع دنباله قیف چند کانالی را تجزیه و آن را به رشته تبدیل کنید:

جاوا

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();
}

گزارش اطلاعات

علاوه بر داده های گزارش، پرس و جو اطلاعات (مثلاً شناسه گزارش) را در مورد داده ها برمی گرداند. به عنوان مثال، روش زیر اطلاعات گزارش را چاپ می کند:

جاوا

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 به شما می گوید که آیا پاسخ پرس و جو نمونه برداری شده است یا خیر. از آنجایی که نمونه برداری می تواند بر نتایج پرس و جو تأثیر بگذارد، مقادیر نمونه برگردانده شده از پرس و جو (API) با مقادیر نشان داده شده در رابط وب مطابقت ندارند. برای جزئیات بیشتر به نمونه گیری مراجعه کنید.

مشاهده اطلاعات (نمایه).

پاسخ پرس و جو شامل شناسه ویژگی وب، نام و شناسه نمای (نمایه)، و شناسه حساب Analytics حاوی نما (نمایه) است. به عنوان مثال، روش زیر آنها را در ترمینال چاپ می کند (خروجی استاندارد):

جاوا

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 است که حاوی مقادیر تمام پارامترهای درخواست داده است. به عنوان مثال، روش زیر مقادیر چنین پارامترهایی را چاپ می کند:

جاوا

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 ) گزارش را برمی گرداند.

اطلاعات صفحه بندی

هر درخواست API گزارش قیف چند کانالی ممکن است با صدها هزار ردیف داده قیف چند کانالی مطابقت داشته باشد. API گزارش قیف چند کانالی تنها یک زیرمجموعه را که به عنوان یک صفحه از داده ها نامیده می شود، در یک زمان معین برمی گرداند. برای بازیابی تمام صفحات داده، از قسمت صفحه بندی استفاده کنید. روش زیر اطلاعات صفحه بندی را چاپ می کند:

جاوا

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() حداکثر تعداد ردیف‌هایی را که پاسخ query می‌تواند داشته باشد را برمی‌گرداند.

متد فراخوانی mcfData.getPreviousLink() پیوند را به صفحه قبلی و mcfData.getNextLink() پیوند را به صفحه بعد برمی گرداند.

مجموع همه نتایج

برای بدست آوردن مجموع مقادیر معیارهای درخواستی بر روی همه نتایج، نه فقط نتایجی که در پاسخ پرس و جو برگردانده می شوند، متد getTotalsForAllResults() را در پاسخ query، یک شی McfData ، فراخوانی کنید. از مجموع مقادیر برای محاسبه میانگین ها استفاده کنید.

جاوا

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());
  }
}

نمونه کار

جاوا

نمونه API گزارش قیف چند کانالی کتابخانه سرویس گیرنده جاوا Google API