How Can We Help?

API 資料

Last Updated:

概要

Pendo Adoptのユーザーは、自分のAdoptのアカウントから他のソースにデータをプッシュするために、APIを利用することができます。

APIキーを作成できるのはAdoptの管理者のみです。APIキーの作成は、［設定］>［インテグレーション］に移動して行います。［インテグレーション］タブが使用できない場合は、アカウントでAPIが有効化されていません。APIアクセスについては、Pendo Adoptのプロバイダーにお問い合わせください。

注意：adopt.pendo.io以外の場所からアカウントにサインインする場合は、カスタムホスト名と一致するようにエンドポイントURLを更新する必要があります。

アグリゲーションAPIの資料

アグリゲーションAPI（Aggregation API） には、以下のエンドポイントからアクセスすることができます。

https://adopt.pendo.io/api/v1/aggregation

アグリゲーションは、データにアクセスするためのクエリ言語です。データソースを取得し、演算子を適用して計算を行うもので、JSONで記述されます。

アグリゲーションエンドポイントは一括エクスポート機能を目的としていないため、サイズやタイムアウト制限に達した場合は、異なる時間範囲でアグリゲーションを分割しなければならない場合があります。

データクエリは、MongoDBをモデルにした柔軟なアグリゲーションパイプラインを使用して実行されます。パイプラインの各ステップは、入力として行を取り、0個以上の行を出力します。基本単位は、名前付きフィールド（ネストされている可能性がある）フィールドを含む行です。上位レベルでは、アグリゲーションは以下の要素で構成されます。

  • 行ソースおよび時間指定
  • 行処理のためのパイプライン

指定された期間のすべての入力データ行がアグリゲーションパイプラインに送られます。これらのパイプラインで生成される行が、アグリゲーションの結果です。パイプラインは、パイプラインと入力に応じて、行がないこともあれば、多くの行を生成することもあります。

時間指定が24個の時間帯に分割される場合（1日の中で1時間ずつなど）、24個の独立したパイプラインが実行され、アグリゲーションの結果は24セットになります。それらは、それぞれ独立した結果となります。

ネストされたフィールド

構成の例

{ "name": { "first": "bugs", "last": "bunny" } }

フィールド名が必要な箇所では、フィールド名のドットリストを使用して、ネストされたオブジェクトを指定できます。

ネストされた指定子を使用して新しいフィールドを作成することもできます。不足している中間オブジェクトはすべて初期化されます。

上記の例では、name.lastというフィールドに、bunnyという値が入っています。

データストア

データストア  
訪問者 今まで閲覧したことのあるすべての訪問者の一般的な情報。
イベント 訪問者によるアプリケーションの各インタラクション。これには、クリック、ページロード、メタデータ、ガイドの各イベントが含まれます。ページとガイドの定義。

式

多くのパイプライン演算子で式がサポートされています。式は、関数呼び出しとともに、基本的なC言語の式の構文に従います。サポートされている演算子は、==、!=、&&、||、<、>、<=、>=、+、-、/、*、%、および!です。

数値はすべて浮動小数点に変換して計算され、C言語の演算順序が使用されます。

括弧()は、式のグループ化に使用できます。

比較演算子は文字列の比較に、論理演算子はブール値の比較に、等値演算子は2つのリストの比較に使用できます。

演算子|| および&&では、nullはfalseと同等に扱われます。

演算子==と!=は、nullを個別の値として扱い（つまりnull == nullだがnull != falseである）、nullをパラメータとして持つ他の演算子はnullを値として返します （つまり1 + null == null）。行に存在しないフィールドを検索すると、null が返されます。

listField[index]のような通常のJavaScriptスタイルのインデックスを使って、リストから値を抽出することができます。また、listField[start:end]のようなJavaScriptスタイルのスライスを使って、サブリストを作成することができます。さらに、負のインデックスを使用して、末尾から項目を検索できます。listField[-2]は、リストの最後から2番目の項目を返します。これはPython形式の構文に従ったものです。

値の配列は、["a","b","c"]もしくは[1,1+2,sum(a)]のようなものがサポートされます。配列の要素はすべて同じ型でなければなりません。配列から要素を選択するには、前項で定義したとおり、通常のJavascript形式のインデックスを使用します。（例：["a","b","c"][2]）

式の基本データ型は、数値（小数点付きまたは小数点なし）、二重引用符で囲まれた文字列、true、false, およびフィールド名（ネストしたフィールドを指定する場合はドット表記を使用）です。現在サポートされている関数は次のとおりです。

機能  
ceil(val) 数値valの上限を返す
val == nullならばnull
valが数値でない/nullでないならばerror
contains(listValue, item) 指定されたリストにitemがあればtrueを返す
contains(haystackString, needleString) needleがhaystackの中にあればtrueを返す（両方とも文字列）
floor(val) 数値valの下限を返す
val == nullならばnull
valが数値でない/nullでないならばerror
formatTime(goFormatString, timeInMillis) go-styleのgo書式の文字列の例を用いて指定された時刻をフォーマットする
hash(string) 指定された文字列の32ビットのハッシュ値を返す
if(testExpression, ifTrue, [ifFalse]) testExpressionがtrueならばifTrue値を返す
testExpressionがfalseならばifFalse値を返す
isNull(field) fieldがnullまたは存在しないならばtrueを返す
それ以外の場合はfalseを返す
len(listField) 指定されたリストの長さを返す
list(field1, field2, field3) 指定されたフィールドを含むリストを返す
listInRange(listField, minValue, maxValue) listFieldの中の、minValueとmaxValue（これらの値も含む）の間にある要素を含むリストを返す
map() 以下で詳しく説明
now() エポック秒（UNIX時間）から経過した現在の時間をミリ秒単位で返す
reverse(list) 指定されたlistの順番を逆にして返す
round(val) 数値valを最も近い整数に四捨五入した値を返す
val == nullならばnullを返す
valが数値でない/nullでないならばerrorを返す
split(s, sep) 文字列sepをフィールド区切りとして用いて、文字列sを文字列のリストに分割する
startOfPeriod(periodName, timeStamp) 渡されたtimestampを含む期間の最初のtimestampを返す
periodは「hourly（時間毎）」「daily（日次）」「weekly（週次）」「monthly（月次）」が指定可能
startsWith(haystack, needle) 文字列haystackが文字列needleで始まるならばtrueを返す
haystackがnilならばfalseを返す
sum(listValue) 数値以外の要素を無視して、指定されたリストの項目のsum （合計）を返す

map()関数

パラメータ2つの場合

map(users, users.name)

行に適用された場合

{ 
  "users": [
    { "id": 5, "name": "mickey" }, 
    { "id": "2", "name": "minnie" }
  ] 
}

応答の例

["mickey", "minnie"]

map()関数には、2つまたは3つのパラメータを取る2つの形式があります。より簡単な形式はmap(listField, expression) で、与えられた式を指定されたリストの各項目に適用し，結果のリストを返します。

listFieldには、オブジェクトのリストを指定する必要があります。つまり、整数のリストは機能しません。

 

> パラメータ3つの場合

map(x, names, len(x))

行に適用された場合

{ "names": ["bugs", "daffy"] }

応答の例

[ 4, 5 ]

3つのパラメータ形式のmap()の方がより一般的で、あらゆるタイプのリストで機能します。どのタイプでも機能しますが、2つのパラメータ形式の場合よりもオブジェクトのリストの処理速度が遅いことに注意してください。

最初のパラメータは、3番目のパラメータ（式）がマッピングされる特定の値を参照するために使用される識別子です。

どちらの形式も、リストパラメータがnullの場合は、nullを返します。

ソース（Source）の仕様

定義

{ 
  "source": { 
    "sourceType": {SOURCE PARAMS} 
  }, 
  "timeSeries": { 
    "first": timeInMsOrExpression, 
    "count": numberOfPeriods, 
    "period": periodName 
  } 
}

spawnを使用しない限り、sourceキーはパイプラインの最初のステップで指定する必要があります。その場合、source は存在しません。これは、アグリゲーションに対して、どのデータをパイプラインに送り込むかを指示するものです。

詳細  
sourceType アグリゲーションのためのデータのソース。

行ソースの指定

リレーショナルデータベースの言葉を使えば、行ソースはテーブルだと考えられます。行ソースで何ができるのかを理解すれば、全体として何が可能なのかを把握できるようになります。

行ソースのデータを返す場合は、さまざまな方法でスライスして細かく分割することができます。

「APIで何にアクセスできるか」の簡単な答えは、すべての主要なエンティティ、ページ使用率の日/時間のサマリー、ガイドのアクティビティや投票調査のためのイベントレベルのデータとなります。

sourceTypeでは、集約するデータの種類を指定します。それぞれのタイプには固有のパラメータがあります。パラメータを指定しないと、空の{}はnullで置き換えられます。

行ソースはパイプラインに入れる行の種類を指定し、通常はパラメーター化されています。行の期間はここでは指定されず、時系列指定の一部となります。

ソース  
イベント ある期間内にシステム上で発生したすべてのイベントのサマリーデータを返す。イベントクラスまたはイベントクラスのリスト{ "eventClass" : "web"|"ios"|["web","ios"] }を受け入れると、デフォルトで"web" を返す。
guideEvents 指定された期間内のすべてのガイドイベント（guideSeen/dismissed/advanced）を返す。guideId、もしくはguideIdとguideStepIdで制限可能。
guidesSeen 期間内に指定されたガイドを閲覧した各訪問者のfirstSeenAt、lastSeenAt、lastStateおよびseenCountを返す。パラメータは { "guideId" : guideId, "guideStepId" : guideStepId }であることが必須。ガイドを省略する（空白/null/指定なし）と、すべてのガイドのすべてのステップの行が表示され、ステップを省略すると、指定されたガイドのすべてのステップが表示される。
pageEvents 結果を1つのpageIdに絞り込むためのpageIdが指定されていない限り、すべてのページをカバーする。指定された期間内の結果を返す。イベントクラスまたはイベントクラスのリスト{ "eventClass" : "web"|"ios"|["web","ios"] }を受け入れると、デフォルトで"web" を返す。
pollEvents 指定された期間内のすべての投票調査の結果を返す。guideId、もしくはguideIdとpollIdで制限可能。
pollsSeen 期間内の投票調査の回答を返す。訪問者が同じ投票調査に複数の回答をしている場合、最新のもののみが返される。パラメータは{ "guideId" : guideId, "pollId" : pollId }であることが必須
訪問者 すべての訪問者とそのメタデータ。パラメータを{ "identified" : true }とすると、匿名の訪問者を排除可能

時系列

2015年7月10日から2015年7月12日の時系列の例

{ 
  "timeSeries": { 
    "period": "dayRange", 
    "first": 1436553419000, 
    "count": 3 
  } 
}

3時間前から現在時刻を含む現在までの時系列の例。

{ 
  "timeSeries": { 
    "period": "hourRange", 
    "first": "now() - 3 * 60601000", 
    "last": "now()" 
  }
}

timeSeriesは、各期間の長さとエポック秒（UNIX時間）からの最初の期間のタイムスタンプ（ミリ秒単位）で構成されています。firstが文字列の場合、タイムスタンプを導出する式として処理されます。

また、アグリゲーションに含める期間数、またはアグリゲーションに含める最後の期間を計算する式が必要となります。

詳細  
period dayRangeもしくはhourRange
first 期間開始のエポック秒（UNIX時間）からミリ秒単位で指定されたタイムスタンプ。
count アグリゲーションに含める期間の数

すべての期間が常に処理されます。最初の時刻が期間の開始と一致しない場合でも、最初の時刻を含む期間のすべてのデータが使用されます。

dayRangeの期間の場合、日はアカウントのタイムゾーンに合わせて調整されます。これは、サマータイムへの切り替えにより、dayRangeの期間に23時間または25時間のデータが含まれることがあるためです。これが望ましくない場合はhourRangeを使用できますが、大量のデータが処理されると、パフォーマンスに大きな影響があります。

イベント（ グループ化されたもの）

以下の行ソースには、日付範囲（相対または絶対）と期間（日）が必要です。これらは、日/時間、訪問者ID、アカウントID、サーバー名、およびIPアドレスの一意の組み合わせごとにデータの行を返します。

属性  
イベント 記録されたすべてのクリックイベントとページビューイベント（タグ付き、タグなしを問わず）
pageEvents タグ付けされたページと一致する記録されたすべてのページビュー

events行のソース

定義

{
    "source": {
        "events": null,
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"events":null,"timeSeries":{"first":"1506977216000","count":-30,"period":"dayRange"}}}]}}'

応答の例

{
    "results": [
        {
            "accountId": "Kappa Trust",
            "visitorId": "59",
            "numEvents": 12,
            "numMinutes": 1,
            "server": "www.some-domain.com",
            "remoteIp": "59.89.251.103",
            "parameters": null,
            "userAgent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
            "day": 1506830400000,
            "pageId": "allevents"
        }
    ],
    "startTime": 1504324800000
}
  • 日/時間、訪問者ID、アカウントID、サーバー名、IP アドレス、およびユーザーエージェントの一意の組み合わせごとに行を返します。
  • タグ付き、タグなしを問わず、すべてのイベントを含みます（pageId "allevents "に注意）
  • 合計時間、アクティブ日数などの測定に役立ちます。
  • オプションでwebもしくはiOSのeventClassを渡して、返すイベントバケットを指定することができます。

pageEvents行のソース

定義

{
    "source": {
        "pageEvents": {
            "pageId": "{pageId}"
        },
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pageEvents":{"pageId":"aJ0KOADQZVL5h9zQhiQ0q26PNTM"},"timeSeries":{"first":"1506977216000","count":-30,"period":"dayRange"}}}]}}'

応答の例

{
    "results": [
        {
            "accountId": "Acme Corp",
            "visitorId": "10",
            "numEvents": 1,
            "numMinutes": 1,
            "server": "www.some-domain.com",
            "remoteIp": "110.227.245.175",
            "parameters": null,
            "userAgent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
            "day": 1506484800000,
            "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
        }
    ]
}
  • タグ付けされたページルールに一致させることができるイベントを含みます。
  • ページ ID、日/時間、訪問者ID、アカウントID、サーバー名、IP アドレス、およびユーザーエージェントの一意の組み合わせごとに行を返します。
  • パラメータは、全ページデータの場合はnull 、特定ページの場合はpageId:PAGE_IDを使用できます。

イベント（グループ化されていないもの）

一部のイベントでは、グループ化されていないイベントを公開します。これらは、指定された期間だけ表示されます。

ソース  
guideEvents 訪問者とガイドとのインタラクション
guidesSeen 訪問者がいつガイドを閲覧したかの概要
guidesSeenEver 訪問者がいつガイドを閲覧したかの概要
pollEvents 訪問者の投票調査とのインタラクション
pollsSeen 訪問者が投票調査に回答した時期と内容の概要
pollsSeenEver 訪問者が投票調査に回答した時期と内容の概要

guideEvents行のソース

定義

{
    "source": {
        "guideEvents": null,
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guideEvents":null,"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'

応答の例

    { "accountIds": [ "Acme" ], "browserTime": 1462796392383, "country": "US", "type": "guideAdvanced", "guideId": "He3BLNt44i0xwO5AEJVIijEswro", "guideStepId": "4TaMV6TLY1JmKIFkprqOcQllU8k", "latitude": 35.823483, "loadTime": 0, "longitude": -78.825562, "region": "nc", "remoteIp": "209.136.209.34", "serverName": "your.app.com", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/601.5.17 (KHTML, like Gecko) Version/9.1 Safari/601.5.17", "visitorId": "johndoe@acme.com", "accountId": "Acme" }
  • 発生するガイドイベントごとに1つのイベント行を返します。これまでの例のようなサマリーやバケット構造ではありません。
  • フィールド値のタイプには、guideAdvanced、guideSeenおよびguideDismissedがあります。
  • 特定のガイドまたはステップを掘り下げるために使用できるパラメーターは、guideIdおよびguideStepIdです。
  • pollEventsは同様に動作し、発生する投票調査の回答ごとに1行を提供します。そのソースのパラメータとして、pollIdを指定できます。

guideSeen行のソース

定義

{
    "source": {
        "guidesSeen": {
            "guideId": "{guideId}",
            "guideStepId": "{guideStepId}"
        },
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエスト例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guidesSeen":{"guideId":"nWtgylnMqWeB4DynO5duF9ako-M","guideStepId":"mHO55y6WJvJ0CnsmUgAtiGtgobA"},"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'

応答の例

{
    "firstSeenAt": 1489673759222,
    "guideId": "nWtgylnMqWeB4DynO5duF9ako-M",
    "guideStepId": "mHO55y6WJvJ0CnsmUgAtiGtgobA",
    "lastAdvancedAutoAt": 0,
    "lastDismissedAutoAt": 0,
    "lastSeenAt": 1489674347693,
    "lastState": "advanced",
    "seenCount": 5,
    "visitorId": "avery"
}
  • 訪問者ID、ガイドID、およびステップIDの一意の組み合わせごとに行を返します。
  • さらに、guideIdとguideStepIdを指定して、特定のガイドまたはステップを掘り下げることもできます。
  • guidesSeenEver行ソースも同じ出力に使用できますが、時間に依存しないため、timeSeriesは必要ありません。

pollEvents行のソース

定義

{
    "source": {
        "pollEvents": null,
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pollEvents":null,"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'

応答の例

{
    "accountIds": [
        "Acme"
    ],
    "browserTime": 1462796392383,
    "country": "US",
    "type": "pollResponse",
    "guideId": "He3BLNt44i0xwO5A201IijEswro",
    "latitude": 35.823483,
    "loadTime": 0,
    "longitude": -78.825562,
    "pollId": "z7y94y62v3c",
    "region": "nc",
    "remoteIp": "209.136.209.34",
    "serverName": "your.app.com",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
    "visitorId": "user@acme.com",
    "accountId": "Acme",
    "pollResponse": "You guys rock!"
}
  • 投票調査の回答が発生するごとに1行を返します。
  • 特定の投票調査を掘り下げるために使用できるパラメーターは、guideIdおよびpollIdです。

pollsSeen行のソース

定義

{
    "source": {
        "pollsSeen": {
            "guideId": "{guideId}",
            "pollId": "{pollId}"
        },
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pollsSeen":{"guideId":"1wz09ZEAFp-HVl78Iw8oxpwbRZA","pollId":"3isny1qp7t2"},"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'

応答の例

{
    "accountId": "1",
    "guideId": "1wz09ZEAFp-HVl78Iw8oxpwbRZA",
    "pollId": "3isny1qp7t2",
    "response": 0,
    "time": 1500305598629,
    "visitorId": "1"
}
  • 期間内の投票調査の回答を返します。
  • 訪問者が同じ投票調査に複数回回答した場合、pollsSeenは直近の回答のみを返します。すべての回答を返すには、pollEventsを使用します。
  • 特定の投票調査イベントを掘り下げるには、パラメータとしてguideIdとpollIdを指定する必要があります。
  • pollsSeenEver行ソースも同じ出力に使用できますが、時間に依存しないため、timeSeriesは必要ありません。

エンティティ

エンティティとは、アグリゲーションの別名です。

エンティティ  
ガイド 訪問者に表示するアプリ内メッセージ
ページ プロダクト内の個々のページを識別する一連のルールのセット（URLルールで定義）
訪問者 プロダクトのユーザー

guides行のソース

定義

{ "source": { "guides": null } }

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guides":null}}]}}'

応答の例

{
    "attributes": { ... },
    "audience": [ ... ],
    "createdAt": 1440449676899,
    "createdByUser": {
        "first": "Someone",
        "id": "5269565705551872",
        "last": "Lastname",
        "role": 8,
        "username": "someone@yourcompany.com"
    },
    "expiresAfter": 1440472740000,
    "id": "BF_p40WvYWC2o81pvsdt1kjcIkI",
    "isMultiStep": false,
    "lastUpdatedAt": 1460734696429,
    "lastUpdatedByUser": {
        "first": "",
        "id": "4985730428305408",
        "last": "",
        "role": 8,
        "username": "someone@yourcompany.com"
    },
    "launchMethod": "auto",
    "name": "2015-08-24 - Maintenance tonight.",
"state": "disabled",
    "stateHistory": [ ... ],
    "steps": [
        {
            "advanceMethod": "button",
            "attributes": {
                "height": 395,
                "width": 440
            },
            "content": "",
            "createdByUser": {
                "first": "Someone",
                "id": "5269565705551872",
                "last": "Lastname",
                "role": 8,
                "username": "someone@yourcompany.com"
            },
            "elementPathRule": "",
            "guideId": "BF_p40WvYWC2o81pvsdt1kjcIkI",
            "id": "Itfe6aDRNtgx9J1XisQwaCxDS-A",
            "lastUpdatedAt": 1460734696429,
            "lastUpdatedByUser": {
                "first": "",
                "id": "4985730428305408",
                "last": "",
                "role": 8,
                "username": "someone@yourcompany.com"
            },
            "name": "",
            "rank": 5000000,
            "resetAt": 0,
            "type": "lightbox"
        }
    ]
}

stepsには、ライトボックス、ツールチップ、バナーなどの単一アイテムとウォークスルー用の複数アイテムが含まれます。

pages行のソース

定義

{ "source": { "pages": null } }

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pages":null}}]}}'

応答の例

{
    "results": [
        {
            "color": "gray",
            "createdAt": 1505938241596,
            "createdByUser": {
                "first": "Adam",
                "id": "5197072786522112",
                "last": "Lohner",
                "role": 8,
                "username": "somePerson@email.com"
            },
            "dirty": false,
            "group": {
                "color": ".groupColor01",
"createdAt": 1505937447295,
                "createdByUser": {
                    "first": "",
                    "id": "",
                    "last": "",
                    "role": 0,
                    "username": ""
                },
                "description": "",
                "id": "DEFAULTGROUP_01_",
                "items": [

                ],
                "lastUpdatedAt": 1505938327653,
                "lastUpdatedByUser": {
                    "first": "Adam",
                    "id": "5197072786522112",
                    "last": "Lohner",
                    "role": 8,
                    "username": "somePerson@email.com"
                },
                "length": 6,
                "name": "Dashboard"
            },
            "id": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
            "kind": "Page",
            "lastUpdatedAt": 1505938241596,
            "lastUpdatedByUser": {
                "first": "Adam",
                "id": "5197072786522112",
                "last": "Lohner",
                "role": 8,
                "username": "somePerson@email.com"
            },
            "name": "Dashboard",
            "rootVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
            "rules": [
                {
                    "designerHint": "http://some-domain.com/",
                    "parsedRule": "^https?://[^/]/?(?:;[^#])?(?:\?[^#])?(?:#.)?$",
                    "rule": "//*"
                }
            ],
            "rulesjson": "",
            "stableVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM-20170920201041.596687476",
"validThrough": 1506981600000
        }
    ]
}

タグ付けされたページ。タグ付きページごとに1行を返します。

 

訪問者

定義

{ "source": { "visitors": null } }

リクエストの例

curl -X POST 
https://adopt.pendo.io/api/v1/aggregation 
-H 'content-type: application/json' 
-H 'x-api-integration-key: [add_your_integration_key_here]' 
-d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"visitors":null}}]}}'

応答の例

{
    "results": [
        {
            "metadata": {
                "agent": {
                    "email": "ac@Cras.co.uk",
                    "ipaddress": "184.169.45.4",
                    "language": "en_US"
                },
                "auto": {
                    "accountid": "Epsilon united",
                    "accountids": [
                        "Epsilon united"
                    ],
                    "firstvisit": 1506965912312,
                    "id": "84",
                    "idhash": 2012371633,
                    "lastbrowsername": "Chrome",
                    "lastbrowserversion": "61.0.3163",
                    "lastoperatingsystem": "Mac OS X",
                    "lastservername": "some-domain.com",
                    "lastupdated": 1506976690418,
                    "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
                    "lastvisit": 1506976690112,
                    "nid": 84
                }
            },
            "visitorId": "84"
        }
    ]
}

visitorsソースは、これまでに閲覧した訪問者ごとに1行を返し、訪問者に関するさまざまなメタデータを含んでいます。各訪問者は一意のvisitorIdを持ちます。

匿名の訪問者を排除するために使用できるパラメーターは、null もしくは{"identified":true}です。

メタデータ  
自動 自動計算されたデータ
カスタム カスタムフィールドデータ
Salesforce Salesforceから同期されたデータ
セグメント セグメントから同期されたデータ

 

パイプライン

構文の例 #1

{ "cat": null }

構文の例 #2

{ "field": "firstName", "operator": "==", "value": "John" }

各ステップは{ "name" : parameterObject }のような形式を取ります。

ソース行は、パイプラインによって結果の行に変換されます。最後の行は、アグリゲーションステップの結果となります。パイプラインは任意の長さにすることができ、個々のステップの順番付きリストとして表されます。

演算子

演算子  
cat パラメータを取らず、各行を変更せずに返す。
count 入力行の数を数え、{ "count" : 456 }のような形式で1行を返す。
accumulate 複数のフィールドの実行中の合計を保持し、各行に合計の現在値を含める。パラメータは{ "totalField1" : "sourceField1" }のような形式。
eval 1つまたは複数の式に基づいて新しいフィールドを挿入する。形式は{ "fieldName1" : "expression" }。
identified 名前付きフィールドが匿名の訪問者ID{ "identified" : "visitorId" }のような行を除外する。訪問者IDは確認するフィールド名。
limit 最初のN行を返し、残りの部分を破棄する。形式は{ "limit" : 5 }。
select 1つまたは複数のフィールドを含む新しい行を構築する（古い行は破棄される）。形式は{ "fieldName1" : "expression" }。
set フィールドを定数値に設定する。形式は{ "set" : { "field1" : 5, "field2.nested" : 20 } }。
sort 指定したフィールドで行をソートする。形式は{ "sort" : [ "fieldName", "anotherFieldName" ] }。フィールド名の前に- を付けると、そのフィールドが逆順にソートされる。
unmarshal 埋め込まれたJSON文字列をサブオブジェクトに展開する。
useragent ユーザーエージェント文字列を解析された文字列セットに展開する。

spawnの演算

定義

{
    "spawn": [
        [
            {
                "source": {
                    "events": null,
                    "timeSeries ": {
                        "period": "dayRange",
                        "first": 1404745200000,
                        "count": 7
                    }
                }
            },
            {
                "cat": null
            }
        ],
        [
            {
                "source": {
                    "events": null,
                    "timeSeries ": {
                        "period": "month",
                        "first": 1404745200000,
                        "count": 7
                    }
                }
            },
            {
                "count": null
            }
        ]
    ]
}

spawn演算子はforkと同様に動作しますが、ネストされた各パイプラインが独自のソースを指定する必要があります。これにより、複数のソースを使用して、パイプの残りの部分で処理される1つの行ストリームを作成できます。

単一のパイプラインをインスタンス化するソースのみを使用できます。つまり、dayRange 、hourRange 、もしくはcountが1であるソースが使用できます。

ソースのtimeSeriesは、spawnパイプラインのソース仕様の一部です。

switchの演算

定義

{
    "switch": {
        "newField": {
            "existingField": [
                {
                    "value": "small",
                    "<": 10
                },
                {
                    "value": "medium",
                    ">=": 10,
                    "<": 20
                },
                {
                    "value": "large",
                    ">=": 20,
                    "<": 50
                }
            ]
        }
    }
}

switchの演算では、フィールドを任意の数の条件と照合し、元のフィールドが一致する条件に基づいて新しいフィールドを行に設定できます。

各行に対して、その値が一致する条件のセットを確認するためにexistingFieldが照合されます。

newFieldを指定された値に設定するには、すべての条件に合致する必要があります。一致する条件がない場合、またはexistingFieldが設定されていない場合、行はスキップされます。

上記の入力では、{ "existingField" : 15 }の行は{ "existingField" : 15, "newField" : "medium" }になります。

filterの演算

定義

{ "filter": "fieldName == 5 || len(anotherField) > 3" }

filterパイプライン演算子は、式を計算し、式がfalseである行を削除します。

forkの演算

以下は、accountIdとvisitorIdそれぞれの合計時間を計算するものです。

{
    "fork": [
        [
            {
                "group": {
                    "group": [
                        "visitorId"
                    ],
                    "fields": [
                        {
                            "time": {
                                "sum": "numMinutes"
                            }
                        }
                    ]
                }
            }
        ],
        [
            {
                "group": {
                    "group": [
                        "accountId"
                    ],
                    "fields": [
                        {
                            "time": {
                                "sum": "numMinutes"
                            }
                        }
                    ]
                }
            }
        ]
    ]
}

fork演算子を使用すると、パイプラインを複数のパイプラインに分割し、それぞれの子パイプラインがそのステップのすべての行を受信することができます。

同じ行がすべての子パイプラインに送信されることに注意してください。これは行のコピーではないので、1つのパイプラインで行われた行への変更はすべてのパイプラインで表示されます。

各パイプラインで生成された行は、すべて親パイプラインの残りの部分を通じて送信されます。forkのネストは可能ですが、十分にテストされていません（つまり確証はできません）。

空のパイプライン（行を変更せずに渡す）は許可されませんが、1つのcat演算を含むパイプラインは同じように動作します。

joinの演算

定義

{ "join": { "fields": [ "firstName", "lastNme" ], "width": 3 } }

join演算子は、1つ以上のキーに基づいて複数の行を結合します。フィールドの競合がある場合は、結合時に後に現れた行の値が優先されます。オプションのwidth引数により、joinで最終結果を構成する行数を指定できます。同じjoinキーを持つ行が多数出現すると、結合された行はパイプラインの次の処理に渡されます。後でそのjoinキーを持つ行が出現した場合は、新しい結合処理として扱われます。width行未満のjoinキーは、すべての入力行が確認された時点で処理されます。

groupの演算

特定された各訪問者が30日間にサイトで費やした時間を計算するリクエストの例

{
    "requestId": "last30daysVisitorTime",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [
        {
            "identified": "visitorId"
        },
        {
            "group": {
                "group": [
                    "visitorId"
                ],
                "fields": [
                    {
                        "minutes": {
                            "sum": "numMinutes"
                        }
                    }
                ]
            }
        }
    ]
}

注：カウント値180は、ガイドが存在する時間全体をカバーするのに十分な長さである必要があります。

group演算子は、柔軟なグループ化（SQLのGROUP BYと同様）と、フィールドの単純集計をサポートします。サポートされるパラメータは以下のとおりです。

パラメータ  
グループ 各グループで値が一致するフィールドのリスト
fields グループ全体で値が集約されるフィールドのセット
stringSort 結果の行はグループキーでソートされる。グループキーは、ソートのために文字列として扱われる（つまり「2」>「10」）。これにより、結果の順序が安定する。

それぞれの結果の行は、groupとfieldsの両方の指定で指定されたすべてのフィールドで構成されます。

アグリゲーションフィールドは、出力行で使用するフィールド名、アグリゲーション名、入力行のフィールド名で構成されます。たとえば、グループ内の行数を数えるには、{"outputField":{ "count" : "inputField" }}を使用し、一致する行数を数えます（ここではフィールド名を指定する必要がありますが無視します）。以下の行アグリゲーターをサポートしています。

アグリゲーター  
count グループ内の行数をカウントする。フィールド名がある場合、そのフィールドの重複しない出現回数をカウント。
listAverage リスト引数の個々の値の平均を求め、その平均値のリストを返す。
max 指定された（数値）フィールドの最大値を返す。
min 指定された（数値）フィールドの最小値を返す。
sum 指定したフィールドの値を合計する。
first 指定されたフィールドの最初の値を返す。（注："first" は入力順序が確定的である場合にのみ定義）

一意のvisitorIdsの数をカウントするには、以下のパイプラインを使用します。

[
    {
        "group": {
            "group": [
                "visitorId"
            ]
        }
    },
    {
        "visitorCount": {
            "count": null
        }
    }
]

それぞれのvisitorIdのイベント数を取得する場合は、以下を使用します。

[
    {
        "group": {
            "group": [
                "visitorId"
            ],
            "fields": {
                "eventCount": {
                    "count": "event"
                }
            }
        }
    }
]

reduceの演算

行数をカウントし、行の中の分フィールドを合計します。

[
    {
        "reduce": {
            "eventCount": {
                "count": null
            },
            "totalMinutes": {
                "sum": "numMinutes"
            }
        }
    }
]

reduce演算子は、すべての行を1つの行に集約し、フィールドに対してアグリゲーションを実行します。アグリゲーターと形式は、groupパイプライン処理のためのfieldsパラメーターと同一です。

30日間の総イベント数と総時間数を計算するリクエストの例。

{
    "requestId": "last30DaysEventAndMinuteTotals",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [
        {
            "reduce": [
                {
                    "events": {
                        "sum": "numEvents"
                    }
                },
                {
                    "minutes": {
                        "sum": "numMinutes"
                    }
                }
            ]
        }
    ]
}

データセット内の一意の訪問者数をカウントする

{
    "requestId": "numberOfUniqueVisitors",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [
        {
            "reduce": [
                {
                    "reduce": {
                        "visitors": {
                            "count": "visitorId"
                        }
                    }
                }
            ]
        }
    ]
}

groupとreduceを使用した一連のイベントに含まれる訪問者数と、それらの訪問者が使用した合計時間（分）をカウントするリクエストの例。

{
    "requestId": "lastDaysEventAndMinuteTotals",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [
        {
            "group": {
                "group": [
                    "visitorId"
                ],
                "fields": {
                    "visitorMinutes": {
                        "sum": "numMinutes"
                    }
                }
            },
            "reduce": {
                "visitorCount": {
                    "count": "numVisitors"
                },
                "totalMinutes": {
                    "sum": "visitorMinutes"
                }
            }
        }
    ]
}

segmentの演算

定義

{ "segment": { "id": "id" } }

セグメントによって、訪問者のグループを事前に選択できます。既存のセグメントは、segment演算子で行をフィルタリングします。

入力行のvisitorIdがセグメント内の項目と一致する場合に、入力行が渡されます。

bulkExpandの演算

訪問者をinfoというサブドキュメントに展開します。

{ "bulkExpand": { "info": { "visitor": "visitorId" } } }

expandをサポートするデータ型は、accountとvisitorです。

unwindの演算

unwindの演算を行うには、以下のようにします。

{ 
  "name": "fred", 
  "items": [
    { "v": "first" }, 
    { "v": "second" }, 
    { "v": "third" } 
  ] 
}

以下を試してみてください。

{ 
  "unwind": { 
    "field": "items", 
    "index": "itemIndex" 
  } 
}

レスポンスは次のようになります。

[{ 
  "name": "fred", 
  "items": { "v": "first" }, 
  "itemIndex": 0 
}, { 
  "name": "fred", 
  "items": { "v": "second" }, 
  "itemIndex": 1 
}, { 
  "name": "fred", 
  "items": { "v": "third" }, 
  "itemIndex": 2 
}]

unwind演算子は、項目のリストを個別の行に展開します。他の項目はすべて保持され、オプションでインデックスを追加できます。

" prefix": trueを追加すると、以下のようになります。

[
  { 
    "name": "fred", 
    "items": [{ "v": "first" }], 
    "itemIndex": 0 
  }, { 
    "name": "fred", 
    "items": [{ "v": "first" }, { "v": "second" }], 
    "itemIndex": 1 
  }, { 
    "name": "fred", 
    "items": [{ "v": "first" }, { "v": "second" }, { "v": "third" }], 
    "itemIndex": 2 
  }
]

また、各項目の左側のすべてが重要な場合は、unwindでそれらの項目を保持できます。

unwindのリストが空の場合、{ "keepEmpty" : true } が指定されない限り、行は出力されません。この場合、元の行が保持されます。

useragentの演算

定義

{ "useragent": { "output": "input" } }

useragent演算子は、フィールドinputのユーザーエージェント文字列を解析し、outputオブジェクトにレンダリングします。

アウトプット  
名前 ブラウザの名前（例：「MSIE」、「Chrome」など）
version ブラウザのバージョン
OS オペレーティングシステム（例：「Windows」、「Mac OS X」、「GNU/Linux」など）
type ユーザーエージェントのタイプ（例：「Browser」、「Crawler」など）

マルチアプリ

pageのソースを例に挙げると、特定のアプリをクエリしない場合、sourceは以下のようになります。

{ "source": { "pages": null } }

アプリに固有のアグリゲーションを実行するには、アグリゲーション内のsourceの値を、null（サブに関連するすべてのアプリのすべてのレコードを返すインジケータ）から、appIdの値を含めるように変更する必要があります。

appIdを含めると、サブスクリプション内のそのアプリケーションのみに関連するデータに結果がスコープされます。

すべての複数アプリのアグリゲーションでは、ヘッダー（Header）のx-api-integration-keyの値として、プライマリアプリのインテグレーションAPIキーを使用します。

appId

特定のアプリでクエリを実行するには、sourceは以下のようになります。

{
    "source": {
        "pages": {
            "appId": 5629499534213120
        }
    }
}

関連記事