このドキュメントでは、Core Reporting API のセグメントの構文と、セグメントの使用 にあたっての考慮事項について説明します。
はじめに
Core Reporting API のセグメント機能を使用すると、次の 2 つの方法で Core Reporting API でセグメントをリクエストできます。
- ID によるセグメント: 組み込みセグメントまたはカスタム セグメントの数値 ID を使用してクエリを実行します。
- 動的セグメント: リクエスト時にセグメントを動的に指定します。
ID によるセグメント
組み込みセグメントまたはカスタム セグメントの ID を使用して、Core Reporting API でセグメントをリクエストできます。ユーザーで使用可能なすべてのセグメントは、Google Analytics Management API の
セグメント コレクションの list メソッドを使用して取得できます。各セグメントの ID は、
セグメント リソースの 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
- Chrome ブラウザが使用されたセッションが 1 回以上あったユーザーの中から、ロンドン市のセッションを選択します。
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:: 接頭辞と、;–>> 演算子または ;–> 演算子を使用して指定します。次に例を示します。
- PC を使用した後にモバイル端末を使用したユーザーを選択します。ユーザーをセグメント化するため、ユーザーのすべてのセッションが検索され、ユーザーが 1 回のセッションでパソコンを使用し、その後のいずれかのセッションでモバイル デバイスを使用したかどうかがチェックされます。
-
users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
-
- また、ステップごとに複数の条件を使用することもできます。
-
users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
-
- また、AND（つまり、「;」）演算子を使用します。
-
users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
-
単純な条件およびシーケンスに基づく条件の詳細については、構文リファレンスの conditionType セクションをご覧ください。 その他の例については、 セグメント、機能のリファレンスの 条件と シーケンスのセクションをご覧ください。
3. 指標スコープの使用
指標のスコープは、その指標が定義されるレベル（HIT、SESSION、USER）を定義します。たとえば、ga:pageviews と ga:transactions はヒットで発生するヒットレベルの指標ですが、ga:sessionDuration と ga:bounces はセッションごとに 1 つの値があるため、セッション レベルの指標です。概念的には、USER が最上位のスコープで、HIT が最下位のスコープです。
プライマリ スコープよりも大きいスコープで指標値をレポートすることもできます。例: ga:pageviews と ga:transactions は、セッションまたはユーザーで発生したヒットごとに加算するだけで、セッション単位とユーザー単位でレポートできます。
指標条件ごとにスコープを指定すると、その条件が適用される
レベルが決まります。指標スコープは、perUser::、perSession::、または perHit:: 接頭辞を使用して指定されます。
次に例を示します。
- ウェブサイトで 10 ドル以上の購入歴があるユーザー（ユーザーのライフタイム バリューが 10 ドル以上）。
users::condition::perUser::ga:transactionRevenue>=10
- セッションで 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は HIT レベルの指標であるため、条件で指定できるスコープはperHit::、perSession::、またはperUser::です（これらはすべて HIT レベルのスコープ以上であるため）。users::condition::perHit::ga:totalEvents>5users::condition::perSession::ga:totalEvents>5
無効な指標スコープの例を次に示します。
- 親の条件スコープが指標スコープよりも小さいため、次のセグメントは無効です（例:セッション < ユーザー）。
sessions::condition::perUser::ga:transactionRevenue>10
- セッション レベルの指標にヒットレベルのスコープを使用し、セッション レベルよりもヒットレベルを設定する。
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==/
複数の条件
すべてのユーザーレベルの条件を 1 つの 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 日です。使用方法の詳細については、以下のセッションの日付の例をご覧ください。
ディメンション条件と指標条件
条件の組み合わせ
1 つ以上のディメンション条件を AND（「;」）と OR（例:「,」）演算子と 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 |
[] |
list（値はリストされた値のいずれか）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
2In List 演算子 []
指定されたリストにある値をクエリできます。これは、ディメンションに対してのみ使用できます。値のリストは、「|」文字で区切ります。値に含まれる「|」はエスケープする必要があります。
構文:{dimensionName}[]{value1}|{value2}|...
制約:
リスト内ディメンション条件ごとに最大 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 を超えるステップを選択し、「パソコン」ステップに続いて「モバイル」ステップでユーザーを選択します。
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 | USER |