アグリゲート API
アグリゲート API は、既存のテーブルと列データに関するアグリゲート統計を計算できるエンドポイントを提供します。
集計 API 要求の場合、クエリ対象のテーブル内のすべてのレコードに対する読み取りアクセス権が必要です。ACL によって要求元ユーザーがテーブル内のレコードにアクセスできない場合、要求は「403 Forbidden」というエラーを返します。
アグリゲート:GET /now/stats/{tableName}
指定されたテーブルのレコードを取得し、戻り値に対して集計関数を実行します。
sysparm_<aggregate>_fieldsパラメーターまたはsysparm_having=<aggregate>^field^operator^valueパラメーターのいずれかを使用して、実行する集計関数を指定し、次のいずれかの集計関数を<aggregate>で置き換えます。
- 平均
- 最大
- 最小
- sum
URL 形式
バージョニングされた URL: /api/now/{api_version}/stats/{tableName}
デフォルト URL: /api/now/stats/{tableName}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 |
| tableName | レコードを取得するテーブルの名前。 データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| 名前と値のペア | sysparm_query パラメーターを使用する代わりに使用できます。キーがフィールドの名前であるキーと値のペアを使用して、クエリをフィルタリングできます。 たとえば、パラメーター データタイプ：文字列 |
| sysparm_<アグリゲート>_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 など) に従う必要があります。複数のクエリーを指定するには、それぞれをカンマで区切って指定できます ( 例:count^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"
}
]
}
]
}