Core Reporting API - セグメント

このドキュメントでは、Core Reporting API のセグメントの構文と、セグメントの使用 にあたっての考慮事項について説明します。

はじめに

Core Reporting API のセグメント機能を使用すると、次の 2 つの方法で Core Reporting API でセグメントをリクエストできます。

  1. ID によるセグメント: 組み込みセグメントまたはカスタム セグメントの数値 ID を使用してクエリを実行します。
  2. 動的セグメント: リクエスト時にセグメントを動的に指定します。

ID によるセグメント

組み込みセグメントまたはカスタム セグメントの ID を使用して、Core Reporting API でセグメントをリクエストできます。ユーザーが使用できるすべてのセグメントは、 Google アナリティクス Management API の Segments コレクションlist メソッドを使用して 取得できます。各セグメントの ID は、Segment リソースid プロパティにあります。

API リクエストでのセグメント ID の使用の詳細については、Core Reporting API リファレンスを参照してください。

動的セグメント

API リクエストを行うときにセグメントを動的に作成して使用することもできます。動的セグメントを作成する際に、次のことを考慮してください。

  1. ユーザーとセッションの選択
  2. 条件とシーケンスの使用
  3. 指標スコープの使用

動的セグメントを作成する際の各考慮事項の概要を以下で説明します。動的セグメントの完全な構文については、動的セグメントの構文リファレンスをご覧ください。

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

1.ユーザーとセッションの選択

ユーザーかセッション(またはその両方)を選択するかどうかを指定します。

  • ユーザーを選択するには、users:: を使用します。
  • セッションを選択するには、sessions:: を使用します。
  • users::sessions:: の両方の条件を指定する場合:
    1. まず、ユーザー条件が適用され、一致するユーザーのセッションが出力されます。
    2. セッション条件は、#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:pageviewsga:transactions は、ヒット内で発生するため、ヒットレベルの指標です。これに対し、ga:sessionDurationga:bounces は、セッションごとに 1 つの値を持つため、セッション レベルの指標です。概念的には、ユーザーは最上位レベルのスコープであり、ヒットは最下位レベルのスコープです。

指標値は、そのプライマリ スコープより上位のスコープで報告することもできます。たとえば、ga:pageviewsga: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 では、指定されたクエリが有効であることを確認するために、指標スコープの検証が実行されます。スコープの検証ルールを次に示します。

  1. 指定された指標スコープは、常に、(users:: プレフィックスまたは sessions:: プレフィックスで示される)親の条件スコープ以下である必要があります。
  2. 指定された指標スコープは、データモデルで定義されたプライマリ スコープ以上である必要があります。指標とそのプライマリ スコープの一覧については、指標: プライマリ スコープ リファレンスをご覧ください。

有効な指標スコープの例を次に示します。

  • 条件スコープと指標スコープが等しい場合(ユーザーレベル)。
    • 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
  • セッション レベルの指標に対してヒットレベルのスコープを使用している場合 (ヒットレベルはセッション レベルより小さい)。
    • 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 つ以上のディメンション条件や指標条件 から構成されます。

単純条件の有効な条件演算子は次のとおりです。

単純条件の構文は次のとおりです。

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:: プレフィックスを使用することもできます。セッション レベルの条件にも同じことが当てはまります。

たとえば、次のセグメントは等価です。どちらの場合も、 ユーザーを選択するためには condition1condition2AND 演算が行われます。
users::<condition1>;<condition2>
users::<condition1>users::<condition2>

シーケンス条件

シーケンス条件は 1 つ以上のステップで構成されます。この場合、各ステップは、1 つ以上のディメンション条件や指標条件によって定義されています。特殊なシーケンス演算子を使用して、複数のステップを組み合わせることができます。

シーケンス条件に有効なシーケンス演算子は次のとおりです。

  • –>> 演算子は、前のステップが次のステップより前に発生することを示します。
  • –> 演算子は、前のステップが次のステップの直前に発生することを示します。

シーケンス条件の構文は次のとおりです。

sequence:: NOT? FIRST_HIT_MATCHES_FIRST_STEP? (AND (PRECEDES|IMMEDIATELY_PRECEDES) <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ユーザー