[Amazon Connect] GetMetricDataで準リアルタイムな履歴メトリックスを取得する

1 はじめに

AIソリューション部の平内(SIN)です。

Amazon Connect(以下、Comnnect)ではn、昨年9月以降、キューメトリクスAPIが利用可能になっています。

APIとしては、リアルタイムメトリクスにアクセスできるGetCurrentMetricDataと、直前24時間からの準リアルタイムの履歴メトリクスにアクセスできるGetMetricDataの2つがあります。

今回は、このうち、準リアルタイムの履歴メトリクスが取得できる、GetMetricDataについて確認してみました。


参考:GetMetricData
参考:GetCurrentMetricData

2 制約等

(1) 利用制限

GetMetricDataは、1秒間に5コールまでという制限があり、これを超える場合は上限緩和の処置が必要です。
参考:Class: AWS.Connect

(2) 取得範囲

開始時間と終了時刻の間隔は、24時間以内である必要があります。この指定を超える場合、InvalidParameterExceptionのエラーとなります。

(3) 時間指定

開始時間と終了時刻は、10:05、10:10、10:15のような5分の倍数である必要があります。

(4) パーミッション

GetMetricDataを使用するためには、以下のパーミッションが必要です。

connect:GetMetricData

(5) データ反映

これは、個人的な使用感になってしまいますが、直近の時間を指定すると、データが反映されていない事があります。 履歴メトリックスのスケジュール保存でも、指定した時間から15分遅れて処理されることから、それぐらいのマージンが必須なのかも知れません。

3 SDK

JavaScriptのSDKから利用する場合は、以下のようになります。

var connect = new AWS.Connect();
connect.createUser(params, function (err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

パラメータの形式は、次のとおりです。
参考:Class: AWS.Connect

var params = {
  EndTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, /* required */
  Filters: { /* required */
    Channels: [
      VOICE,
      /* more items */
    ],
    Queues: [
      'STRING_VALUE',
      /* more items */
    ]
  },
  HistoricalMetrics: [ /* required */
    {
      Name: CONTACTS_QUEUED | CONTACTS_HANDLED | CONTACTS_ABANDONED | CONTACTS_CONSULTED | CONTACTS_AGENT_HUNG_UP_FIRST | CONTACTS_HANDLED_INCOMING | CONTACTS_HANDLED_OUTBOUND | CONTACTS_HOLD_ABANDONS | CONTACTS_TRANSFERRED_IN | CONTACTS_TRANSFERRED_OUT | CONTACTS_TRANSFERRED_IN_FROM_QUEUE | CONTACTS_TRANSFERRED_OUT_FROM_QUEUE | CONTACTS_MISSED | CALLBACK_CONTACTS_HANDLED | API_CONTACTS_HANDLED | OCCUPANCY | HANDLE_TIME | AFTER_CONTACT_WORK_TIME | QUEUED_TIME | ABANDON_TIME | QUEUE_ANSWER_TIME | HOLD_TIME | INTERACTION_TIME | INTERACTION_AND_HOLD_TIME | SERVICE_LEVEL,
      Statistic: SUM | MAX | AVG,
      Threshold: {
        Comparison: LT,
        ThresholdValue: 'NUMBER_VALUE'
      },
      Unit: SECONDS | COUNT | PERCENT
    },
    /* more items */
  ],
  InstanceId: 'STRING_VALUE', /* required */
  StartTime: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789, /* required */
  Groupings: [
    QUEUE | CHANNEL,
    /* more items */
  ],
  MaxResults: 'NUMBER_VALUE',
  NextToken: 'STRING_VALUE'
};
connect.getMetricData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

4 HistoricalMetric

パラメータ HistoricalMetricには、取得したい、メトリックスを配列で渡すことになりますが、指定可能な名前はは、以下のとおりです。


参考:HistoricalMetric

Valid Values: CONTACTS_QUEUED | CONTACTS_HANDLED | CONTACTS_ABANDONED | 
CONTACTS_CONSULTED | CONTACTS_AGENT_HUNG_UP_FIRST | CONTACTS_HANDLED_INCOMING | 
CONTACTS_HANDLED_OUTBOUND | CONTACTS_HOLD_ABANDONS | CONTACTS_TRANSFERRED_IN | 
CONTACTS_TRANSFERRED_OUT | CONTACTS_TRANSFERRED_IN_FROM_QUEUE | 
CONTACTS_TRANSFERRED_OUT_FROM_QUEUE | CONTACTS_MISSED | CALLBACK_CONTACTS_HANDLED | 
API_CONTACTS_HANDLED | OCCUPANCY | HANDLE_TIME | AFTER_CONTACT_WORK_TIME | 
QUEUED_TIME | ABANDON_TIME | QUEUE_ANSWER_TIME | HOLD_TIME | INTERACTION_TIME | 
INTERACTION_AND_HOLD_TIME | SERVICE_LEVEL

ここで、コンソールの履歴メトリックスから指定可能な項目と比較してみると、以下のようになります。

よく見てみると、コンソールからの方が、全然多いことに気が付きます。 特に、AVGのみで、SUMが存在しない項目が多数あるので、総数となるメトリックスと取得時間とで計算が必要そうです。

例えば、キューに関するメトリックスであれば、総数である、CONTACT_HANDLEと、取得時間から計算するイメージです。

5 コード

最後に、データ取得の一例です。2019.5.30の13:00(JST)から、2019.5.30の15:00(JST)までの3時間を取得しています。

const AWS = require("aws-sdk");
const connect = new AWS.Connect();

const historicalMetrics = [
    {Name: "ABANDON_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "AFTER_CONTACT_WORK_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "API_CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CALLBACK_CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_ABANDONED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_AGENT_HUNG_UP_FIRST",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_CONSULTED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_HANDLED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_HANDLED_INCOMING",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_HANDLED_OUTBOUND",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_HOLD_ABANDONS",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_MISSED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_QUEUED",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_TRANSFERRED_IN",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_TRANSFERRED_IN_FROM_QUEUE",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_TRANSFERRED_OUT",Unit: "COUNT",Statistic: "SUM"},
    {Name: "CONTACTS_TRANSFERRED_OUT_FROM_QUEUE",Unit: "COUNT",Statistic: "SUM"},
    {Name: "HANDLE_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "HOLD_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "INTERACTION_AND_HOLD_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "INTERACTION_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "OCCUPANCY",Unit: "PERCENT",Statistic: "AVG"},
    {Name: "QUEUE_ANSWER_TIME",Unit: "SECONDS",Statistic: "AVG"},
    {Name: "QUEUED_TIME",Unit: "SECONDS",Statistic: "MAX"},
    {Name: "SERVICE_LEVEL",Unit: "PERCENT",Statistic: "AVG", Threshold: { Comparison: "LT",ThresholdValue: 60}},
];

async function job(){
    const endTime = new Date(2019, 5 - 1, 30, 15, 0, 0); 
    const startTime = new Date(2019, 5 - 1, 30, 13, 0, 0);

    const queueId = '249f1a68-ffd4-47fc-89a2-dbe00bf1c4dd'
    const instanceId = '9a112eb9-b037-43d3-8113-53f615b8406f';

var params = {
        EndTime: endTime,
        Filters: { 
        Queues: [
            queueId
        ]
        },
        HistoricalMetrics: historicalMetrics,
        InstanceId: instanceId,
        StartTime: startTime,
        Groupings: [
            "QUEUE"
        ],
    };
    const data = await connect.getMetricData(params).promise();
    const metricResult = data.MetricResults[0];

    let results = [];
    metricResult.Collections.forEach( collection => {
        var name = collection.Metric.Name;
        var value = collection.Value;
        results.push(name + ":" + value + ":" + tags[name]);
    })
    results = results.sort().forEach( result =>{
        console.log(result);
    })
}

job();

const tags = {
    "ABANDON_TIME":"平均キュー中止時間(コールを中止する前にお客様がキューで経過した平均時間)",
    "CONTACTS_MISSED":"問い合わせの不在着信(エージェントにルーティングされたけれども、通話を承認しなかった場合にカウントされる)",
    "OCCUPANCY":"利用率",
    "CONTACTS_ABANDONED":"中止された問い合わせ(キューで待機中にエージェントに接続する前にお客様が切断した問い合わせの数)",
    "CONTACTS_QUEUED":"キューに保存された問い合わせ",
    "QUEUED_TIME":"キューに入っている最大時間",
    "SERVICE_LEVEL":"SLA",
    "AFTER_CONTACT_WORK_TIME":"連絡作業後の平均時間",
    "CONTACTS_HANDLED":"対応した問い合わせ",
    "CONTACTS_HANDLED_INCOMING":"対応した着信問い合わせ",
    "HANDLE_TIME":"平均処理時間",
    "QUEUE_ANSWER_TIME":"平均キュー応答時間",
    "INTERACTION_AND_HOLD_TIME":"エージェントの対応時間とお客様の保留時間の平均",
    "INTERACTION_TIME":"エージェントの平均対応時間",
    "CONTACTS_AGENT_HUNG_UP_FIRST":"エージェントが先に切断した問い合わせ",
    "CONTACTS_HOLD_ABANDONS":"保留中に切断された問い合わせ(エージェント+顧客)",
    "CONTACTS_HANDLED_OUTBOUND":"対応した発信問い合わせ"
}

6 最後に

今回は、準リアルタイムの履歴メトリクスが取得できる、GetMetricDataについて確認してみました。

実は、コンソールからスケジュールして保存できる履歴メトリックスと比べると、ちょっと、違いが感じられます。それぞれの特徴を把握して、使い所を見極める必要がありそうです。
参考:[Amazon Connect] 履歴メトリクスをスケジュール指定してCSVに保存する

7 参考リンク


Class: AWS.Connect
GetMetricData
GetCurrentMetricData


弊社では、Amazon Connectに関するキャンペーンを行なっています。
【6/27(木)東京】「1時間でクラウド型コンタクトセンターを構築できるようになる!無料Amazon Connectハンズオンセミナー」を開催します

また、音声を中心とした各種ソリューションの開発支援を行なっております。

コメントは受け付けていません。