Core Reporting API - リファレンス ガイド

データ リクエストで dimensions を使用する場合は、次の制約に注意してください。

• クエリで指定できるディメンションは最大 7 個です。
• ディメンションのみで構成されたクエリを送信することは できません。リクエストするディメンションと少なくとも 1 つの指標を 組み合わせる必要があります。
• 同じクエリ内で照会できるのは特定のディメンションのみです。使用できる ディメンションの組み合わせを、 ディメンションと指標のリファレンスにある有効な組み合わせ ツールで確認してください。

• どのリクエストでも少なくとも 1 つの指標を指定する必要があります。ディメンションのみで リクエストを構成することはできません。
• クエリには指標を 10 個まで指定できます。
• ディメンションを指定していない限り、複数のカテゴリのほとんどの指標を 組み合わせて使用することができます。
• 指標は他のディメンションや指標と組み合わせて使用できますが、その指標に有効な組み合わせが当てはまる場合に限ります。詳しくは、ディメンションと指標のリファレンスをご覧ください。

取得するデータの並べ替え順序と方向を示す指標とディメンションのリストです。

• 並べ替え順序は、リストされた指標とディメンションの左から右への順序によって指定されます。
• デフォルトの並べ替え方向directionは昇順ですが、リクエストしたフィールドで接頭辞としてマイナス記号（-）を使用すると、並べ替え方向を降順に変更できます。

クエリの結果を並べ替えることにより、データをさまざまな角度から見ることができます。たとえば、「最も多い国はどこか、どのブラウザが最も使用されているか」という疑問に答えるには、次のようにします。次のパラメータを使用してクエリを作成できます。ga:country で、次に ga:browser で、どちらも昇順で並べ替えます。

sort=ga:country,ga:browser

sort=ga:browser,ga:country

sort パラメータを使用する場合は、次の点に注意してください。

• dimensions パラメータまたは metrics パラメータに使用したディメンションまたは指標の値のみで並べ替えます。dimensions パラメータまたは metrics パラメータで指定されていないフィールドを基に並べ替えるようリクエストすると、エラーが返されます。
• en-US の言語 / 地域では、デフォルトで、文字列がアルファベットの昇順で並べ替えられます。
• 数値は、デフォルトで昇順で並べ替えられます。
• 日付は、デフォルトで昇順で並べ替えられます。

filters クエリ文字列パラメータは、リクエストから返されるデータを制限します。filters パラメータを使用するには、フィルタするディメンションまたは指標に続けてフィルタ式を指定します。たとえば、次のクエリは、ga:browser ディメンションが文字列 Firefox で始まるビュー（プロファイル）12134 の ga:pageviews と ga:browser をリクエストします。

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

フィルタを適用したクエリでは、結果に含める（または含めない）行が制限されます。結果の各行はフィルタに対してテストされます。フィルタが一致すると行が維持され、一致しないと行が削除されます。

• URL エンコード: Google API クライアント ライブラリによってフィルタ演算子が自動的にエンコードされます。
• ディメンションのフィルタ: フィルタはディメンションの集計前に行われるため、返される指標は該当するディメンションのみの合計を表します。上記の例では、ブラウザが Firefox のページビュー数のみが返されます。
• 指標のフィルタ: 指標のフィルタは、指標の集計後に行われます。
• 有効な組み合わせ: リクエスト内のすべてのディメンションまたは指標とフィルタが有効な組み合わせであれば、クエリに含まれないディメンションまたは指標をフィルタできます。たとえば、特定のブラウザでフィルタを適用した日付付きのページビュー リストをクエリすることができます。詳しくは、ディメンションと指標のリファレンスをご覧ください。

フィルタ構文

1 つのフィルタには次の形式を使用します。

ga:name operator expression

この構文の説明は次のとおりです。

• name - フィルタを適用するディメンションまたは指標の名前です。たとえば、ga:pageviews はページビュー数の指標でフィルタします。
• operator - 使用するフィルタの一致タイプを定義します。演算子はディメンションまたは指標に固有です。
• expression - 結果に含める値または結果から除外する値を記述します。式には正規表現構文を使用します。

フィルタ演算子

ディメンション用と指標用にそれぞれ 6 つのフィルタ演算子があります。演算子を URL クエリ文字列に含めるには URL エンコードする必要があります。

ヒント: URL エンコードが必要なフィルタを設計するには、Data Feed Query Explorer を使用します。Query Explorer は、文字列と空白を含む URL を自動的にエンコードします。

フィルタ式

フィルタ式にはいくつか重要な規則があります。

• URL 予約文字 - & などの文字は、通常の方法で URL エンコードする必要があります。
• 予約文字 - セミコロンとカンマを式に含める場合は、バックスラッシュでエスケープする必要があります。
  • セミコロン \;
  • カンマ \,
• 正規表現 - =~ 演算子と !~ 演算子を使用して、フィルタ式で正規表現を使用することもできます。これらの構文は Perl 正規表現と類似しており、次のルールが追加されています。
  • 最大文字数: 128 文字 - 正規表現が 128 文字を超えると、サーバーから 400 Bad Request ステータス コードが返されます。
  • 大文字と小文字の区別 - 正規表現一致では大文字と小文字は区別されません。

フィルタの組み合わせ

フィルタはブール論理演算の OR と AND を使用して組み合わせることができます。これにより、 フィルタ式の 128 文字の制限を事実上拡張できます。

OR

OR 演算子はカンマ（,）を使用して定義します。演算子は AND 演算子より優先され、同じ式内でディメンションと指標を組み合わせるためには使用できません。

AND

AND 演算子は、セミコロン（;）を使用して定義します。その前に OR 演算子が付き、同じ式でディメンションと指標を組み合わせることができます。

Core Reporting API でセグメントをリクエストする方法の詳細については、セグメントのデベロッパー ガイドをご覧ください。

セグメントの概念については、セグメント - 機能のリファレンスおよびヘルプセンターのセグメントをご覧ください。

セグメントで使用できるディメンションと指標
すべてのディメンションと指標をセグメントで使用できるわけではありません。セグメントで使用できるディメンションと指標を確認するには、 ディメンションと指標のリファレンスをご覧ください。

• DEFAULT - 速度と精度のバランスがとれたサンプルサイズでレスポンスが返されます。
• FASTER - サンプルサイズを小さくすることにより、高速なレスポンスが返されます。
• HIGHER_PRECISION - サンプルサイズを大きくすることにより、より正確なレスポンスが返されますが、レスポンス速度が低下する可能性があります。

• json - JSON オブジェクトを含むデフォルトの rows プロパティをレスポンスに出力します。
• dataTable - Data Table オブジェクトを含む dataTable プロパティをレスポンスで出力します。この Data Table オブジェクトは、Google グラフのビジュアリゼーションで直接使用できます。

部分レスポンスで返すフィールドを指定します。API レスポンスでフィールドのサブセットのみを使用する場合は、fields パラメータを使用して、含めるフィールドを指定できます。

fields リクエスト パラメータ値の形式はほぼ XPath の構文に基づいています。サポートされる構文の概要を次に示します。

• 複数のフィールドを選択するには、カンマ区切りのリストを使用します。
• フィールド a 内にネストされているフィールド b を選択するには a/b を使用し、フィールド b 内にネストされているフィールド c を選択するには a/b/c を使用します。
• 配列またはオブジェクトの特定のサブフィールド セットをリクエストするには、式をかっこ "( )" で囲んでサブセレクタを使用します。
  たとえば、fields=columnHeaders(name,dataType) は、columnHeaders 配列の name フィールドと dataType フィールドのみを返します。サブフィールドを 1 つ指定することもできます。ここで、fields=columnHeader(name) は fields=columnHeader/name と同等です。

true の場合、人が読める形式でレスポンスを返します。デフォルト値: false。

ユーザーの IP アドレスが不明な場合でも、サーバーサイド アプリケーションからユーザー 1 人あたりの割り当て量を適用できます。これはたとえば、アプリケーションがユーザーに代わって App Engine で cron ジョブを実行する場合に使用します。ユーザーを一意に識別する任意の文字列を選択できますが、上限は 40 文字です。

両方が指定されている場合、これは userIp をオーバーライドします。