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 サービスオブジェクトを作成する方法は次のとおりです。

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

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

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

Java

Analytics analytics = initializeAnalytics();

Analytics サービスオブジェクト analytics を使用して、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 からデータをリクエストするには:

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

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.Rows の List として返されます。各 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 サンプル

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

はじめに

準備

Java

概要

Multi-Channel Funnels Reporting API へのクエリ

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

Java

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

Java

API の結果の処理

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

列ヘッダーのデータ

Java

行データ

Java

Java

レポート情報

Java

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

Java

クエリ情報

Java

ページ設定情報

Java

すべての結果の合計

Java

実用的なサンプル

Java

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

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

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