Multi-ChannelFunnel 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 にアクセスします。各クライアント ライブラリには、マルチチャネル レポート API を呼び出してデータを取得するための単一のアナリティクス サービス オブジェクトが用意されています。クライアント ライブラリを使用して API にアクセスできない場合は、Multi-ChannelFunnel Reporting API - リファレンス ガイドをご覧ください。

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

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

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

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

Java

Analytics analytics = initializeAnalytics();

アナリティクスのサービス オブジェクト analytics を使用して、マルチチャネル レポート 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() は次のページへのリンクを返します。

すべての結果の合計

クエリ レスポンスで返された結果だけでなく、すべての結果でリクエストされた指標の合計値を取得するには、クエリ レスポンスで 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

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