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-Channel Funnels Reporting API にアクセスします。各クライアント ライブラリは、Multi-Channel Funnels Reporting API を呼び出してデータを取得するための 1 つの Analytics サービス オブジェクトを提供します。クライアント ライブラリを使用せずに API にアクセスする場合は、Multi-Channel Funnels Reporting API - リファレンス ガイドをご覧ください。

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

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

上記の手順を完了していない場合は、まず Google アナリティクス API についてのチュートリアルをご覧ください。このチュートリアルでは、Google アナリティクス API アプリケーションを作成する基本的な手順を詳しく説明しています。チュートリアルを完了したら、このガイドを引き続きご覧ください。

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

Java

Analytics analytics = initializeAnalytics();

Analytics サービス オブジェクト analytics を使用して、Multi-Channel Funnels 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 から返される主なデータは、2 次元の McfData.RowsList として 返されます。各 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();
}

レポート情報

クエリでは、レポートデータに加え、そのデータに関する情報(レポート 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-Channel Funnels 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 サンプル