OData Analytics Endpoint(OData分析エンドポイント)
Live Agentは、分析レコードを取得するためにOData v4 analytics Endpointを公開しています。RESTの最良の方法であるODataは、強力なAPIフレームワークです。OData Endpointsは、GETリクエストを使用してLive Agentから最も関連性の高いデータモデルを取得することができます。これは、スプレッドシートできめ細かいクエリを作成したり、お気に入りのデータ可視化ツールでボットに豊富なダッシュボードを構築するための企業分析のニーズをすべてカバーします。
Live Agent OData Endpointは、GETリクエストのみをサポートし、PATCH、DELETE、POSTなどの他のリクエストタイプはサポートされていないことにご注意ください。
Technical video "Analytics & OData"Watch this Episode of Cognigy Sessions for a technical deep dive
使用法と認証
OData エンドポイントに接続するには、Live Agent Access Token を取得します：
- Live Agent インタフェースを開きます。
- 左側メニューの[Profile Settings ( プロファイル設定 )]に進みます。
- [Access Token(アクセストークン)]セクションで、既存のトークンをコピーします。
- このトークンをODataリクエストに貼り付けます。
OData URLは、以下のように、サービスルート、APIバージョン、サービスパス、データコレクション、およびLive Agentアクセストークンパラメータで構成されます：
GET /<api-version>/odata/<OData data model>?<odata query> HTTP/1.1
Host: <odata domain>
Authorization: Bearer <Live Agent access token>認証は、以下のようなクエリパラメータを使って行うことも可能です：
/<api-version>/odata/<OData data model>?<odata query>&apikey=<Live Agent access token>ODataドメイン名
ODataエンドポイントは、Cognigy User Interfaceドメインとは異なるドメインで使用できます。
例 https://odata-liveagent-trial.cognigy.ai/v1.0/odata
例えば、トライアルサーバー上では、Analytics Inputs CollectionのODataエンドポイントURLはhttps://odata-liveagent-trial.cognigy.ai/v1.0/odata/Message? です。
オンプレミスインストールの場合は、odata-trial.cognigy.aiドメイン名をローカルインストール用に設定したドメイン名に置き換えてください。
Excel/Power BI
PowerBIまたはExcelを使用する際、認証を求められる場合があります。匿名認証を選択し、＆apikey=のクエリパラメータとしてLive Agentのアクセストークンを指定します。
Endpointのバージョン
バージョン 1.0
OData Endpointの現在のバージョンはv1.0です。このEndpointバージョンは、LiveAgentバージョン1.0.0以降で使用できます。このバージョンでは、以下のODataコレクションが使用できます：
利用可能なすべてのODataモデルを表示するには、以下のEndpointをご利用ください: https://<hostname>/v1.0/odata/
V1.0 OData EndpointにアクセスするためのURLは以下の通りです: https://<hostname>/v1.0/odata/<collection>
クエリ
Endpoint は、以下のODataクエリ文字列演算子をサポートしています：
$filter$select$skip$top$orderby$expand
クエリ例
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation(1)?$select=inbox_id,account_id&apikey=<access-token> id=1のトークについて、inbox_id列とaccount_id列の戻り値。
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?$select=id,account_id&apikey=<access-token> すべてのトークのid列とaccount_id列の戻り値。
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?$select=id,account_id&$filter=created_at le '2021-11-23T00:00:00'&apikey=<access-token> created_at列が'2021-11-23T00:00:00' 以前であるとフィルタリングされた、すべての Conversationsのid列と account_id列の戻り値。
参考資料
参考資料の全容については、[OData.org の広範リソースコレクション]および[Oasis OData URL Convention Documentation]をご参照ください。
データ保護と分析
Live Agentの管理者ロールを持つユーザーのみが、ODataモデルへのクエリを実行できます。
Live Agent OData コレクション
このセクションでは、OData Endpointから取得できるOData Collections内に存在するデータタイプの詳細を紹介します。利用可能なコレクションは次のとおりです：
- メッセージ
- トーク
- ユーザー
- ラベル
- 受信トレイ
メッセージ
説明:
メッセージは、Agentとクライアント間の1つのコミュニケーションです。AgentまたはユーザーがEnterを押すたびに、そのテキストが新しいメッセージ行として書き込まれます。メッセージテーブルでは、全ての受信トレイとトークから全てのメッセージを見つけることができます。
クエリ例:
- V1.0 エンドポイント:
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Message?
データ種別:
このデータモデルを取得すると、Endpointは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| id | 固有メッセージID | 数値 | 1 |
| content | 送信されたメッセージ | 文字列 | Welcome to Live Agent |
| account_id | アカウントID | 数値 | 1 |
| inbox_id | 受信トレイID | 数値 | 1 |
| conversation_id | トークID | 数値 | 1 |
| message_type | メッセージタイプ | 数値 | 3 |
| created_at | メッセージタイプ作成日 | 日付 | 2021-12-11 12:41:26.745 |
| updated_at | メッセージ更新日 | 日付 | 2021-12-11 12:41:26.745 |
| private | メッセージの可視性 | ブーリアン型 | false |
| status | メッセージのステータス | 数値 | 3 |
| source_id | メッセージソース | 文字列 | default |
| content_type | text: 0, input_text: 1, input_textarea: 2, input_email: 3, input_select: 4, cards: 5, form: 6, article: 7, incoming_email: 8, input_csat: 9, typescognigy: 2016, request_file_upload: 2017 | 数値 | 0 |
| content_attributes | JSON属性/値の定義 | JSON | “{\”items\”:[{\”title\”:\”Acme Hardware\”]}” |
| sender_type | メッセージの発信者情報を提供 | 文字列 | cognigy |
| sender_id | 送信者固有ID | 数値 | 1 |
| external_source_ids | 外部ソースID | JSON | “{\”items\”:[{\”title\”:\”Acme Hardware\”]}” |
トーク
説明:
Conversationとは、Agentとクライアントの間に開かれるコミュニケーションチャネルです。
クエリ例:
- V1.0 エンドポイント:
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?
データ種別:
このデータモデルを取得すると、Endpointは以下のフィールドを返します:
| フィールド名 | 説明 | 種別 | 例 |
| id | 固有トークID | 数値 | 1 |
| account_id | アカウントID (トークの属する) | 数値 | 1 |
| inbox_id | 受信トレイID (トークの属する) | 数値 | 1 |
| status | トークのステータス: | 数値 | 1 |
| assignee_id | Agent ID (トークに割り当てられた) | 数値 | 1 |
| created_at | トーク作成日 | 日付 | 2021-12-11 12:41:26.745 |
| updated_at | トーク更新日 | 日付 | 2021-12-11 12:41:26.745 |
| contact_id | クライアント固有の認証 | 数値 | 3 |
| display_id | 表示ID | 数値 | 3 |
| contact_last_seen_at | 最後にコンタクト/クライアントが確認された日付 | 日付 | 2021-12-11 12:41:26.745 |
| agent_last_seen_at | 最後にAgentが確認された日付 | 日付 | 2021-12-11 12:41:26.745 |
| additional_attributes | 任意の追加属性を含むJSON | JSON | {} |
| contact_inbox_id | コンタクト受信トレイID | 数値 | 1 |
| uuid | 固有の識別子 | 文字列 | 89f20666-e17d-427c-9283-268ba7870283 |
| identifier | 識別子 | 文字列 | ‘”89f20666-e17d-427c-9283-268ba7870283″ |
| last_activity_at | 最終稼働日 | 日付 | 2021-12-11 12:41:26.745 |
| team_id | チームID (トークに属している) | 数値 | 1 |
| campaign_id | キャンペーンID | 数値 | 1 |
| snoozed_until | スヌーズ終了日 | 日付 | 2021-12-11 12:41:26.745 |
| custom_attributes | 追加アドオン属性 | JSON | {} |
| assignee_last_seen_at | 担当者が最後に確認された日付 | 日付 | 2021-12-11 12:41:26.745 |
受信トレイ
説明:
受信トレイは、特定のAgentからのすべてのトークが保存される場所です。
クエリ例:
- V1.0 エンドポイント:
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Inbox?
データ種別:
このデータモデルを取得すると、Endpointは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| id | 固有レコードID | 数値 | 1 |
| channel_id | チャンネルID | 数値 | 1 |
| name | 受信トレイ名 | 文字列 | Welcome to Live Agent |
| account_id | アカウントID | 数値 | 1 |
| created_at | 受信トレイ作成日 | 日付 | 2021-12-11 12:41:26.745 |
| updated_at | 受信トレイ更新日 | 日付 | 2021-12-11 12:41:26.745 |
| channel_type | API、WebWidget、Facebookなどのコミュニケーションチャンネル | 文字列 | Channel:WebWidget |
| enable_auto_assignment | Agentがトークを自動割り当てする機能 | ブーリアン型 | true |
| greeting_enabled | 挨拶文を自動送信する機能 | ブーリアン型 | false |
| greeting_message | 自動挨拶メッセージ | 文字列 | “Hi there!” |
| email_address | Emailアドレス | 文字列 | default |
| working_hours_enabled | 勤務時間表を有効にする機能 | ブーリアン型 | true |
| out_of_office_enabled | 営業時間外に表示されるデフォルトのメッセージ | 文字列 | Out of office hours, try again tomorrow |
| timezone | 受信トレイタイムゾーン | 文字列 | UTC |
| enable_email_collect | Eメール収集が可能 | ブーリアン型 | true |
| csat_survey_enabled | CSAT調査が可能 | ブーリアン型 | true |
| cognigy_organization_id | CognigyアカウントID | 数値 | 1 |
| cognigy_project_id | CognigyプロジェクトID | 数値 | 1 |
| enable_auto_reassignment | トークの再割り当てが可能 | ブーリアン型 | true |
| conversation_show_all | 自分のものでなくても、受信トレイにあるすべてのトークを見ることが可能 | ブーリアン型 | true |
ラベル
説明:
ラベルは、異なるトークにマークをつけたり、区別したり、グループ化したりするために使用されています。
クエリ例:
- V1.0 エンドポイント:
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Label?
データ種別:
このデータモデルを取得すると、Endpointは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| id | 固有ラベルID | 数値 | 1 |
| title | ラベルタイトル | 文字列 | label-complain” |
| description | ラベルの説明 | 文字列 | “labels used for complains” |
| color | ラベルの色 | 文字列 | “red” |
| show_on_sidebar | サイドバーにラベルを表示が可能 | ブーリアン型 | true |
| account_id | ラベルが属するアカウント | 数値 | 3 |
| created_at | ラベル作成日 | 日付 | 2021-12-11 12:41:26.745 |
| updated_at | ラベル更新日 | 日付 | 2021-12-11 12:41:26.745 |
ユーザー
説明:
このデータモデルは、AgentのようなLive Agentユーザーに関する情報を保持します。
クエリ例:
- V1.0 エンドポイント:
https://odata-liveagent-trial.cognigy.ai/v1.0/odata/User?
データ種別:
このデータモデルを取得すると、Endpointは以下のフィールドを返します：
| フィールド名 | 説明 | 種別 | 例 |
| id | 固有レコードID | 数値 | 1 |
| provider | 例：Eメール | 文字列 | ‘”email” |
| uid | 提供された固有識別子 | 文字列 | ‘”some-email@cognigy.com” |
| encrypted_password | パスワードの暗号化 | 文字列 | “2a11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38hjovasd” |
| reset_password_token | パスワードのリセットに使用されるトークン | 文字列 | “2a11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38rjsvaru” |
| reset_password_send_at | パスワードリセットが送信された日付 | 日付 | 2021-12-11 12:41:26.745 |
| remember_created_at | 作成日を記憶 | 日付 | 2021-12-11 12:41:26.745 |
| sign_in_count | ユーザーのログイン回数 | 数値 | 3 |
| current_sign_in_at | 現在のログイン日 | 日付 | 2021-12-11 12:41:26.745 |
| last_sign_in_at | 最終ログイン日 | 日付 | 2021-12-11 12:41:26.745 |
| current_sign_in_ip | 現在のログインIPアドレス | 文字列 | ‘”120.0.0.1″ |
| last_sign_in_ip | 現在のログインIPアドレス | 文字列 | ‘”120.0.0.1″ |
| confirmation_token | 認証トークン | 文字列 | “2a11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38hjovasd” |
| confirmed_at | 認証トークン確認日時 | 日付 | 2021-12-11 12:41:26.745 |
| confirmation_sent_at | 認証トークン送信日時 | 日付 | 2021-12-11 12:41:26.745 |
| unconfirmed_email | 未確認Eメール | 文字列 | ‘”unconfirmed@cognigy.com” |
| name | ユーザー名 | 文字列 | ‘”Francisco” |
| display_name | ユーザー表示名 | 文字列 | ‘”Paco” |
| ユーザーEmailアドレス | 文字列 | fran@cognigy.com | |
| tokens | ユーザートークン | JSON | “”{\”MN4iNP38tvwe5wer7pvpnAQ\”:{\”token\”:\” 10$iA7Si0sBV9lMkO2mqvwiD.L90.uTCl27WQbEo/Kc0W\”,\”expiry\”:1644763988}}”” |
| created_at | ユーザー作成日 | 日付 | 2021-12-11 12:41:26.745 |
| updated_at | ユーザー更新日 | 日付 | 2021-12-11 12:41:26.745 |
| pubsub_tokens | ユーザーパブリッシュ/サブスクライブトークン | 文字列 | MiVxY3FKry6oklambiuqL72nn |
| availability | これは、ユーザーの空席状況を表します。 | 数値 | 1 |
| ui_settings | ユーザー向けUI設定 | JSON | “{“is_conv_actions_open”: true, ‘”is_contact_sidebar_open”: true}” |
| custom_attributes | カスタム属性 | JSON | “{}” |
| cognigy_user_id | CognigyユーザーID | 文字列 | “610bEOk617uPiXy9L3HOq8nn6kdjJK2” |
統合
Excel
Microsoft Excel 2016から接続する場合は、PowerQuery機能を使用する必要があります。PowerQuery機能は、[Data(データ)] > [Get & Transform(取得と変換)] > [New Query(新しいクエリ)] > [From Other Sources(その他のソースから)] > [From OData Feed(ODataフィードから)] にあります。これにより、OData v4フィードに接続されます。
Power BI
Power BIドキュメントの指示に従ってください。
Tableau
互換性のないODataバージョン
Cognigy.AIはODataバージョン4.0をサポートしているため、Tableauのバージョンによっては互換性がありません。
ODataフィードの接続方法については、[Tableau]のドキュメントをご覧ください。
ODataコンシューマーエコシステム
利用可能なODataコンシューマーオプションの一覧については、OData.orgの[Consumers]リンクからご覧ください。
.NET、Java、JavaScript、C++、その他のプラットフォームのクライアントライブラリ
利用可能なODataライブラリの一覧については、OData.orgの利用可能なライブラリの最新ディレクトリをご覧ください。