[toc]

@qn-pandora/app-sdk提供了引用 Pandora 平台的基础能力的 Manager、工具包等。

1 Manager

1.1 SearchManager

对 Pandora 平台搜索相关 API 进行封装

使用方式

• 创建 SearchManager 时传递参数

import { SearchManager } from '@qn-pandora/app-sdk'

const searchCondition = {
  queryString: 'repo="testjwzfr"',
  time: {
    start: 0,
    end: 1589770122581
  }
}
const option = {
  task: {
    event: true,
    summary: true,
    timeline: true,
    result: true
  }
}
const searchManager = new SearchManager({
  searchCondition,
  option
})
searchManager.on('done', data => {
  console.log('data', data)
})
searchManager.search()

• 调用 search 方法时传递参数

import { SearchManager } from '@qn-pandora/app-sdk'

const searchCondition = {
  queryString: 'repo="testjwzfr"',
  time: {
    start: 0,
    end: 1589770122581
  }
}
const option = {
  task: {
    event: true,
    summary: true,
    timeline: true,
    result: true
  }
}
const searchManager = new SearchManager({
  option
})
searchManager.on('done', data => {
  console.log('data', data)
})
searchManager.search(searchCondition)

• 通过 jobId 获取数据

import { SearchManager } from '@qn-pandora/app-sdk'

const searchCondition = {
  queryString: 'repo="testjwzfr"',
  time: {
    start: 0,
    end: 1589770122581
  }
}
const option = {
  task: {
    event: true,
    summary: true,
    timeline: true,
    result: true
  }
}
const searchManager = new SearchManager({
  option
})
const jobId = await searchManager.search(searchCondition)

searchManager.on('done', data => {
  const event = searchMangeer.getEvent(jobId)
  console.log('event', event)
})

参数介绍

• searchCondition

  • queryString: 搜索条件
  • time: 搜索时间范围
    • start 搜索开始时间，时间戳
    • end 搜索结束时间，时间戳
  • preview: 可选，是否预览数据，默认值为 true
  • mode: 可选，搜索模式 "fast" | "smart" | "detailed"， 默认值为"smart"

• option

  • task，任务选项，根据需要开启特定任务进行计算
    • event: 事件信息
    • timeline: 时间柱
    • summary: 字段汇总统计
    • result: 聚合计算结果

方法

• search() 开启搜索任务，参数为 searchCondition，是可选项，不填则使用创建 searchManager 时的 searchCondition。该函数是个 Promise 函数，返回创建好任务的 jobId。
• getEvent(jobId) 获取事件信息结果
• getTimeline(jobId) 获取时间柱结果
• getSummary(jobId) 获取字段汇总统计结果
• getResult(jobID) 获取聚合计算结果
• stop() 停止当前任务

事件

可通过 on 函数注册监听事件回调函数

• data 每一次轮训数据结束触发，当开启 preview 时，可获取到中间结果
• done 轮训结束后触发，当搜索结果全部返回后触发回调，可直接在回调函数中获取完整搜索结果
• error 轮训发生错误时触发，可获取到错误信息

1.2 LoginManager

对 Pandora 平台登录相关 API 进行封装

使用方式

• pandora 登录

import { LoginManager, ELoginType } from '@qn-pandora/app-sdk'

const loginManager = new LoginManager(ELoginType.PANDORA)
loginManager.login({
  username: 'admin',
  password: 'admin'
})

• SSO 登录

import { LoginManager, ELoginType } from '@qn-pandora/app-sdk'

const loginManager = new LoginManager(ELoginType.SSO)
loginManager.login({
  token:
    'MjNGNDEweHdnQ2pOWVpuNFpINkkzUVJQZ0I0MnBab2RNTGt6UGcya0h0aUFpVVNGOjcxNzdmNjRhN2RmZDdjN2UxMGQ1MmRiNmQxYmZkNGU0NjJlNzU3NDdhNjU1NGMyNzJlMzMwODgyNzFiY2IzODMyZGJiZTA1YTM4OWI3NDIyOTgxODkwZGYzYjMxYWI2NTk2OTY0MmI1NDZjMjMxZDRiZjNlZGE3YWMyYjc4MzFj'
})

支持方法

方法返回都为 Promise

• login 登录
• logout 登出
• getUserInfo 获取用户信息

1.3 ReportManager

对 Pandora 平台报表管理相关 API 进行封装

使用方式

• 创建 ReportManager 传递参数

import { ReportManager } from '@qn-pandora/app-sdk'

const fetchAll = true // false by default
const pageSize = 20 // 10 by default

const reportManager = new ReportManager(fetchAll, pageSize)

• 列出所有报表

const lists = await reportManager.listReports()

• 通过 id 查询报表信息

const reportId = '0'
const info = await reportManager.getReport(reportId)

• 创建报表

const report = {
  name: 'testReport',
  time: {
    global: false,
    preset: 'AllTime'
  },
  spl: 'repo="tracing" | stats count() by host | where count > 10',
  description: 'description'
}

const res = await reportManager.createReport(report)

• 更新报表

const report = {
  name: 'testReport',
  time: {
    global: false,
    preset: 'AllTime'
  },
  spl: 'repo="tracing" | stats count() by host | where count > 10',
  description: 'updated description'
}

const res = await reportManager.updateReport(report)

• 删除报表

const reportId = '0'
const res = await reportManager.deleteReport(reportId)

参数介绍

• 创建 reportManager 时的参数

  • fetchAll: 是否拉取所有报表，默认值为 false，默认拉取 500 条，可通过设置 pageSize 改变拉取所有的数目
  • pageSize: 每页拉取数目，默认为 10

• 创建及更新 report 的参数

  • name: 报表名称
  • time: 报表时间范围
  • spl: 搜索条件
  • descrption: 描述

1.4 DatasetManager

对 Pandora 平台数据集管理相关 API 进行封装

使用方式

• 创建 DatasetManager 传递参数

import { DatasetManager } from '@qn-pandora/app-sdk'

const fetchAll = true // false by default
const pageSize = 20 // 10 by default

const datasetManager = new DatasetManager(fetchAll, pageSize)

• 列出所有数据集

const list = await datasetManager.listDatasets()

• 通过 id 查询数据集信息

const datasetId = '0'
const info = await getDataset(datasetId)

• 创建数据集

const baseDataset = {
  name: 'ds1',
  description: 'description',
  category: 'c1',
  transforms: [{ type: 'fields', fields: ['field1'] }],
  schemas: [{ name: 'name', type: 'long' }],
  dataSource: {
    query: 'query_string',
    time: {
      relative: 'relative',
      preset: 'preset',
      timeShift: 'timeShift',
      global: true
    }
  }
}

const res = await datasetManager.createDataset(baseDataset)

• 更新数据集

const baseDataset = {
  name: 'ds1',
  description: 'description',
  category: 'c1',
  transforms: [{ type: 'fields', fields: ['field1'] }],
  schemas: [{ name: 'name', type: 'long' }],
  dataSource: {
    query: 'query_string',
    time: {
      relative: 'relative',
      preset: 'preset',
      timeShift: 'timeShift',
      global: true
    }
  }
}

const res = await datasetManager.updateDataset(baseDataset)

• 删除数据集

const datasetId = '0'
const res = await deleteDataset(datasetId)

• 创建分类

const categories = ['c1', 'c2']
const res = await datasetManager.setCategories(categories)

• 展示分类

const list = await datasetManager.listCategory()

• 获取数据集 spl

const datasetId = '0'
const datasetSpl = await datasetManager.getDatasetSpl(datasetId)

• 获取转换 spl

const transforms = {
  type: 'fields',
  fields: ['f1', 'f2']
}

const transformSpl = await datasetManager.getTransformSpl(transforms)

参数介绍

• 创建 datasetManager 时的参数

  • fetchAll: 是否拉取所有报表，默认值为 false，默认拉取 500 条，可通过设置 pageSize 改变拉取所有的数目
  • pageSize: 每页拉取数目，默认为 10

• baseDataset

  • name: 数据集名字
  • description: 数据集描述
  • category: 数据集类型
  • transforms: 数据集中操作
  • schemas: 数据集字段
  • dataSource: 数据集数据源
    • query: 搜索条件
    • time: 时间

1.5 RepoManager

对 Pandora 平台仓库管理相关 API 进行封装

使用方式

• 创建 RepoManager 传递参数

import { RepoManager } from '@qn-pandora/app-sdk'

const fetchAll = true // false by default
const pageSize = 20 // 10 by default

const repoManager = new RepoManager(fetchAll, pageSize)

• 列出所有仓库

const list = await repoManager.listRepos()

• 通过仓库名称查询仓库信息

const repoName = 'repo'
const info = await repoManager.getRepo(repoName)

• 创建仓库

const repo = {
  name: 'repo',
  description: 'desciption',
  retention: -1
}

const res = await repoManager.createRepo(repo)

• 更新仓库

const repo = {
  name: 'repo',
  description: 'updated desciption',
  retention: -1
}

const res = await reportManager.updateReport(report)

• 删除仓库

const repoName = 'repo'
const res = await reportManager.deleteRepo(repoName)

参数介绍

• 创建 repoManager 时的参数

  • fetchAll: 是否拉取所有报表，默认值为 false，默认拉取 500 条，可通过设置 pageSize 改变拉取所有的数目
  • pageSize: 每页拉取数目，默认为 10

• repo

  • name: 仓库名称
  • description: 仓库描述
  • retention: 存储时限

1.6 SourceTypeManager

对 Pandora 平台来源管理相关 API 进行封装

使用方式

• 创建 SourceTypeManager 传递参数

import { SourceTypeManager } from '@qn-pandora/app-sdk'

const fetchAll = true // false by default
const pageSize = 20 // 10 by default

const sourceTypeManager = new SourceTypeManager(fetchAll, pageSize)

• 列出所有来源

const list = await sourceTypeManager.listSourceType()

• 通过来源名称查询来源信息

const sourceTypeName = 'sourceType'
const info = await sourceTypeManager.getSourceTypeByName(sourceTypeName)

• 创建来源类型

const sourceType = {
  name: 'sourceType',
  description: 'desciption',
  category: 'c1',
  line: {
    type: 'auto'
  },
  datetime: {
    type: 'now'
  }
  advance: {
    charset: 'utf-8',
    fieldDiscovery: false
  }
}

const res = await sourceTypeManager.createSourceType(sourceType)

• 删除来源类型

const sourceTypeName = 'sourceType'
const res = await sourceTypeManager.deleteSourceType(sourceTypeName)

参数介绍

• 创建 sourceTypeManager 时的参数

  • fetchAll: 是否拉取所有报表，默认值为 false，默认拉取 500 条，可通过设置 pageSize 改变拉取所有的数目
  • pageSize: 每页拉取数目，默认为 10

• sourceType

  • name: 来源类型名称
  • description: 来源类型描述
  • category: 来源分类
  • line: 换行规则
    • type: 换行规则(自动/单行/正则)
    • regex: 规则是正则时的正则式
  • datetime: 时间戳
    • type: 时间戳类型(自动/当前/自定义)
    • zoneOffset: 自定义时区
    • dateTimePrefix: 自定义时间戳前缀
    • dateTimeFormat: 自定义时间戳格式
    • maxDateTimeLength: 自定义时间戳长度上限
  • advance: 高级设置
    • charset: 编码方式
    • fieldDiscovery: 是否字段自动发现

1.7 PermissionManager

对 Pandora 平台应用权限管理相关 API 进行封装

使用方式

• 创建 PermissionManager

import { PermissionManager } from '@qn-pandora/app-sdk'

const appName = 'appName'
const permissionManager = new PermissionManager(appName)

• 获取某个功能的权限列表

const operations = await permissionManager.getFuncOperations('func1')

• 查看某个资源的授权情况

const rolePerms = await permissionManager.getKnowledgePerm('func1', '1')

• 修改知识权限

const rolePerms = [
  {
    role: 'role0',
    operation: 'list'
  },
  {
    role: 'role1',
    operation: 'edit'
  }
]
const res = await permissionManager.updateKnowledgePerm('func1', '1', rolePerms)

• 批量修改知识权限

const rolePerms = [
  {
    role: 'role0',
    operation: 'list'
  },
  {
    role: 'role1',
    operation: 'edit'
  }
]
const res = await permissionManager.bulkUpdateKnowledgePerm(
  'func1',
  ['0', '1'],
  rolePerms
)

2 Utils

2.1 bind

bind 装饰器用于为装饰的函数绑定 this 指针

使用方式

在类中装饰类的方法：

import { utils } from '@qn-pandora/app-sdk'

const { bind } = utils

export class SomeClass extends UpperClass {
  @bind
  someFunction() {
    this.setData(someData)
    // setData挂载在UpperClass上，this绑定在当前class上
  }
}

注意事项

bind 装饰过的函数在被重载时，不可在重载函数中调用父集的当前函数，会导致父集的当前函数 this 指针异常。

3 Components

自定义 Pandora 应用平台视图页面的组件。开发自定义组件不受前端开发框架限制，可以是 react, vue, Angular, jquery 等任意框架开发。唯一的限制在于：最终开发的自定义组件的 js bundle 需要被打包成 umd 模块。

Pandora 平台的视图页面引用自定义组件示例如下：

<custom-component src="<js_bundle_name>.js" />

3.1 BaseComponent

自定义 Pandora 应用平台的展示组件的基类，自定义的展示组件必须继承子该组件。

展示组件与输入组件的区别： 展示组件: 一般为接受属性，只做相应的展示，组件内部不做数据录入，即使做数据录入，也不会向组件外部传递。例如：Table, List, Tooltip, Avatar 等... 输入组件: 一般接受数据录入，且会把响应的信息传递到组件外部。例如：Input, Checkbox, DatePicker 等...

属性与方法说明

interface IComponentContext {
  appName: string // app的名称
}

abstract class BaseComponent {
  element: Element // 组件的挂载dom容器
  get staticPath(): string // app的静态资源的相对路径
  context: IComponentContext // app的上下文
  initialize(): void // 初始化操作
  resize(): void // 挂载dom容器大小变更时调用
  /**
   * 渲染组件的核心方法，自定义组件必须实现本方法，刻画了自定义组件的渲染逻辑
   * @param params 自定义组件接受的额外参数，
   *    例如：<custom-component src="<js_bundle_name>.js" width="100" height="50" />，
   *    此时params的值为：{ width: "100", height: "50" }
   */
  abstract render(params: any): void
  dispose(): void // 销毁组件时调用，常用来释放资源
  /**
   * 构造函数
   * @param element 组件的挂载dom容器
   * @param context app的上下文
   */
  constructor(element: Element, context: IComponentContext)
}

示例(React)

import React from 'react'
import ReactDOM from 'react-dom'
import { BaseComponent } from '@qn-pandora/app-sdk'
// 自定义React组件逻辑
import List from './List'

export default class extends BaseComponent {
  // 实现render方法，将List组件挂载到this.element上去
  render() {
    ReactDOM.render(<List />, this.element)
  }
}

3.2 BaseInput

自定义 Pandora 应用平台的输入组件的基类，自定义的输入组件必须继承子该组件。

BaseInput 是一种特殊的 BaseComponent，BaseInput 继承自 BaseComponent。

属性与方法说明

interface IBaseInputParams<T> {
  value: T
  onChange: (value: T) => void
  [key: string]: any
}

export default abstract class BaseInput<T> extends BaseComponent {
  /**
   * 渲染组件的核心方法，自定义输入组件必须实现本方法，刻画了自定义组件的渲染逻辑
   * @param params 在BaseComponent render方法params的基础增加value和onChange字段。
   *    value: 外部传递状态到自定义输入组件的属性。
   *    onChange: 输入组件将内部状态变化通知到外部的桥梁。调用该函数，即可将状态通知到外部。
   */
  abstract render(params: IBaseInputParams<T>): void
}

示例(React)

import React from 'react'
import ReactDOM from 'react-dom'
import { BaseInput } from '@qn-pandora/app-sdk'
import Search from './Search'

interface IParams {
  value: string
  onChange: (value: string) => void
}

export default class extends BaseInput<string> {
  render(params: IParams) {
    ReactDOM.render(
      <Search value={params.value} onChange={params.onChange} />,
      this.element
    )
  }
}

4 Module

4.1 renderPandoraModule

渲染潘多拉平台的模块（/页面）

使用方式

将潘多拉平台的数据集页面渲染进 id 为 moduleContainer 的 div 内

import { renderPandoraModule, EModuleType } from '@qn-pandora/app-sdk'
export default class extends BasicComponent {
  datasetContainerRef = React.createRef()

  componentDidMount() {
    renderPandoraModule(
      EModuleType.DatasetModule,
      this.datasetContainerRef.current,
      {
        basePath: 'http://pandora-express-rc.qiniu.io/apps/application/demoapp'
      }
    )
  }

  render() {
    return <div ref={this.datasetContainerRef} id="moduleContainer" />
  }
}

参数介绍

renderPandoraModule(<module name>, <dom> [, options])

• module name （类型：string） 要渲染的模块（/页面）的名称。import { EModuleType } from '@qn-pandora/app-sdk'中的EModuleType包含了所有模块（/页面）的名称 模块名 | 说明 -- | -- EModuleType.DatasetModule | 渲染 Pandora 平台上面的数据集页面 EModuleType.SearchModule | 渲染 Pandora 平台上面的搜索分析页面 EModuleType.DashboardModule | 渲染 Pandora 平台上面的仪表盘管理页面 EModuleType.TaskExportModule | 渲染 Pandora 平台上面的仪表盘定时任务页面 EModuleType.MonitorManageModule | 渲染 Pandora 平台上面的监听采集页面 EModuleType.RepoModule | 渲染 Pandora 平台上面的仓库管理页面 EModuleType.SourceTypeModule | 渲染 Pandora 平台上面的来源管理页面 EModuleType.FieldModule | 渲染 Pandora 平台上面的解析管理页面 EModuleType.ReportModule | 渲染 Pandora 平台上面的报表管理页面 EModuleType.AlertRulesModule | 渲染 Pandora 平台上面的告警规则页面 EModuleType.AlertEventsModule | 渲染 Pandora 平台上面的告警事件页面
• dom (类型：Element) 将模块（/页面）渲染到该 dom 里面
• options （类型：Object） 参数 | 类型 | 说明 -- | -- | -- options.basePath | string | 在 Pandora 平台上基于该 url 切换路由