Multi-Channel Funnels Reporting API - リファレンス ガイド

このドキュメントでは、Multi-Channel Funnels Reporting API のすべてのクエリとレスポンスについて説明します。

はじめに

Multi-Channel Funnels Reporting API を使用すると、Google アナリティクスのマルチチャネル レポート データをリクエストできます。すべてのレポートは、トラッキング コードからアナリティクスに送信されるデータから派生する統計情報で構成され、ディメンションや指標として整理されます。ディメンションと指標を独自に組み合わせることで、Reporting API を使用して、お客様の仕様に合わせてカスタマイズされたレポートを作成できます。

この API には、レポートデータをリクエストする report.get という 1 つのメソッドが含まれています。このメソッドを使用して、データを取得するビュー（プロファイル）に対応する表 ID を指定します。さらに、次の項目を指定します。

• ディメンションと指標の組み合わせ。
• 期間。
• 取得するデータを制御する一連のオプション パラメータ。

この API により、report.get メソッドは REST エンドポイント（https://www.googleapis.com/analytics/v3/data/mcf）で利用できます。次のセクションでは、サンプル リクエストを示し、それぞれのパラメータについて説明します。

リクエスト

この API には、データをリクエストするためのメソッドが 1 つ用意されています。

analytics.data.mcf.get()

この API は、REST エンドポイントとしてクエリすることもできます。

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/mcf
  ?ids=ga:12345
  &metrics=mcf:totalConversions,mcf:totalConversionValue
  &start-date=2011-10-01
  &end-date=2011-10-31

各 URL クエリ パラメータは、API クエリ パラメータを指定します。API クエリ パラメータは、URL エンコードされている必要があります。

Multi-Channel Funnels Reporting API に対するすべてのリクエストは、（できれば OAuth 2.0 を使用して）承認する必要があります。

クエリ パラメータの概要

次の表に、Multi-Channel Funnels Reporting API で使用できるすべてのクエリ パラメータを示します。パラメータ名をクリックすると、詳細な説明に移動します。

クエリ パラメータの詳細

ids

トップへ戻る

start-date

  &start-date=7daysAgo
  &end-date=yesterday

トップへ戻る

end-date

  &start-date=9daysAgo
  &end-date=today

トップへ戻る

dimensions

トップへ戻る

metrics

トップへ戻る

sort

sort=mcf:source,mcf:medium

sort=mcf:medium,mcf:source

トップへ戻る

filters

https://www.googleapis.com/analytics/v3/data/mcf
?ids=mcf:12134
&dimensions=mcf:source
&metrics=mcf:totalConversions
&filters=mcf:medium%3D%3Dreferral
&start-date=2011-10-01
&end-date=2011-10-31

トップへ戻る

samplingLevel

トップへ戻る

max-results

トップへ戻る

レスポンス

正常終了すると、このリクエストは、次のように定義される JSON 構造を持つレスポンスの本文を返します。

注: 「結果」という用語は、クエリに一致する行セット全体を表します。「レスポンス」という用語は、結果の現在のページで返される行のセットを表します。itemsPerPage の説明に示すように、結果の合計数が現在のレスポンスのページサイズを上回る場合は、結果とレスポンスが異なることがあります。

レスポンスの形式

{
  "kind": "analytics#mcfData",
  "id": string,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "sort": [
      string
    ],
    "filters": string,
    "samplingLevel": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "selfLink": string,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "containsSampledData": boolean,
  "sampleSize": string,
  "sampleSpace": string,
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
  "rows": [
    [
      McfData.Rows
    ]
  ],
}

トップへ戻る

レスポンスのフィールド

レスポンス本文の構造のプロパティは次のように定義されています。

{
  "primitiveValue": "2183"
}

{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

トップへ戻る

エラーコード

Multi-Channel Funnels Reporting API は、リクエストが正常に処理されると 200 HTTP ステータス コードを返します。クエリの処理中にエラーが発生した場合、API はエラーコードと説明を返します。アナリティクス API を使用する各アプリケーションでは、適切なエラー処理ロジックを実装する必要があります。エラーコードとエラー処理方法の詳細については、エラー　レスポンス　リファレンス　ガイドを参照してください。

トップへ戻る

試してみる

Multi-Channel Funnels Reporting API 対するクエリを試すことができます。

• ライブデータに対するリクエストを送信して JSON 形式のレスポンスを確認するには、Google APIs Explorer で analytics.data.mcf.get メソッドをお試しください。

トップへ戻る

サンプリング

Google アナリティクスでは、ディメンションと指標の特定の組み合わせがリアルタイムで計算されます。妥当な時間内のデータを返すために、Google アナリティクスではデータのサンプルのみを処理することができます。

samplingLevel パラメータを設定すると、リクエストに使用するサンプリング レベルを指定できます。

MCF Reporting API のレスポンスにサンプルデータが含まれる場合、containsSampledData レスポンス フィールドは true になります。さらに、sampleSize と sampleSpace という 2 つのプロパティにより、クエリのサンプリング レベルに関する情報が提供されます。これらの 2 つの値を使用すると、クエリに使用されたセッションの割合を計算できます。たとえば、sampleSize が 201,000、sampleSpace が 220,000 の場合、レポートはセッションの (201,000 / 220,000) * 100 = 91.36% を基に作成されています。

サンプリングの一般的な説明と、Google アナリティクスでの使用方法については、サンプリングを参照してください。

トップへ戻る

大量のデータ結果の処理

クエリから大量の結果が返されることが予想される場合、以下のガイドラインに従うことで、API クエリを最適化し、エラーを避け、割り当ての超過を最低限に抑えることができます。Google アナリティクスでは、1 つの API リクエストに最大 7 個のディメンションと 10 個の指標を許可することで、一定の成果を確保している点に注意してください。多数の指標とディメンションを指定したクエリは、他のクエリよりも処理に時間がかかる場合もありますが、リクエストする指標の数を制限すればクエリの性能が改善されるとは限りません。代わりに、次の手法を使用して、最適な結果を得ることができます。

クエリあたりのディメンション数の削減

API では、1 つのリクエストで最大 7 個のディメンションを指定できます。Google アナリティクスでは、多くの場合、このような複雑なクエリの結果をその場で計算します。結果の行数が多いと、この処理に特に時間がかかる場合があります。たとえば、都市別や時間別にキーワードをクエリすると、数百万行のデータと一致する可能性があります。クエリのディメンションの数を制限して Google アナリティクスで処理する必要がある行数を減らすことにより、クエリの性能を改善することができます。

期間によるクエリの分割

1 つの長い期間の日付付きの結果を改ページする代わりに、1 週間または 1 日ごとにクエリを分けることを検討してください。当然ながら、大きなデータセットの場合、1 日のデータに対するリクエストであっても max-results を超える結果が返されることがあります。この場合、改ページを避けることはできません。ただし、どのような場合でも、クエリに一致する行数が max-results を超える場合は、期間を分割することで、結果の取得にかかる合計時間を短縮できます。この方法により、単一スレッドのクエリと並列クエリの両方においてクエリの性能を改善することができます。

改ページ

結果を改ページすることで、大量の結果を管理しやすいセグメントに分割することができます。totalResults フィールドは、一致する行がいくつ存在するかを示し、itemsPerPage は、結果で返すことができる最大行数を指定します。itemsPerPage に対する totalResults の割合が高い場合、個々のクエリの処理には必要以上に時間がかかる可能性があります。表示の目的などのために、限られた数の行のみを必要としている場合は、max-results パラメータを使用してレスポンス サイズに対して明示的な制限を設定すると便利です。ただし、アプリケーションで大きな結果セット全体を処理する必要がある場合は、許可された最大行数をリクエストする方が効率的です。

gzip の使用

gzip 圧縮を有効にすると、各リクエストが消費する帯域幅を手早く低減できます。これには、結果を圧縮解除するために追加の CPU 時間が必要ですが、ネットワークのコストを大きく削減できます。gzip でエンコードされたレスポンスを受け取るには、Accept-Encoding ヘッダーを設定し、ユーザー エージェントを変更して文字列 gzip を含めます。gzip 圧縮を有効にする正しい HTTP ヘッダーの例を次に示します。

Accept-Encoding: gzip
User-Agent: my program (gzip)