このドキュメントでは、Core Reporting API のセグメントの構文と、セグメントの使用 にあたっての考慮事項について説明します。
はじめに
Core Reporting API のセグメント機能を使用すると、次の 2 つの方法で Core Reporting API でセグメントをリクエストできます。
- ID によるセグメント: 組み込みセグメントまたはカスタム セグメントの数値 ID を使用してクエリを実行します。
- 動的セグメント: リクエスト時にセグメントを動的に指定します。
ID によるセグメント
組み込みセグメントまたはカスタム セグメントの ID を使用して、Core Reporting API でセグメントをリクエストできます。ユーザーが使用できるすべてのセグメントは、Google アナリティクス Management API の Segments コレクション
の list メソッドを使用して取得できます。各セグメントの ID は、Segment リソースの id プロパティにあります。
API リクエストでのセグメント ID の使用の詳細については、Core Reporting API リファレンスを参照してください。
動的セグメント
API リクエストを行うときにセグメントを動的に作成して使用することもできます。動的セグメントを作成する際に、次のことを考慮してください。
動的セグメントを作成する際の各考慮事項の概要を以下で説明します。動的セグメントの完全な構文については、動的セグメントの構文リファレンスをご覧ください。
セグメントで使用できるディメンションと指標
すべてのディメンションと指標をセグメントで使用できるわけではありません。セグメントで使用できるディメンションおよび指標を確認するには、ディメンションと指標のリファレンスをご覧ください。
1. ユーザーとセッションの選択
ユーザーかセッション(またはその両方)を選択するかどうかを指定します。
- ユーザーを選択するには、
users::
を使用します。 - セッションを選択するには、
sessions::
を使用します。 users::
とsessions::
の両方の条件を指定する場合:- まず、ユーザー条件が適用され、一致するユーザーのセッションが出力されます。
- セッション条件は、#1 からのセッションのみに適用されます。
次に例を示します。
- 少なくとも 1 つのセッションで Chrome ブラウザを使用したユーザーを選択する。
users::condition::ga:browser==Chrome
- Chrome ブラウザが使用されたセッションを選択する。
sessions::condition::ga:browser==Chrome
- 少なくとも 1 つのセッションで Chrome ブラウザを使用したロンドンのユーザーを選択する。
users::condition::ga:browser==Chrome;sessions::condition::ga:city==London
ユーザーとセッションの選択の詳細については、構文リファレンスの conditionScope セクションをご覧ください。
2. 条件とシーケンスの使用
ユーザーとセッションのどちらをセグメント分割するかを決定したら、1 つ以上の条件またはシーケンスを指定します。
条件
条件を指定するには、condition::
プレフィックスを使用します。次に例を示します。
- Chrome ブラウザを使用してロンドンからアクセスしたユーザーを選択する。
users::condition::ga:city==London;ga:browser==Chrome
シーケンス
シーケンス条件は、1 つ以上のステップで構成されます。この場合、各ステップは、1 つ以上のディメンション条件または指標条件で定義されます。
シーケンスに基づく条件を指定するには、sequence::
プレフィックスと、FOLLOWED BY(;–>>
)演算子または IMMEDIATELY FOLLOWED BY(;–>
)演算子を使用します。次に例を示します。
- PC を使用した後にモバイル端末を使用したユーザーを選択します。ここではユーザーがセグメント化されるため、これにより、ユーザーのすべてのセッションが検索され、ユーザーが 1 つのセッションで PC を使用した後、続くセッションのいずれかでモバイル端末を使用したかどうかが確認されます。
-
users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
-
- ステップごとに複数の条件を使用することも可能です。
-
users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
-
- AND(;)演算子を使用して、1 つのセグメントで条件とシーケンスを組み合わせることもできます。
-
users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
-
単純な条件およびシーケンスに基づく条件の詳細については、構文リファレンスの conditionType セクションをご覧ください。追加の例については、セグメント - 機能のリファレンスの条件セクションとシーケンス セクションをご覧ください。
3. 指標スコープの使用
指標のスコープは、その指標が定義されるレベル(ヒット、セッション、ユーザー)を定義します。たとえば、ga:pageviews
と ga:transactions
は、ヒット内で発生するため、ヒットレベルの指標です。これに対し、ga:sessionDuration
と ga:bounces
は、セッションごとに 1 つの値を持つため、セッション レベルの指標です。概念的には、ユーザーは最上位レベルのスコープであり、ヒットは最下位レベルのスコープです。
指標値は、そのプライマリ スコープより上位のスコープで報告することもできます。たとえば、ga:pageviews
と ga:transactions
は、セッションまたはユーザーで発生するヒットごとに追加することで、セッション レベルとユーザーレベルで報告できます。
指標条件ごとにスコープを指定すると、その条件が適用される
レベルが決まります。指標のスコープを指定するには、
perUser::
、perSession::
、または perHit::
プレフィックスを使用します。
次に例を示します。
- ウェブサイトで 1,000 円以上使っているユーザー(つまり、ライフタイムバリューが
1,000 円以上のユーザー)を選択します。
users::condition::perUser::ga:transactionRevenue>=10
- 1 つのセッションで 1,000 円以上使ったユーザーを選択します。
users::condition::perSession::ga:transactionRevenue>=10
スコープの制限
Core Reporting API では、指定されたクエリが有効であることを確認するために、指標スコープの検証が実行されます。スコープの検証ルールを次に示します。
- 指定された指標スコープは、常に、(
users::
プレフィックスまたはsessions::
プレフィックスで示される)親の条件スコープ以下である必要があります。 - 指定された指標スコープは、データモデルで定義されたプライマリ スコープ以上である必要があります。指標とそのプライマリ スコープの一覧については、指標: プライマリ スコープ リファレンスをご覧ください。
有効な指標スコープの例を次に示します。
- 条件スコープと指標スコープが等しい場合(ユーザーレベル)。
users::condition::perUser::ga:transactionRevenue>10
- 条件スコープが指標スコープより大きい場合(ユーザーはセッションより大きい)。
users::condition::perSession::ga:transactionRevenue>10
ga:totalEvents
は、ヒットレベルの指標のため、条件で その指標に使用できるスコープは、perHit::
、perSession::
、perUser::
となります(これらはすべて ヒットレベルのスコープ以上であるため)。users::condition::perHit::ga:totalEvents>5
users::condition::perSession::ga:totalEvents>5
無効な指標スコープの例を次に示します。
- 次のセグメントは、親の条件スコープが指標スコープより小さい(セッションはユーザーより小さい)ため、無効です。
sessions::condition::perUser::ga:transactionRevenue>10
- SESSION レベルの指標に対してヒットレベルのスコープを使用している場合(ヒットレベルはセッション レベルより小さい)。
users::condition::perHit::ga:sessionDuration>60
デフォルトのスコープ
指標条件のスコープが明示的に指定されていない場合、デフォルトで
条件スコープが適用されます。たとえば、次のセグメントでは、そのすべての指標条件に
ユーザーレベルのスコープを使用します。
users::condition::ga:transactionRevenue>=10;ga:sessionDuration>60
動的セグメントの構文リファレンス
基本的な構文
セグメントを定義するには、segment=<segmentCondition>+
形式の構文を使用します。つまり、セグメントは、1 つ以上の segmentCondition
ステートメントから構成されます。
<segmentCondition>
は <conditionScope><conditionType><dimensionOrMetricConditions>
として定義されます。
各要素の説明は次のとおりです。conditionScope
は、条件の最上位レベルのスコープを指定します。
conditionType
は、条件の種類を指定します。
dimensionOrMetricConditions
は、ディメンションや指標の条件、またはシーケンス ステップを指定します。
conditionScope
条件の最上位レベルのスコープを指定します。使用可能な値は次のとおりです。
users::
ユーザーを選択する場合。sessions::
セッションを選択する場合。
conditionScope
に関する制限と考慮事項:
- 1 つのセグメントに複数の「ユーザー」条件と「セッション」条件を指定する場合は、AND 演算子を使って条件を組み合わせる必要があります。
- ユーザーとセッションの両方を選択する条件も AND 演算子で組み合わせる必要があります。ユーザーとセッション両方の条件が指定されている場合、最初にすべてのユーザー条件が適用されて一致するユーザーが検出され、次に一致するユーザーに属するセッションに対してすべてのセッション条件が適用されます。
- ユーザーレベルの条件を使用する場合、期間が 90 日を超えないようにしてください。
- 条件スコープにより、その下のすべての指標条件のデフォルトのスコープレベルが決まります(スコープレベルの詳細については、指標: プライマリ スコープ リファレンスを参照してください)。
conditionType
条件の種類を指定します。使用可能な値は次のとおりです。
condition::
単純な(つまり、シーケンスに基づかない)条件を指定する場合。sequence::
シーケンスに基づく条件を指定する場合。
conditionType
に関する制限と考慮事項:
- 複数の「単純条件」と「シーケンス」を指定する場合は、必ず AND 演算子を 使って条件を組み合わせます。
- シーケンスに基づく条件では、セグメントにつき最大 10 個のステップが 許可されます。
単純条件
単純条件は、組み合わせることができる 1 つ以上のディメンション条件や指標条件 から構成されます。
単純条件の有効な条件演算子は次のとおりです。
- 条件を組み合わせる際に使用する AND 演算子または OR 演算子
- ディメンションや指標の演算子。
単純条件の構文は次のとおりです。
condition::<dimensionOrMetricConditions>
単純条件の例:
users::condition::ga:transactionRevenue>10;ga:sessionDuration>60
- 最上位の否定演算子を指定すると、複数のディメンション条件や
指標条件を中に含む可能性がある特定の単純条件の補集合を
検出できます。例:
users::condition::!ga:transactionRevenue>10;ga:sessionDuration>60
除外条件
除外条件を使用すると、定義した条件に一致しないセグメントを作成できます。
この構文では NOT 演算子(「!
」 )を使用して条件を否定し、条件に一致するセッションを除外します。
離脱ページがルートページ パスに完全に一致するセッションを除外するには、次のようにします。
sessions::condition::!ga:exitPagePath==/
複数の条件
単一の users::
プレフィックスの下でユーザーレベルのすべての条件をグループ化することも、条件ごとに別個の users::
プレフィックスを使用することもできます。セッション レベルの条件にも同じことが当てはまります。
たとえば、次のセグメントは等価です。どちらの場合も、ユーザーを選択するためには condition1 と condition2 の AND
演算が行われます。users::<condition1>;<condition2>
users::<condition1>users::<condition2>
シーケンス条件
シーケンス条件は 1 つ以上のステップで構成されます。この場合、各ステップは、1 つ以上のディメンション条件や指標条件によって定義されています。特殊なシーケンス演算子を使用して、複数のステップを組み合わせることができます。
シーケンス条件に有効なシーケンス演算子は次のとおりです。
–>>
演算子は、前のステップが次のステップより前に発生することを示します。–>
演算子は、前のステップが次のステップの直前に発生することを示します。
シーケンス条件の構文は次のとおりです。
sequence:: NOT? FIRST_HIT_MATCHES_FIRST_STEP?
各要素の説明は次のとおりです。
NOT
は !
で表します。FIRST_HIT_MATCHES_FIRST_STEP
は ^
で表します。PRECEDES
は ;–>>
で表します。IMMEDIATELY_PRECEDES
は ;–>
で表します。step
は <dimensionOrMetricConditions>
で表します。
シーケンス条件の例:
-
users::sequence::ga:deviceCategory==desktop;->ga:deviceCategory==tablet
- 最上位の否定演算子を指定すると、複数のディメンション条件や指標条件を中に含む可能性がある特定のシーケンスの補集合を検出できます。例:
users::sequence::!ga:deviceCategory==desktop;->ga:deviceCategory==tablet
^
演算子を使用すると、最初のステップが特定の期間内の最初のセッションの最初のヒットに一致することを指定できます。例:users::sequence::^ga:deviceCategory==desktop;->ga:deviceCategory==tablet
セッション条件の日付
セグメントでは、dateOfSession
構文を使用する分析手法がサポートされます。BETWEEN <>
演算子と組み合わせることにより、特定の期間内にセッションを開始したユーザーのグループにセグメントを制限できます。dateOfSession
の最長期間は 31 日です。その使用方法の詳細については、以下のセッションの日付の例をご覧ください。
ディメンション条件と指標条件
条件の組み合わせ
AND(;
)演算子と OR(,
)演算子を使用して、1 つ以上のディメンション条件を組み合わせることができます(OR 演算子の方が優先されます)。
構文は、フィルタを組み合わせたときに使用した構文と同じです。詳細については、Core Reporting API リファレンスのフィルタの組み合わせをご覧ください。
演算子
次の表に、セグメントで使用できるすべての演算子と、これらがディメンションや指標でサポートされるかどうかを示します。
演算子 | 説明 | ディメンション条件でサポートされるか | 指標条件でサポートされるか |
---|---|---|---|
== |
等しいまたは完全一致 | はい 例: ga:city==London |
はい 例: ga:adCost==10 |
!= |
等しくない、または完全一致でない | はい 例: ga:city!=London |
はい 例: ga:adCost!=10 |
< |
小さい | はい(数値のみ) 例: ga:hour<12 |
はい 例: ga:adCost<10 |
<= |
以下 | はい(数値のみ) 例: ga:hour<=12 |
はい 例: ga:adCost<=10 |
> |
大きい | はい(数値のみ) 例: ga:hour>12 |
はい 例: ga:adCost>10 |
>= |
以上 | はい(数値のみ) 例: ga:hour>=12 |
はい 例: ga:adCost>=10 |
<> |
範囲(指定された範囲内の値)1 | はい(数値のみ) 例: ga:hour<>1_12 |
はい 例: ga:adCost<>10_20 |
[] |
リスト内(リストされた値のいずれか)2 | はい 例: ga:browser[]Chrome|Firefox|Opera |
いいえ |
=@ |
文字列の一部に一致 | はい 例: ga:keyword=@shoes |
いいえ |
!@ |
文字列の一部に一致しない | はい 例: ga:keyword!@shoes |
いいえ |
=~ |
正規表現の一致を含む | はい 例: ga:keyword=~shoes |
いいえ |
!~ |
正規表現の一致を含まない | はい 例: ga:keyword!~shoes |
いいえ |
1BETWEEN 演算子 <>
特定の範囲内の値をクエリすることができます。その範囲の値は包括的です。数値型の指標とディメンション両方に使用できます(たとえば、ga:hour
)。範囲の最小値と最大値はアンダースコアで区切る必要があります。
構文:{dimensionOrMetricName}<>{minValue}_{maxValue}
例:
12~23 時の間に発生したセッションを選択します。
sessions::condition::ga:hour<>12_23
2LIST 演算子 []
指定されたリスト内の値をクエリすることができます。これは、ディメンションに対してのみ使用できます。値のリストは、「|」文字で区切ります。値に含まれる「|」はエスケープする必要があります。
構文:{dimensionName}[]{value1}|{value2}|...
制限:
1 つのリスト内ディメンション条件に指定できる値の数は最大 10 個です(たとえば、ga:city[]city1|city2|...|city10
)。
例:
Chrome、Firefox、Opera のいずれかのブラウザからのセッションを選択します。sessions::condition::ga:browser[]Chrome|Firefox|Opera
特殊文字のエスケープ
値式の中に出現する特殊文字「,
」と「;
」はエスケープする必要があります。例:
ga:keyword==nike\,shoes
ディメンション条件と指標条件の詳細については、Core Reporting API リファレンス を参照してください。
制限
ディメンション条件と指標条件に関連する制限は次のとおりです。
- 1 つのセグメントに指定できるディメンション条件または指標条件の数は最大 10 個です。
- ディメンション条件の式の最大文字数は 1,024 文字です。
従来の動的セグメントの移行
dynamic::
プレフィックスを使用する従来の動的セグメントは、現在の構文のディメンション条件および指標条件が指定されたセッション レベルのセグメントに相当します。従来の動的セグメントを使用している場合は、dynamic::
プレフィックスを sessions::condition::
プレフィックスに置き換えて、新しい構文に移行する必要があります。たとえば、次の 2 つのセグメントは等価です。
dynamic::ga:browser==Chrome
上記のセグメントは、次のセグメントと等価です。
sessions::condition::ga:browser==Chrome
セグメントの例
1. ユーザー属性: 男性、EN-US 言語、ゲームに関心あり、アメリカ大陸からアクセス。
最初にユーザーベースのセグメントが適用されます。そのため、ユーザーベースの条件により、 ゲームに関心がある男性が返されます。次に、これらの ユーザーに属するセッションにセッションベースの条件が適用され、アクセス元が アメリカ大陸で、かつ言語が EN-US のセッションが取得されます。
users::condition::ga:userGender==Male;users::condition::ga:interestAffinityCategory==Games
;
sessions::condition::ga:region==Americas;sessions::condition::ga:language==en-u
2. 行動: 100 を超えるセッションを保持、過去 7 日間アクセスなし、セッションあたりのトランザクションが 3 以上、セッションあたりのサイトの滞在時間が 100 秒を超えるユーザー。
users::condition::ga:sessions>100;ga:daysSinceLastSession>=7;
perSession::ga:transactions>2;perSession::ga:sessionDuration>100
3. セッション: ブラウザが Chrome、国が米国、ヒットあたりの例外が 1 を超えるセッションを選択し、かつセッションあたりの離脱が 2 未満のユーザーを選択します。
sessions::condition::ga:browser==Chrome;ga:country==US;perHit::ga:exceptions>1;
users::condition::perSession::ga:exits<2
4. シーケンスを含むセッション: 「Chrome、ヒットあたりの合計イベント数が 5 を超える」ステップを選択し、「PC」ステップに続いて「モバイル端末」ステップを使用してユーザーを選択します。
sessions::sequence::ga:browser==Chrome;condition::perHit::ga:totalEvents>5;users::sequence::ga:deviceCategory==desktop->>ga:deviceCategory=mobile
5. セッションの日付: 2014 年 5 月 20 日から 2014 年 5 月 30 日までの間に最初のセッションを持ち、サイトの滞在時間が 600 秒を超えるユーザーを選択します。
users::sequence::^ga:sessionCount==1;dateOfSession<>2014-05-20_2014-05-30;->>ga:sessionDurationBucket>600
指標: プライマリ スコープ リファレンス
指標 | プライマリ スコープ |
---|---|
ga:adClicks | ヒット |
ga:adCost | ヒット |
ga:adsenseAdsClicks | ヒット |
ga:adsenseAdsViewed | ヒット |
ga:adsenseAdUnitsViewed | ヒット |
ga:adsenseCTR | ヒット |
ga:adsenseECPM | ヒット |
ga:adsensePageImpressions | ヒット |
ga:adsenseRevenue | ヒット |
ga:avgDomainLookupTime | ヒット |
ga:avgDomContentLoadedTime | ヒット |
ga:avgDomInteractiveTime | ヒット |
ga:avgEventValue | ヒット |
ga:avgPageDownloadTime | ヒット |
ga:avgPageLoadTime | ヒット |
ga:avgRedirectionTime | ヒット |
ga:avgScreenviewDuration | ヒット |
ga:avgSearchDepth | ヒット |
ga:avgSearchDuration | ヒット |
ga:avgSearchResultViews | ヒット |
ga:avgServerConnectionTime | ヒット |
ga:avgServerResponseTime | ヒット |
ga:avgUserTimingValue | ヒット |
ga:costPerConversion | ヒット |
ga:costPerGoalConversion | ヒット |
ga:costPerTransaction | ヒット |
ga:CPC | ヒット |
ga:CPM | ヒット |
ga:CTR | ヒット |
ga:domainLookupTime | ヒット |
ga:domContentLoadedTime | ヒット |
ga:domInteractiveTime | ヒット |
ga:domLatencyMetricsSample | ヒット |
ga:eventValue | ヒット |
ga:exceptions | ヒット |
ga:exceptionsPerScreenview | ヒット |
ga:fatalExceptions | ヒット |
ga:fatalExceptionsPerScreenview | ヒット |
ga:goalAbandonRateAll | ヒット |
ga:goalAbandonsAll | ヒット |
ga:goalCompletionsAll | ヒット |
ga:goalStartsAll | ヒット |
ga:goalValueAll | ヒット |
ga:goalValueAllPerSearch | ヒット |
ga:goalXXAbandonRate | ヒット |
ga:goalXXAbandons | ヒット |
ga:goalXXCompletions | ヒット |
ga:goalXXStarts | ヒット |
ga:goalXXValue | ヒット |
ga:impressions | ヒット |
ga:itemQuantity | ヒット |
ga:itemRevenue | ヒット |
ga:itemsPerPurchase | ヒット |
ga:localItemRevenue | ヒット |
ga:localTransactionRevenue | ヒット |
ga:localTransactionShipping | ヒット |
ga:localTransactionTax | ヒット |
ga:margin | ヒット |
ga:metricXX | ヒット |
ga:pageDownloadTime | ヒット |
ga:pageLoadSample | ヒット |
ga:pageLoadTime | ヒット |
ga:pageValue | ヒット |
ga:pageviews | ヒット |
ga:percentSearchRefinements | ヒット |
ga:redirectionTime | ヒット |
ga:revenuePerItem | ヒット |
ga:revenuePerTransaction | ヒット |
ga:ROI | ヒット |
ga:RPC | ヒット |
ga:screenviews | ヒット |
ga:searchDepth | ヒット |
ga:searchDuration | ヒット |
ga:searchGoalConversionRateAll | ヒット |
ga:searchGoalXXConversionRate | ヒット |
ga:searchRefinements | ヒット |
ga:searchResultViews | ヒット |
ga:searchUniques | ヒット |
ga:serverConnectionTime | ヒット |
ga:serverResponseTime | ヒット |
ga:socialActivities | ヒット |
ga:socialInteractions | ヒット |
ga:socialInteractionsPerSession | ヒット |
ga:speedMetricsSample | ヒット |
ga:timeOnScreen | ヒット |
ga:totalEvents | ヒット |
ga:totalValue | ヒット |
ga:transactionRevenue | ヒット |
ga:transactions | ヒット |
ga:transactionShipping | ヒット |
ga:transactionTax | ヒット |
ga:uniqueAppviews | ヒット |
ga:uniqueEvents | ヒット |
ga:uniquePageviews | ヒット |
ga:uniquePurchases | ヒット |
ga:uniqueScreenviews | ヒット |
ga:uniqueSocialInteractions | ヒット |
ga:userTimingSample | ヒット |
ga:userTimingValue | ヒット |
ga:adsenseExits | セッション |
ga:avgTimeOnPage | セッション |
ga:avgSessionDuration | セッション |
ga:bounces | セッション |
ga:entranceBounceRate | セッション |
ga:entranceRate | セッション |
ga:entrances | セッション |
ga:eventsPerSessionWithEvent | セッション |
ga:exitRate | セッション |
ga:exits | セッション |
ga:goalConversionRateAll | セッション |
ga:goalValuePerSession | セッション |
ga:goalXXConversionRate | セッション |
ga:organicSearches | セッション |
ga:pageviewsPerSession | セッション |
ga:percentSessionsWithSearch | セッション |
ga:screenviewsPerSession | セッション |
ga:searchExitRate | セッション |
ga:searchExits | セッション |
ga:searchSessions | セッション |
ga:sessionDuration | セッション |
ga:transactionRevenuePerSession | セッション |
ga:transactionsPerSession | セッション |
ga:bounceRate | セッション |
ga:sessions | セッション |
ga:sessionsWithEvent | セッション |
ga:newSessions | ユーザー |
ga:percentNewSessions | ユーザー |
ga:users | ユーザー |