OData Analytics Endpoint
Cognigy.AIは、分析レコードを取得するためにOData v4 analytics Endpointを公開しています。ODataはRESTの最良の方法であり、強力なAPIフレームワークです。OData Endpointを使用すると、GETリクエストを使用してCognigy.AIからすべての生データを取得できます。スプレッドシートできめ細かいクエリを作成したり、お気に入りのデータ可視化ツールでボット用の豊富なダッシュボードを構築したりするための企業分析のニーズをすべてカバーします。
Cognigy OData EndpointはGETリクエストのみに対応しており、PATCH、DELETE、POSTなどの他のリクエストタイプには対応していないことにご注意ください。
Technical video "Analytics & OData"Watch this Episode of Cognigy Sessions for a technical deep dive
使用方法と認証
サーバー上の OData URL で API キーを使用して、OData Endpoint に接続できます。
OData URLは、以下のようにサービスルート、apiのバージョン、コレクション、apiキーのパラメータで組み合わされます：
https://<odata domain>/<api-version>/<collection>?apikey=YOURAPIKEY
ODataドメイン名
OData Endpointは、Cognigyユーザーインタフェースドメインとは異なるドメインで使用できます。https://trial.cognigy.aiを介してCognigyにログインする場合、ODataドメインはhttps://odata-trial.cognigy.ai になります。
例えば、トライアルサーバーの場合、Analytics Inputs CollectionのOData Endpoint URLはhttps://odata-trial.cognigy.ai/v2.2/Inputs?apikey=YOURAPIKEY（YOURAPIKEYは各自のAPI Keyに置き換えてください）です。オンプレミスインストールの場合は、odata-trial.cognigy.aiドメイン名をローカルインストール用に設定したドメイン名に置き換えてください。
Excel/Power BI
PowerBIやExcelを使用する際、認証を求められることがあります。［anonymous authentication（匿名認証）]を選択してください。
Endpointのバージョン
- バージョン2.3
- バージョン2.2以前
v4.31.0で追加
現在のOData Endpointのバージョンはv2.3です。このバージョンでは、以下のODataコレクションが利用可能です：
- 分析
（/Analytics） - トーク
(/Conversations) - ステップ
(/Steps) - 実行ステップ
(/ExecutedSteps) - セッション
（/Sessions） - LiveAgentエスカレーション
(/LiveAgentEscalations)
V2.3 OData EndpointにアクセスするためのURLは次のとおりです：
https://<hostname>/v2.3/<collection>?apikey=YOURAPIKEY
OData v2.0～2.2の非推奨
Cognigy.AI v4.48.0では、OData Endpointのバージョン2.0～2.2が非推奨となり、削除されました。
- 入力 (/Inputs) – V2.3 Endpoint で Analytics に名称が変更されました。
- チャット履歴(/ChatHistory) – V2.3 EndpointでConversationsに名称が変更されました。
- ステップ (/Steps)
- 実行ステップ(/ExecutedSteps)
- トーク (/Conversations) – V2.3 EndpointではSessionsに名称が変更されました。
V2.XのOData EndpointにアクセスするためのURLは、次のとおりです：
https://<hostname>/v2.X/<collection>?apikey=YOURAPIKEY
クエリ
Endpointでは、以下の OData クエリ言語演算子をサポートしています：
- $filter
- $skip
- $top
- $orderby
- $count
- $select
$countとExcelまたはPowerBI
Microsoft ExcelおよびPowerBIは、$count クエリに対応していません。Postmanまたは他のオプションを使用してください。
リクエストの例
OData 2.3
| リクエスト説明 | OData 2.3リクエスト |
| 分析レコードの合計数を返します（ExcelまたはPowerBIには対応していません）。 | https://odata-trial.cognigy.ai/v2.3/Analytics/$count?apikey=YOURAPIKEY |
| 指定されたAPIKeyに対応するすべての分析レコードを返します。 | https://odata-trial.cognigy.ai/v2.3/Analytics?apikey=YOURAPIKEY |
| 分析レコードの最初の10件を返します。 | https://odata-trial.cognigy.ai/v2.3/Analytics/?$top=10&apikey=YOURAPIKEY |
| 実行時間が50ミリ秒未満の分析レコードの上位5件を、実行時間順に返します。 | https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=executionTime lt 50&$top=5&$orderby=executionTime&apikey=YOURAPIKEY |
| ProjectIdでフィルタリングされた特定のCognigy.AI Agentのすべての分析レコードを返します。 | https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=projectId eq 'PROJECTID'&apikey=YOURAPIKEY |
| 2つの日付（たとえば2021年1月1日と2021年7月1日）の間のすべての分析レコードを返します。 | https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=timestamp gt 2021-01-01T00:00:00.000Z and timestamp lt 2021-07-01T00:00:00.000Z&apikey=YOURAPIKEY |
参考ドキュメント
完全な情報については、OData.orgの広範なリソースコレクションとOasis OData URL Convention Documentationをご参照ください。
データ保護と分析
エージェント設定メニューから、OData Endpoint で利用可能なデータを制御・管理します。詳細については、[Data Protection & Analytics(データ保護と分析)]をご覧ください：
- Collect Analytics(分析の収集)を無効にすると、分析データはODataに記録されず、利用できなくなります。
- Mask Sensitive Analytics(機密分析をマスク) を有効にすると、inputTextとinputDataフィールドはマスクされます。
さらに、ノードの設定に従ってODataで利用可能な分析データを無効またはマスクするBlind Mode Nodeを使用して、Flowの内部で分析ログの動作を制御できます。
Cognigy.AI ODataコレクション
このセクションでは、OData Endpoint から取得できる ODataコレクション内にあるデータタイプについて詳しく説明します。次のコレクションを使用できます：
- Analytics（分析）
- Conversations（トーク）
- Steps（ステップ）
- ExecutedSteps（実行済みステップ）
- Sessions（セッション）
- LiveAgentEscalations（ライブエージェントエスカレーション）
フィールド
各コレクションはフィールドを返し、フィールドでフィルタリングできます。ODataレコードフィールドの多くは、入力オブジェクトの結果から直接取得されます。
入力オブジェクト内のこれらの変数については、こちらをご覧ください。
Analytics（分析）
説明
コンタクトがCognigy.AI Flowにメッセージを送信するたびに、Cognigy.AIはそのやりとりに関する詳細な分析ログを含む分析レコードを作成します。それぞれのやりとりは、1行の項目としてAnalytics Endpointで公開されます。このコレクションに書き込まれたデータはFlowの実行終了時に保存されるため、Overwrite Analytics Nodeを使用してこのコレクションに含まれるデータを上書きすることができます。
クエリの例
- OData 2.3
- OData 2.2
- OData 2.0
https://odata-trial.cognigy.ai/v2.3/Analytics?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.2/Inputs?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.0/Inputs?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | 一意の分析レコード ID | 文字列 | 5a91d194fde28b0011ce2423 |
| organisation | 組織の名前 | 文字列 | cognigy |
| projectId | プロジェクトID | 文字列 | 5a91d194fde28b0011ce2422 |
| flowReferenceId | FlowのID | 文字列 | 66ceb9cc-ac5b-4cdd-9f4b-8a48dfbb35d9 |
| entrypoint | プロジェクト/AgentのID、またはEndpointで使用されている場合のSnapshotのID | 文字列 | 621d3deb87016d3855ec0c92 |
| ip | リクエスト発信元のIPアドレス | 文字列 | 78.143.45.111 |
| contactId | 接続しているユーザーのID | 文字列 | myContactID |
| sessionId | セッションID | 文字列 | 5a91d194fde28b0011ce2425 |
| inputId | 一意の入力ID | 文字列 | 5a91d194fde28b0011ce2424 |
| inputText | 入力テキスト | 文字列 | Hello World! |
| inputData | 文字列としての入力データオブジェクト | 文字列 | {“key”:”value”} |
| state | 入力時のFlowのState | 文字列 | default |
| mode | 入力のモード | 文字列 | TextOnly |
| userType | 接続しているユーザーのタイプ。外部ユーザーの場合は “external”、管理ユーザーの場合は “admin” | 文字列 | external |
| channel | 入力があったチャネル | 文字列 | |
| flowLanguage | Flowの言語 | 文字列 | en-EN |
| intent | インテント検出（空白可） | 文字列 | orderFood |
| intentFlow | インテントが検出されたFlowの親ID（空白可） | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| intentScore | 認識されたインテントに対する入力の数値スコア (空白可) | 数値 | 0.836322430892043 |
| completedGoalsList | このセッションで完了したゴールのリスト | 文字列 | orderedFood |
| foundSlots | スロットタグ検出 | 文字列 | DATE |
| foundSlotDetails | 詳細付きスロットタグを検出 | 文字列 | DATE[2018-2-25T12:32:32.000] |
| understood | スロット、インテント、メッセージタイプが検出されたかどうか | ブーリアン型 | true |
| timestamp | 入力日時 | 日時 | 2018-2-25T12:32:32.000Z |
| executionTime | フロー実行に要した時間（ミリ秒） | 数値 | 32 |
| execution | 実行回数 | 数値 | 3 |
| custom1 | Flowが作成したカスタム値 | 文字列 | |
| custom2 | Flowが作成したカスタム値 | 文字列 | |
| custom3 | Flowが作成したカスタム値 | 文字列 | |
| custom4 | Flowが作成したカスタム値 | 文字列 | |
| custom5 | Flowが作成したカスタム値 | 文字列 | |
| custom6 | Flowが作成したカスタム値 | 文字列 | |
| custom7 | Flowが作成したカスタム値 | 文字列 | |
| custom8 | Flowが作成したカスタム値 | 文字列 | |
| custom9 | Flowが作成したカスタム値 | 文字列 | |
| custom10 | Flowが作成したカスタム値 | 文字列 | |
| localeReferenceId | ロケールの参照ID | 文字列 | |
| localeName | ロケール名 | 文字列 | |
| endpointUrlToken | EndpointのURLトークン | 文字列 | |
| endpointName | Endpoint名 | 文字列 | |
| rating | セッションの評価。マイナス評価なら-1、プラス評価なら1。 | 数値 | |
| ratingComment | 評価時に記入されたコメント | 文字列 | |
| snapshotName | Endpointで使用されるSnapshotの名前 | 文字列 |
カスタムフィールドの最大値
各カスタムフィールドの値として最大500文字を保存できます。
分析ステップラベルが使用されないのはなぜですか？
分析ステップラベルはCognigyユーザーインタフェースからいつでも更新できます。そのため、過去のすべてのデータレコードを将来のレコードと互換性を持たせるために、entityReferenceIdが使用されます。entityReferenceIDは、分析ステップとして割り当てられたNode IDまたはIntent IDです。ステップの現在の分析ラベルは、entityReferenceIDを Stepsレコードにマッピングすることで取得できます。
Conversations（トーク）
説明
Conversationsコレクションは、エンドユーザー、ボット、ヒューマンエージェントの応答を含む、すべてのセッションメッセージのログを表示します。これらのソースのいずれかがCognigy.AI Flowにメッセージを送信するたびに、Cognigy.AIはやりとりを記録するレコードを作成します。それぞれのやりとりは、1行の項目としてAnalytics Endpointに公開されます。
クエリの例
- OData 2.3
- OData 2.2
- OData 2.0
https://odata-trial.cognigy.ai/v2.3/Conversations?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.2/ChatHistory?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.0/ChatHistory?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | 一意の分析レコード ID | 文字列 | 5a91d194fde28b0011ce2423 |
| projectId | プロジェクトID | 文字列 | 5a91d194fde28b0011ce2422 |
| projectName | Cognigy.AIプロジェクト名 | 文字列 | Project 1 |
| inputId | 一意の入力ID | 文字列 | 5a91d194fde28b0011ce2424 |
| sessionId | セッションID | 文字列 | 5a91d194fde28b0011ce2425 |
| contactId | 接続しているユーザーのID | 文字列 | myContactID |
| organisation | 組織の名前 | 文字列 | cognigy |
| inputText | 入力テキスト | 文字列 | Hello World! |
| inputData | 文字列としての入力データオブジェクト | 文字列 | {“key”:”value”} |
| type | メッセージがFlowの入力であるか出力であるか | 文字列 | input or “output” |
| source | メッセージの発信元 | 文字列 | user or “bot” or “agent” or “suggestion” |
| timestamp | 入力日時 | 日時 | 2018-2-25T12:32:32.000Z |
| flowName | Flow名 | 文字列 | MainFlow |
| flowParentId | Flowの親ID | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| channel | 入力があったチャネル | 文字列 | |
| inHandoverRequest | セッションがハンドオーバーリクエスト中かどうかのフラグ | ブーリアン型 | false |
| inHandoverConversation | セッションがハンドオーバーセッションであるかどうかのフラグ | ブーリアン型 | true |
| outputId | 出力ID | 文字列 | f514b7b2-7dc0-4e75-be62-a53fed5b2bb7 |
Steps（ステップ）
v4.2で追加
説明
Stepsコレクションは、分析ステップとして割り当てられ、APIキーがアクセスできるフローに存在するすべてのエンティティ（エンティティはFlow NodeまたはIntent）のリストを表示します。分析ステップは、エンティティの設定で[Analytics Step]フィールドに値を追加することで、Cognigy.AIで作成されます。このODataコレクションにStepが存在するには、そのフローで少なくとも1つのセッションによってトリガーされている必要があります。ExecutedStepsに存在できる各ステップは、1行の項目としてこのAnalytics Endpointに公開されます。
クエリの例
- OData 2.3
- OData 2.2
- OData 2.0
https://odata-trial.cognigy.ai/v2.3/Steps?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.2/Steps?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.0/Steps?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | 一意の分析レコード ID | 文字列 | 5a91d194fde28b0011ce2423 |
| label | Cognigy.AIでエンティティ（nodeまたはintent）に定義された分析ステップラベル。 | 文字列 | Question (2) |
| type | エンティティの種類 | 文字列 | node or intent |
| entityReferenceId | 一意のエンティティID（Node IDまたはFlow ID） | 文字列 | 5a91d194fde28b0011ce2423 |
| flowReferenceId | FlowのID | 文字列 | 5a91d194fde28b0011ce2423 |
| flowName | ステップが存在するFlowの名前 | 文字列 | Main Flow |
| projectName | Cognigy.AIプロジェクト名 | 文字列 | Project 1 |
| snapshotId | SnapshotのID | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| snapshotName | Snapshot名 | 文字列 | Bot Release 2.2 |
ステップレコードを使用した可視化の構築
次の説明では、BIソフトウェアでこれらのレコードを操作して、理解しやすいセッションパス分析を作成する方法について説明します：Step Monitoring with OData（ODataを使用したステップのモニタリング）
ExecutedSteps（実行済ステップ）
説明
ExecutedStepsコレクションには、セッションで発生したすべてのステップイベントのリストが含まれます。また、その前に発生したステップ（親ステップ）への参照も含まれます。エンティティ（割り当てられたステップを持つFlow NodeまたはIntent）が実行されるたびに、このコレクションにレコードが作成されます。実行された各ステップは、1行の項目としてこの Analytics Endpointで公開されます。
クエリの例
- OData 2.3
- OData 2.2
- OData 2.0
https://odata-trial.cognigy.ai/v2.3/ExecutedSteps?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.2/ExecutedSteps?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.0/ExecutedSteps?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | 一意の分析レコード ID | 文字列 | 5a91d194fde28b0011ce2423 |
| userId | 接続しているユーザーのID | 文字列 | myContactID |
| sessionId | セッションID | 文字列 | 5a91d194fde28b0011ce2425 |
| inputId | メッセージID | 文字列 | 5a91d194fde28b0011ce2425 |
| stepLabel | Cognigy.AIでエンティティ（nodeまたはintent）に定義された分析ステップラベル。 | 文字列 | Question (2) |
| parentStep | このステップの前に発生したステップのID | 文字列 | 5a91d194fde28b0011ce2425 |
| type | エンティティの種類 | 文字列 | node or intent |
| entityReferenceId | 一意のエンティティID（Node IDまたはFlow ID） | 文字列 | 5a91d194fde28b0011ce2423 |
| flowReferenceId | FlowのID | 文字列 | 5a91d194fde28b0011ce2423 |
| flowName | ステップが存在するFlowの名前 | 文字列 | Main Flow |
| timestamp | ステップ実行時のタイムスタンプ | 日時 | 2018-2-25T12:32:32.000Z |
| projectName | Cognigy.AIプロジェクト名 | 文字列 | Project 1 |
| projectId | プロジェクトID | 文字列 | 6067352c18887e471da4e392 |
| organisationId | Cognigy.AI組織ID | 文字列 | 5f8833dae72b850ad2ed4d53 |
| snapshotId | SnapshotのID | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| snapshotName | Snapshot名 | 文字列 | Bot Release 2.2 |
Sesiions（セッション）
v4.41で追加
説明
Sessionsコレクションには、発生したすべてのセッションのリストが含まれます。このコレクションの主な目的は、任意のセッションで行われた分析ステップのリストと、それらが行われた順序のリストを表示することです。この情報は、stepPathと呼ばれる1つの列にカンマ区切りのリストとして含まれます。各セッションは、1 行の項目としてこの Analytics Endpointで公開されます。
クエリの例
- OData 2.3
- OData 2.2
- OData 2.0
https://odata-trial.cognigy.ai/v2.3/Sessions?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.2/Conversations?apikey=YOURAPIKEY
https://odata-trial.cognigy.ai/v2.0/Conversations?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | 一意の分析レコード ID | 文字列 | 5a91d194fde28b0011ce2423 |
| goals | セッションで達成されたすべてのゴール | 文字列 | Goal1, Goal2 |
| stepPath | 実行されたステップのカンマ区切りリスト | 文字列 | 9ac4f679-beae-4461-b9e3-43aece8b3430,f1e72fe3-f04b-48f5-b862-1e35ad253f18, … |
| stepsCount | ステップ数のカウント | 数値 | 10 |
| handoverEscalations | セッションがハンドオーバーをトリガーした回数 | 数値 | 3 |
| startedAt | 最初のメッセージを受信したタイムスタンプ | 日時 | 2018-2-25T12:32:32.000Z |
| userId | 接続しているユーザーのID | 文字列 | myContactID |
| sessionId | セッションID | 文字列 | 5a91d194fde28b0011ce2425 |
| localeReferenceId | ロケール名のID | 文字列 | en-EN |
| localeName | ロケール名 | 文字列 | English |
| endpointReferenceId | EndpointのID | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| endpointName | Endpoint名 | 文字列 | Webchat |
| projectName | Cognigy.AIプロジェクト名 | 文字列 | Project 1 |
| projectId | プロジェクトID | 文字列 | 6067352c18887e471da4e392 |
| organisationId | Cognigy.AI組織ID | 文字列 | 5f8833dae72b850ad2ed4d53 |
| snapshotId | SnapshotのID | 文字列 | 5e33b160e6236da3aa54221461a53f04 |
| snapshotName | Snapshot名 | 文字列 | Bot Release 2.2 |
LiveAgentEscalations（ライブエージェントエスカレーション）
v4.49で追加
説明
LiveAgentEscalationsコレクションは、Live Agentエスカレーションのレコードを含み、Live Agentへのハンドオーバーについての関連データを含みます。
クエリ例
- OData 2.3
https://odata-trial.cognigy.ai/v2.3/LiveAgentEscalations?apikey=YOURAPIKEY
データタイプ
このコレクションを取得する際、エンドポイントは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| _id | レコードの一意識別子 | 文字列 | 649be849b7fd71d48b9bacc8 |
| organisationId | レコードに関連する組織の識別子 | 文字列 | 5eb4a49d426cd3d05f2892a9 |
| projectId | レコードに関連するプロジェクトの識別子 | 文字列 | 6409b6c53c9687b5e78e6403 |
| sessionId | セッションの識別子 | 文字列 | session-2a38246e-0395-49a5-876d-dd5133fd5418 |
| timestamp | レコードが作成された日時 | 日時 | 2023-06-28T07:59:04.628Z |
| localeName | ロケール名 | 文字列 | en |
| status | レコードの現在のstatus | 文字列 | opened |
| inboxId | レコードに関連する受信トレイの識別子 | 文字列 | 7983 |
| inboxName | 受信トレイ名 | 文字列 | LA Chatbot-default |
| teamId | チームの識別子 | 文字列 | 8 |
| teamName | チーム名 | 文字列 | IT Support |
| labels | レコードに関連するラベルのリスト | 配列 | [Hardware] |
| agentId | エージェントの識別子 | 文字列 | 618cf7687614774ba028dcac |
| agentName | エージェントの識別子名 | 文字列 | John Smith |
| contactId | コンタクトの識別子 | 文字列 | 649ba8450d5df5cadf8b75b8 |
| endpointName | Endpoint名 | 文字列 | LA Chatbot |
| endpointType | Endpointの種類 | 文字列 | webchat2 |
| endpointUrlToken | エンドポイントに関連するトークンまたは識別子。 | 文字列 | ea30b8f20db52f9d86ea36fd55a7d66bd2c4c60eb24ac7ad52f1c9e173dd4cdb |
| channel | レコードが受信されたチャネル | 文字列 | admin-webchat |
| localeReferenceId | 特定のロケールを参照するための識別子 | 文字列 | 7eff993c-b801-4556-b111-1c319e8577cf |
| snapshotId | Snapshotの識別子 | 文字列 | 63ff0cc47a466cab278fd19b |
| endpsnapshotName | Snapshot名 | 文字列 | Prod-Snapshot 26.7.23 |
エンティティ関係図
このスキームは、コレクションエンティティ間の関係を記述したものです。
統合
Excel
Microsoft Excel 2016から接続する場合は、PowerQuery機能を使用する必要があります。PowerQuery機能は、[Data(データ)] > [Get & Transform(取得と変換)] > [New Query(新しいクエリ)] > [From Other Sources(その他のソースから)] > [From OData Feed(ODataフィードから)]にあります。これにより、OData v4フィードに接続されます。
PowerBI
[Power BI]ドキュメントの指示に従ってください。
Tableau
互換性のないODataバージョン
現在、Cognigy.AIはODataバージョン4. 0に対応しており、Tableauのバージョンによっては互換性がありません。
TableauでOData Feedを接続する方法はこちらをご覧ください。
OData Consumerエコシステム
利用可能なOData Consumerオプションの完全なリストについては、OData.orgのConsumersへのリンクをご参照ください。
.NET、Java、JavaScript、C++およびその他のプラットフォームのクライアントライブラリ
利用可能なODataライブラリの完全なリストについては、OData.org で利用可能なライブラリの最新ディレクトリをご参照ください。