Multi-Channel Funnels Reporting API - デベロッパー ガイド

このドキュメントでは、Multi-Channel Funnels Reporting API を使ってマルチチャネル データを利用する方法について説明します。

はじめに

マルチチャネルの標準レポートとカスタム レポートの表形式のデータには、Multi-Channel Funnels Reporting API を介してアクセスできます。データにアクセスするにはクエリを作成します。クエリでビュー（旧プロファイル）、開始日と終了日、さらに、表内の列ヘッダーを構成するディメンションと指標を指定します。このクエリを Multi-Channel Funnels Reporting API に送信すると、すべてのデータが表形式で返されます。

この API を初めてご利用になる場合は、Multi-Channel Funnels Reporting API の概要をご覧ください。Multi-Channel Funnels Reporting API の目的とその API が提供するデータについて説明しています。

始める前に

このガイドでは、Java クライアント ライブラリを使用して Multi-ChannelFunnel Reporting API にアクセスします。各クライアント ライブラリは、Multi-ChannelFunnel Reporting API を呼び出してデータを取得するための単一のアナリティクス サービス オブジェクトを提供します。クライアント ライブラリを使用せずに API にアクセスする場合は、 Multi-ChannelFunnel Reporting API - リファレンス ガイドをご覧ください。

Analytics サービス オブジェクトを作成する方法は次のとおりです。

  1. Google API コンソールで アプリケーションを登録します。
  2. Google アナリティクス データへのアクセスを承認します。
  3. Analytics サービス オブジェクトを作成するコードを記述します。

上記の手順を完了していない場合は、いったん Analytics API についてのチュートリアルをご覧ください。このチュートリアルでは、Google Analytics API アプリケーションを作成する最初の手順について説明しています。チュートリアルを完了したら、引き続き次のガイドをご覧ください。

たとえば、以下のコードは承認済みの Analytics サービス オブジェクトを作成します。

Java

Analytics analytics = initializeAnalytics();

Analytics サービス オブジェクト analytics を使用して、Multi-ChannelFunnel Reporting API を呼び出します。

概要

Multi-Channel Funnels Reporting API を使用してデータを取得するには、次の操作を行うアプリケーションを記述します。

  1. Multi-Channel Funnels Reporting API へのクエリ
  2. API から返された結果の処理

Multi-Channel Funnels Reporting API へのクエリ

Multi-Channel Funnels Reporting API からデータをリクエストするには:

  1. Multi-Channel Funnels Reporting API クエリ オブジェクトを作成します。
  2. クエリ オブジェクトを使用して、マルチチャネル サーバーからデータをリクエストします。

Multi-Channel Funnels Reporting API へのクエリの作成

Multi-Channel Funnels Reporting API クエリ オブジェクトを作成するには、次のメソッドを呼び出します。

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

このメソッドに渡される最初のパラメータは、ga:XXXX という形式の一意のテーブル ID です。XXXX は、リクエストされたデータを含むアナリティクス ビュー（プロファイル）の ID です。クエリオブジェクトを使用して クエリパラメータ（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);

クエリ パラメータの一覧については、クエリ パラメータの概要をご覧ください。マルチチャネルから取得するデータは、指標パラメータとディメンション パラメータで指定します。ディメンションと指標の一覧については、 ディメンションと指標のリファレンスをご覧ください。

Multi-Channel Funnels Reporting API のデータ リクエストの実行

クエリ オブジェクトを作成したら、そのオブジェクトで 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();
}

未加工の API レスポンスにアクセスする場合は、クエリ オブジェクトの executeUnparsed() メソッドを呼び出します。

HttpResponse response = apiQuery.executeUnparsed();

クエリが正しく実行されると、リクエストしたデータが返されます。エラーが発生すると、execute メソッドはエラーのステータス コードとエラーの説明を含む例外をスローします。アプリは例外をキャッチして処理する必要があります。

API の結果の処理

Multi-Channel Funnels Reporting API へのクエリが正しく実行されると、レポートデータとそのデータに関する情報が返されます。

マルチチャネル レポートデータ

クエリによって次の表形式のレポートデータが返されます。

  • 列ヘッダーのデータ
  • 行データ

列ヘッダーのデータ

クエリ レスポンスには、表のヘッダー情報を含む列ヘッダー フィールドがあります。フィールドは 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());
  }
}

行データ

API から返される主なデータは、McfData.Rows の 2 次元 List として返されます。各 McfData.Rows は 1 つのセルを表します。各セルには、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();
}

レポート情報

クエリでは、レポートデータに加えて、データに関する情報（レポート ID など）が返されます。レポート情報を出力するメソッドの例を次に示します。

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 フィールドは、クエリ レスポンスがサンプリングされたかどうかを示します。サンプリングはクエリ結果に影響する可能性があるため、クエリ（API）から返されるサンプリング値は、管理画面に表示される値と一致しません。詳しくは、サンプリングをご覧ください。

ビュー（旧プロファイル）情報

クエリ レスポンスには、ウェブ プロパティ ID、ビュー（旧プロファイル）の名前と ID、ビュー（旧プロファイル）を含むアナリティクス アカウントの ID が含まれます。これらの情報を端末（標準出力）に出力するメソッドの例を次に示します。

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）を返します。

ページ設定情報

Multi-Channel Funnels Reporting API リクエストに合致するマルチチャネル データの行数は膨大な件数に上る可能性があります。Multi-ChannelFunnel Reporting API は、ある時点でデータのサブセット（データの単一ページ）のみを返します。データのすべてのページを取得するには、ページ設定フィールドを使用します。次のメソッドは、ページ設定情報を出力します。

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() は次のページへのリンクを返します。

すべての結果の合計

クエリ レスポンスで返された結果だけでなく、すべての結果について、リクエストされた指標の合計値を取得するには、クエリ レスポンス（McfData オブジェクト）に対して getTotalsForAllResults() メソッドを呼び出します。合計値は平均値の計算に利用できます。

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

Google API Java クライアント ライブラリ Multi-Channel Funnels Reporting API サンプル