## EMS restful interfaces

---

### 1. 状态管理

* URI:

  ```
  /api/rest/systemManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/systemState?ne_id=0
  ```

  说明：

  ```Tips
  ** elementTypeValue=all/smf/amf/..
  ** all: 表示所有配置的NF（ems前端->后端）
  ** smf：查询smf网元
  ** 参数ne_id指网元标识，指定ne_id条件表示查询该网元系统状态（ems前端->后端需要带该参数）
  ```
* Method:

  > GET
  >
* Return:

  ```json

      "data": [
          {
              "AMF_0": {
                  "error": {
                      "errorCode": "1",
                      "errorInfo": "Internal server error, NF connnect refused"
                  },
                  "ipAddress": "192.168.2.188"
              }
          },
          {
              "SMF_0": {
                  "ipAddress": "192.168.1.232",
                  "systemState": {
                      "capability": 10000,
                      "cpuUsage": {
                          "nfCpuUsage": 2,
                          "sysCpuUsage": 52
                      },
                      "diskSpace": {
                          "partitionInfo": [
                              {
                                  "total": 1920,
                                  "used": 0
                              },
                              {
                                  "total": 393,
                                  "used": 13
                              },
                              {
                                  "total": 48700,
                                  "used": 32431
                              },
                              {
                                  "total": 1965,
                                  "used": 0
                              },
                              {
                                  "total": 5,
                                  "used": 0
                              },
                              {
                                  "total": 1965,
                                  "used": 0
                              },
                              {
                                  "total": 55,
                                  "used": 55
                              },
                              {
                                  "total": 63,
                                  "used": 63
                              },
                              {
                                  "total": 91,
                                  "used": 91
                              },
                              {
                                  "total": 49,
                                  "used": 49
                              },
                              {
                                  "total": 55,
                                  "used": 55
                              },
                              {
                                  "total": 73,
                                  "used": 73
                              },
                              {
                                  "total": 91,
                                  "used": 91
                              },
                              {
                                  "total": 1475,
                                  "used": 206
                              },
                              {
                                  "total": 49,
                                  "used": 49
                              },
                              {
                                  "total": 393,
                                  "used": 13
                              },
                              {
                                  "total": 393,
                                  "used": 0
                              },
                              {
                                  "total": 73,
                                  "used": 73
                              },
                              {
                                  "total": 63,
                                  "used": 63
                              }
                          ],
                          "partitionNum": 19
                      },
                      "expiryDate": "2025-02-28",
                      "memUsage": {
                          "nfUsedMem": 163992,
                          "sysMemUsage": 1345,
                          "totalMem": 4025608
                      },
                      "serialNum": "13740126",
                      "version": "1.5.3.2"
                  }
              }
          },
          {
              "SMF_1": {
                  "ipAddress": "192.168.1.173",
                  "systemState": {
                      "capability": 10000,
                      "cpuUsage": {
                          "nfCpuUsage": 0,
                          "sysCpuUsage": 69
                      },
                      "diskSpace": {
                          "partitionInfo": [
                              {
                                  "total": 3966,
                                  "used": 0
                              },
                              {
                                  "total": 797,
                                  "used": 0
                              },
                              {
                                  "total": 200559,
                                  "used": 5968
                              },
                              {
                                  "total": 3987,
                                  "used": 0
                              },
                              {
                                  "total": 5,
                                  "used": 0
                              },
                              {
                                  "total": 3987,
                                  "used": 0
                              },
                              {
                                  "total": 797,
                                  "used": 0
                              }
                          ],
                          "partitionNum": 7
                      },
                      "expiryDate": "2024-12-31",
                      "memUsage": {
                          "nfUsedMem": 212136,
                          "sysMemUsage": 720,
                          "totalMem": 8167360
                      },
                      "serialNum": "13740272",
                      "version": "1.5.3.3"
                  }
              }
          }
      ]
  }
  ```

### 2. 数据库管理（内部接口）

#### 2.1 查询(select)

* URI:

  ```
  /api/rest/databaseManagement/{apiVersion}/{databaseName}/{tableName}?SQL={SQL}|WHERE={WHERE}
  ```
* Method:

  > GET
  >
* Params:

  > 参数关键字大小写敏感
  >

  * WHERE

    > WHERE=id=1 and parent_id=0
    >

    说明：

    ```Tips
    ** 表名为tableName带的表名
    ```
  * SQL

    > SQL=select count(*) from sysmenu&SQL=SELECT * FROM menu
    >

    说明：

    ```Tips
    ** 支持多个SQL查询
    ** SQL只能是查询语句
    ** tableName带的表名忽略
    ** 特殊字符需要转义，如"%"需转义为"%25"
    ```
* Return:

  ```json
  {
      "data": [
          {
              "tableName1": [
                  {
                      "column1": value1,
                      "column2": value2,
                      "column3": value3,
                      ...
                  }
              ]
          },
          {
              "tableName2": [
                  {
                      "column1": value11,
                      "column2": value12,
                      "column3": value13,
                      ...
                  },
                  {
                      "column1": value21,
                      "column2": value22,
                      "column3": value23,
                      ...
                  }
              ]
          }
      ]
  }
  ```
* Example:

  * WHERE:

    ```
    /api/rest/databaseManagement/v1/omc_db/menu?WHERE=id=1
    ```

    ```json
    {
        "data": [
            {
                "menu": [
                    {
                        "href": "111",
                        "icon": "11",
                        "id": 1,
                        "parent_id": 0,
                        "remark": "0",
                        "title": "test"
                    }
                ]
            }
        ]
    }
    ```

  * SQL:

    ```
    /api/rest/databaseManagement/v1/omc_db/menu?SQL=select count(*) from sysmenu&SQL=SELECT * FROM menu
    ```

    ```json
    {
        "data": [
            {
                "sysmenu": [
                    {
                        "count(*)": 4
                    }
                ]
            },
            {
                "menu": [
                    {
                        "href": "111",
                        "icon": "11",
                        "id": 1,
                        "parent_id": 0,
                        "remark": "0",
                        "title": "test"
                    },
                    {
                        "href": "31",
                        "icon": "313",
                        "id": 2,
                        "parent_id": 1,
                        "remark": "0",
                        "title": "test1"
                    }
                ]
            }
        ]
    }
    ```

#### 2.2 增加（insert）

* URI:

  ```
  /api/rest/databaseManagement/{apiVersion}/{databaseName}/{tableName}
  ```
* Method:

  > POST
  >
* Body:

  > 参数关键字大小写敏感
  >

  ```json
  {
      "menu": [
          {
              "id": 3,
              "title": "test3",
              "icon": "113",
              "href": "1113",
              "parent_id": 2,
              "remark": "0"
          }
      ]
  }
  ```

  说明：

  ```Tips
  ** 支持多条插入数据
  ** 支持多个表插入数据
  ** tableName带的表名忽略
  ```
* Return:

  ```json
  {
      "data": {
          "affected rows": 1
      }
  }
  ```

#### 2.3 修改（update）

* URI:

  ```
  /api/rest/databaseManagement/{apiVersion}/{databaseName}/{tablename}?WHERE={where}
  ```
* Method:

  > PUT
  >
* Params:

  * WHERE
    ```Tips
    参数关键字大小写敏感
    exp: WHERE=id=1
    ```
* Body:

  ```json
  {
      "menu": [
          {
              "title": "test3",
              "icon": "113",
              "href": "1113",
          }
      ]
  }

  ```
* Return:

  ```json
  {
      "data": [
          {
              "tableName1": [
                  {
                      "column1": value1,
                      "column2": value2,
                      "column3": value3,
                      ...
                  }
              ]
          },
          {
              "tableName2": [
                  {
                      "column1": value11,
                      "column2": value12,
                      "column3": value13,
                      ...
                  },
                  {
                      "column1": value21,
                      "column2": value22,
                      "column3": value23,
                      ...
                  }
              ]
          }
      ]
  }
  ```

#### 2.4 删除（delete）
* URI:

  ```
  /api/rest/databaseManagement/{apiVersion}/{databaseName}/{tablename}?WHERE={where}
  ```
* Method:

  DELETE

* Params:

  * WHERE
    ```Tips
    参数关键字大小写敏感
    exp: WHERE=id=1
    ```
* Body:

    NA

* Return:

  Code: 200/204

### 3. 配置管理

#### 3.1 参数配置表

* 类型定义（type）

  * string
    > filter指定字符串长度，如："filter": "6~100" , 字符串的长度范围，如果单个数字表示最大长度
    >
  * ipv4
    > filter忽略
    >
  * ipv6
    > filter忽略
    >
  * int
    > filter指定整型数的范围，如："filter": "100~999"
    >
  * enum
    > "filter": '{"0": "http", "1": "https"}'
    >
  * bool
    > "filter": '{"0": "false", "1": "true"}'
    >
  * regex
    > filter为正则表达式
    >
* Example

  ```yaml
  UDM:
  system:
      display: "System"
      list:
      - name: "serviceIP"
          type: "ipv4"
          value: "172.16.5.140"
          access: "read-write"
          filter: ''
          display: "Service IP"
          comment: ""
      - name: "servicePort"
          type: "int"
          value: "8080"
          access: "read-write"
          filter: "0~65535" 
          display: "Service Port"
          comment: "0~65535"
  subsSmfSelection:
      display: "Subs Smf Selection"
      array:
      - name: "index"
          type: "int"
          value: "0"
          access: "read-write"
          filter: '0~15'
          display: "Index"
          comment: "0~15"
      - name: "name"
          type: "string"
          value: 'def_ambr'
          access: "read-write"
          filter: '^.{1,32}$'
          display: "Name"
          comment: "0~32"
      - name: "snssai"
          type: "string"
          value: '1-000001'
          access: "read-write"
          filter: '^\d{1,3}[A-Fa-f0-9]{6}$'
          display: "Snssai"
          comment: ""
      - name: "dnnList"
          type: "int"
          value: '0'
          access: "read-write"
          filter: '0~3'
          display: "Dnn List"
          comment: ""
          array:
          - name: "index"
              type: "int"
              value: "0"
              access: "read-write"
              filter: '0~15'
              display: "index"
              comment: "0~15"
          - name: "dnn"
              type: "string"
              value: 'cmnet'
              access: "read-write"
              filter: '^.{1,32}$'
              display: "Dnn"
              comment: "0~32"
          - name: "defaultDnnInd"
              type: "bool"
              value: 'true'
              access: "read-write"
              filter: 'false;true;'
              display: "default Dnn Indicator"
              comment: ""  
  ```

  完整文件具体请参考 udm_param_config.yaml

#### 3.2 获取参数

* URI

  ```
  /api/rest/systemManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/config/{paraName}?ne_id=0&loc={index0}/{paraName1}/{index1}/...
  ```

  说明

  ```Tips
  apiVersion: "v1"
  elementTypeValue: udm, smf, amf... 网元类型
  udm paraName: system, subsUEAmbr, subsSmfSelection ...
  非array的参数，忽略loc
  ```
* Params

  * loc 多层表的定位信息
  * ne_id 网元标识 (ems前端->后端需要带该参数)
* Method

  > GET
  >
* Return

  ```
  /api/rest/systemManagement/v1/elementType/udm/objectType/config/system
  ```

  ```json
  {
      "data": [
          {
              "serviceIP": "172.16.5.140",
              "servicePort": "8080",
              "...": "..."
          }
      ]
  }
  ```

  ```
  /api/rest/systemManagement/v1/elementType/udm/objectType/config/subsSmfSelection?loc=1/dnnList
  ```

  ```json
  {
      "data": [
          {
              "index": "0",
              "dnn": "cmnet",
              "...": "..."
          },
          {
              "index": "1",
              "dnn": "ims",
              "...": "..."
          }     
      ]
  }
  ```

#### 3.3 配置参数

* URI

  ```
  /api/rest/systemManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/config/{paraName}?ne_id=0&loc={index0}/{paraName1}/{index1}
  ```
* Params

  * loc 多层表的定位信息
  * ne_id 网元标识 (ems前端->后端需要带该参数)
* Method

  > POST/PUT/DELETE


  说明：

  ```Tips
  单层表不支持POST/DELETE操作
  ```
* Body

  ```json
  {
      "serviceIP": "172.16.5.140",
      "servicePort": "8080",
      "...": "..."
  }
  ```

  说明：

  ```Tips
  DELETE操作忽略Body
  ```

#### 3.4 创建网元

* URI

  ```
  /api/rest/systemManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/neInfo
  ```
* Params

    N/A    

* Method

  > POST

* Body
  ```json
  {
    
  }
  ```

### 4 跟踪管理

#### 4.1 订阅管理

* 创建订阅

  * URI

    ```
    /api/rest/traceManagement/{apiVersion}/subscriptions
    ```
  * Method

    > POST
    >
  * Body

    ```json
    {
        "id": "1",
        "filter": "...",
        "callbackUrl": "https://x.x.x.x:x/api/rest/traceManagement/v1/events"
    }
    ```
  * Return

    > {}
    >
* 查询订阅

  * URI
    查询单个订阅：

    ```
    /api/rest/traceManagement/{apiVersion}/subscriptions/{id}
    ```

    查询所有订阅：

    ```http
    /api/rest/traceManagement/{apiVersion}/subscriptions
    ```
  * Method

    > GET
    >
  * Body

    > null
    >
  * Return

    ```json
    {
        "data": [
            {
                "id": "1",
                "filter": "...",
                "callbackUrl": "https://x.x.x.x:x/api/rest/traceManagement/v1/events"
            }
        ]
    }
    ```
* 删除订阅

  * URI

    ```
    /api/rest/traceManagement/{apiVersion}/subscriptions/{id}
    ```
  * Method

    > DELETE
    >
  * Body

    > null
    >

#### 4.2 事件上报

* 事件上报

  * URI

    ```
    /api/rest/traceManagement/{apiVersion}/events
    ```
  * Method

    > POST
    >
  * Body

    ```json
    {
        "data": [
            {    
                "id": ["1", "2"],
                "key1": "",   
                "key2": "...",
                "content": "content0......"
            },
            {    
                "id": ["1", "3"],
                "key1": "",  
                "key2": "...",
                "content": "content1......"
            }  
        ]
    }
    ```
### 5 性能管理

#### 5.1 任务管理

* URI
    ```
    /api/rest/performanceManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/measureTask?id={taskId1}&id={taskId2}
    ```
* Method
    
    POST/PUT/DELETE/PATCH

* Params
 
    taskId=1&taskId=2

    * POST: 增加测量任务，激活任务，不带id参数，id在body
    * PUT： 修改测量任务，激活任务，不带id参数，id在body
    * DELETE：删除测量任务，不需要带body，带id参数，可带多个
    * PATCH: 暂停测量任务，不需要带body，带id参数，可带多个
    
* Relation NF

   OMC -> NF/NF -> OMC

* Body

    下发测量任务的报文结构
    ```json
    type MeasureTask struct {
        Tasks []struct {
            Id int `json:"Id"`

            StartTime string `json:"StartTime"`
            EndTime   string `json:"EndTime"`

            Schedule struct {
                Type    string `json:"Type"` // 计划类型：Weekly/Monthly
                Days    []int  `json:"Days"` // Weekly: [0,1,...5,6]，0~6表示星期日~星期六, Monthly: [1,2,3,...,30,31]一个月的几天
                Periods []struct {
                    Start string `json:"Start"` // 零点或者零点加测量粒度的整数倍 00:15:00
                    End   string `json:"End"`   // 零点加测量粒度的整数倍 08:45:00, 16:15:00
                } `json:"Periods"`
            } `json:"Schedule"`

            GranulOption string `json:"GranulOption"` // 测量粒度选项：15M/30M/60M/24H

            KPISet []struct {
                Code string   `json:"Code"` // 统计编码 如：SMFHA01
                KPIs []string `json:"KPIs`  // 指标项集合 ["SMF.AttCreatePduSession", "SMF.AttCreatePduSession._Dnn"]
            } `json:"KPISet"`
        } `json:"Task"`
    }
    ```

* Return
  
#### 5.2 测量数据上报
* URI
    ```
    /api/rest/performanceManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/measureReport
    ```
* Method
    
    POST

* Body
      
    网元返回测量数据的报文结构
    ```json
    type MeasureReport struct {
        Id        int    `json:"Id"`
        Timestamp string `json:"TimeStamp"`

        Report struct {
            Period struct {
                StartTime string `json:"StartTime"`
                EndTime   string `json:"EndTime"`
            } `json:"Period"`

            Datas []struct {
                Code string `json:"Code"` // 统计编码 如：SMFHA01
                KPIs []struct {
                    KPIID     string `json:"KPIID"` // 指标项, 如： SMF.AttCreatePduSession._Dnn
                    KPIValues []struct {
                        Name  string `json:"Name"` // 单个的写"Total", 或者指标项有多个测量项，如Dnn的名称写对应的Dnn"cmnet"/"ims"
                        Value int    `json:"Value"`
                    } `json:"KPIValues"`
                } `json:"KPIs"`
            } `json:"Datas"`
        } `json:"Report"`
    }
    ```
#### 5.3 黄金指标上报
* URI
    ```
    /api/rest/performanceManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/kpiReport/{index}
    ```
* Method
    
    GET
* Body

    ```json
    type KpiReport struct {
        Timestamp string `json:"TimeStamp"`
        Task      struct {
            Period struct {
                StartTime string `json:"StartTime"`
                EndTime   string `json:"EndTime"`
            } `json:"Period"`
            NE struct {
                NEName string `json:"NEName"`
                RmUID  string `json:"rmUID"`
                NeType string `json:"NeType"`
                KPIs   []struct {
                    KPIID string `json:"KPIID"`
                    Value int    `json:"Value"`
                    Err   string `json:"Err"`
                } `json:"KPIs"`
            } `json:"NE"`
        } `json:"Task"`
    }
    ```
### 6 故障管理
#### 6.1 告警上报
* URI
    ```
    /api/rest/faultManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/alarms
    ```
* Method
  
    POST

* Relation NF
  
    NF->OMC

* Body

    ```json
    type Alarm struct {
        AlarmSeq          int    `json:"alarmSeq"`
        AlarmId           string `json:"alarmId"`
        NeId              string `json:"neId"`
        AlarmCode         int    `json:"alarmCode"`
        AlarmTitle        string `json:"alarmTitle"`
        EventTime         string `json:"eventTime"`
        AlarmType         string `json:"alarmType"`
        OrigSeverity      string `json:"origSeverity"`
        PVFlag            string `json:"pvFlag"`
        NeName            string `json:"neName"`
        NeType            string `json:"neType"`
        ObjectName        string `json:"objectName"`
        LocationInfo      string `json:"locationInfo"`
        Province          string `json:"province"`
        AlarmStatus       int    `json:"alarmStatus"`
        SpecificProblem   string `json:"specificProblem"`
        SpecificProblemID string `json:"specificProblemID"`
        AddInfo           string `json:"addInfo"`
    }
    ```

#### 6.2 获取网元告警
* URI
    ```
    /api/rest/faultManagement/{apiVersion}/elementType/{elementTypeValue}/objectType/alarms
    ```
* Method
  
    GET

* Relationship
  
    OMC->NF

* Body
    
    n/a

* Return
    
    ```json
    type Alarms struct {
        Alarms []struct {
            AlarmSeq          int    `json:"alarmSeq"`
            AlarmId           string `json:"alarmId"`
            NeId              string `json:"neId"`
            AlarmCode         int    `json:"alarmCode"`
            AlarmTitle        string `json:"alarmTitle"`
            EventTime         string `json:"eventTime"`
            AlarmType         string `json:"alarmType"`
            OrigSeverity      string `json:"origSeverity"`
            PVFlag            string `json:"pvFlag"`
            NeName            string `json:"neName"`
            NeType            string `json:"neType"`
            ObjectName        string `json:"objectName"`
            LocationInfo      string `json:"locationInfo"`
            Province          string `json:"province"`
            AlarmStatus       int    `json:"alarmStatus"`
            SpecificProblem   string `json:"specificProblem"`
            SpecificProblemID string `json:"specificProblemID"`
            AddInfo           string `json:"addInfo"`
        } `json:"Alarms"`
    }
    ```
