集計 API
集計 API は、既存のテーブルと列のデータに関する集計統計情報の計算を可能にするエンドポイントを提供します。
集計 API 要求の場合は、クエリ対象のテーブル内のすべてのレコードに対する読み取りアクセス権が必要です。ACL のために、要求元ユーザーがテーブル内のレコードにアクセスできない場合、要求は 403 Forbidden エラーを返します。
集計 - GET /now/stats/{tableName}
指定されたテーブルのレコードを取得し、返された値に対して集計関数を実行します。
<aggregate> を次のいずれかの集計関数に置き換えて、sysparm_<aggregate>_fields パラメーターまたは sysparm_having=<aggregate>^field^operator^value パラメーターのいずれかを使用して、実行する集計関数を指定できます。
- avg
- max
- min
- sum
URL 形式
バージョニングされた URL：/api/now/{api_version}/stats/{tableName}
デフォルトの URL：/api/now/stats/{tableName}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 |
| tableName | レコードを取得するテーブルの名前。 データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| name-value pairs | sysparm_query パラメーターの使用に代わるものです。キーがフィールドの名前である場合、キー値のペアを使用してクエリをフィルタリングできます。 たとえば、 データタイプ：文字列 |
| sysparm_<aggregate>_fields | 各集計操作を実行するフィールドのリスト。複数のフィールドを指定するには、それぞれをカンマで区切ります。たとえば、期間フィールドと優先度フィールドから平均値を取得するには、sysparm_avg_fields=duration,priority を使用します。注: クエリが意味のある結果を返すには、このパラメーター、sysparm_count パラメーター、またはその両方を指定します。どちらのパラメーターも渡されない場合、集計操作は実行されません。 データタイプ：文字列 |
| sysparm_count | クエリで返されたレコードの数を返すかどうかを決定するフラグ。 注: クエリが意味のある結果を返すには、このパラメーター、sysparm_<aggregate>_fields パラメーター、またはその両方を指定します。どちらのパラメーターも渡されない場合、集計操作は実行されません。 データタイプ：文字列 |
| sysparm_display_value | 参照フィールドまたは選択フィールド別にグループ化するときのデータ取得操作。この値に基づいて、クエリでデータベースの表示値、実際の値、またはその両方が返されます。
データタイプ：文字列 |
| sysparm_group_by | 返されたデータのグループ化の基準となるフィールド。複数のフィールドを指定するには、各フィールドをカンマで区切ります (sysparm_group_by=priority,state など)。データタイプ：文字列 |
| sysparm_having | 集計操作に基づくデータのフィルタリングを可能にする追加のクエリ。優先度が 3 を超えるクエリ結果内のレコードの数を取得するために、このパラメーターの値は aggregate^field^operator^value の構文に従う必要があります (count^priority^>^3 など)。複数のクエリを指定するには、それぞれをカンマで区切ります (ascount^state^=^1,avg^priority^>^3 など)。データタイプ：文字列 |
| sysparm_order_by | グループ化された結果の順序付けの基準となる値のリスト。フィールドまたは集計を使用して順序を指定できます。たとえば、 sysparm_order_by=AVG^state を指定すると、平均ステータス値が小さい結果のグループが最初に返されます。COUNT で並べ替えて、各グループのレコード数でレコードのグループを配置することもできます。順序を指定すると、グループはデフォルトで昇順に並べられます。降順でソートするには、 データタイプ：文字列 |
| sysparm_query | エンコードされたクエリ。 例： データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| なし |
ヘッダー
次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。 デフォルト： application/json |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー資格情報が間違っているか、渡されていません。 |
| 500 | 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。 |
応答本文のパラメーター (JSON または XML)
| 名前 | 説明 |
|---|---|
| 指定されたテーブルと指定された要求パラメーターに応じて異なります。 |
サンプル cURL 要求
curl "https://instance.servicenow.com/api/now/stats/incident?sysparm_avg_fields=reassignment_count%2Cbusiness_stc&sysparm_group_by=assignment_group" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": [
{
"stats": {
"avg": {
"business_stc": "804162.7143",
"reassignment_count": "1.0000"
}
},
"groupby_fields": [
{
"value": "",
"field": "assignment_group"
}
]
},
{
"stats": {
"avg": {
"business_stc": "2037371.0000",
"reassignment_count": "1.5000"
}
},
"groupby_fields": [
{
"value": "287ee6fea9fe198100ada7950d0b1b73",
"field": "assignment_group"
}
]
},
{
"stats": {
"avg": {
"business_stc": "1821488.2857",
"reassignment_count": "1.1111"
}
},
"groupby_fields": [
{
"value": "8a5055c9c61122780043563ef53438e3",
"field": "assignment_group"
}
]
},
{
"stats": {
"avg": {
"business_stc": "1730322.0000",
"reassignment_count": "1.2500"
}
},
"groupby_fields": [
{
"value": "287ebd7da9fe198100f92cc8d1d2154e",
"field": "assignment_group"
}
]
},
{
"stats": {
"avg": {
"business_stc": "1564478.6250",
"reassignment_count": "1.2500"
}
},
"groupby_fields": [
{
"value": "d625dccec0a8016700a222a0f7900d06",
"field": "assignment_group"
}
]
},
{
"stats": {
"avg": {
"business_stc": "1512202.2500",
"reassignment_count": "1.1111"
}
},
"groupby_fields": [
{
"value": "8a4dde73c6112278017a6a4baf547aa7",
"field": "assignment_group"
}
]
}
]
}