# API 列表

# 总览

• 所有方法均返回 fetch 请求默认的 Promise 对象
• 如果源返回值为空，方法会返回空对象
• 可以通过 response._header 获取返回对象的 header：

  log.projects.list()
    .then(res => console.log(res._header))
  

  1
  2
  

Q:为什么没有返回类型？

A: 因为阿里云日志服务的返回数据并不固定 (视查询结果)，同时头也可以改变返回类型，而且很多操作只返回头信息。 所以大多数情况下还需要你参考 API 源的文档返回值并且尝试一次。

# 项目 projects

# 查看项目列表

查询并返回项目列表。API 源

方法：log.projects.list(offset?: number, size?: number)

参数：

# 获取单个项目

根据名称查询单个项目。API 源

方法：log.projects.findOne(projectName: string)

参数：

# 创建项目

创建项目。API 源

方法：log.projects.create(projectName: string, description: string)

参数：

# 更新项目

更新项目详情。API 源

方法：log.projects.updateOne(projectName: string, description: string)

参数：

# 删除项目

删除一个项目。API 源

方法：log.projects.destroyOne(projectName: string)

参数：

# 日志库 logstores

# 获取日志库列表

获取日志库列表，可以按名称查询。API 源

方法：

log.logstores.list(
  projectName: string,
  logstoreName?: string,
  offset?: number,
  size?: number,
) 

参数：

# 获取单个日志库

查询单个日志库。API 源

方法：log.logstores.findOne(projectName: string, logstoreName: string)

参数：

# 更新日志库

修改日志库信息。API 源

方法：

log.logstores.updateOne(
  projectName: string,
  logstoreName: string, 
  entity: LogstoreUpdateOption,
)

参数：

entity：

interface LogstoreUpdateOption {
  ttl: number,
  shardCount: number,
  enable_tracking?: boolean,
  autoSplit?: boolean,
  maxSplitShard?: number,
}

entity 参数说明:

# 创建日志库

创建单个日志库。API 源

方法：

log.logstores.create(
  projectName: string,
  logstoreName: string,
  entity: LogstoreUpdateOption,
)

参数：

# 删除日志库

删除单个日志库。API 源

方法：log.logstores.destroyOne(projectName: string, logstoreName: string)

参数：

# 添加日志

向单个日志库写入日志。API 源

方法：

log.logstores.appendLog(
  projectName: string,
  logstoreName: string,
  logEntity: LogGroup,
)

参数：

logEntity:

logs: ProtoEntity | ProtoEntity[],
topic?: string,
source?: string,
reserved?: string,

logEntity 参数说明:

使用示例，向一个日志库中写入 2 个日志:

const { AliyunLog } = require('aliyun-logs')
const log = new AliyunLog({ ... })

// 创建一个日志实体，包含两条
const mylogs = new AliyunLog.ProtoEntity(
  [{ key: 'user001', value: 'ok' }, { key: 'user002', value: 'system has an error' }]
)
  
// 提交日志实体
log.logstores.appendLog('use-deploy', 'test2', { logs: mylogs })
.catch(err => console.log(err))

# 根据游标拉取日志

根据游标拉取压缩日志。API 源

方法：log.logstores.pullLogsByCursor(projectName: string, logstoreName: string, pullOption: LogsPullOption)

参数：

pullOption:

interface LogsPullOption {
  shardid: string,
  cursor: string,
  count: number,
  encoding?: 'lz4' | 'deflate' | 'gzip'
}

pullOption 参数说明:

# 查询日志

查询日志。API 源

方法：log.logstores.queryLogs(projectName: string, logstoreName: string, query: LogQuery)

参数：

query:

interface LogQuery {
  from: number,
  to: number,
  topic?: string,
  query?: string,
  line?: number,
  offset?: number,
  reverse?: boolean,
}

query 参数说明:

# 查询日志分布

查询日志的分布情况。API 源

方法：log.logstores.queryHistograms(projectName: string, logstoreName: string, query: HistogramsQuery)

参数：

query:

interface HistogramsQuery {
  from: number,
  to: number,
  topic?: string,
  query?: string,
}

query 参数说明:

# 分区 shards

# 查询分区列表

查询日志库中的所有分区列表。API 源

方法：log.shards.list(projectName: string, logstoreName: string)

参数：

# 分裂 Shard

分裂一个可写的 Shard。API 源

方法：log.shards.split(projectName: string, logstoreName: string, splitOption: ShardsSplitOption)

参数：

splitOption:

interface ShardsSplitOption {
  shardid: number,
  splitkey: string,
}

splitOption 参数说明:

# 合并 Shard

合并两个相邻且可写的 Shard。提供一个 shardid，自动寻找下一个 Shard 合并。API 源

方法：log.shards.merge(projectName: string, logstoreName: string, shardid: number)

参数：

# 获取游标

根据时间获取游标。API 源

方法：log.shards.findCursor(projectName: string, logstoreName: string, cursorOption: ShardsCursorOption)

参数：

cursorOption:

interface ShardsCursorOption {
  shardid: string,
  from: 'begin' | 'end' | string,
}

cursorOption 参数说明:

# 获取游标的时间

根据游标查询服务端时间。API 源

方法:

log.shards.findTimeByCursor(
  projectName: string,
  logstoreName: string,
  timeOfCursorOption: ShardsTimeOfCursorOption,
)  

参数：

timeOfCursorOption:

interface ShardsTimeOfCursorOption {
  shardid: string,
  cursor: string,
}

timeOfCursorOption 参数说明:

# 投递任务 shippers

# 获取投递任务状态

查询投递任务状态。API 源

方法: log.shippers.findTasks(projectName: string, logstoreName: string, taskQuery: TaskQuery)

参数：

taskQuery:

interface TaskQuery {
  shipperName: string,
  from: number,
  to: number,
  status?: string,
  offset?: number,
  size?: number,
}

taskQuery 参数说明:

# 重试任务

重新执行失败的日志投递任务。API 源

方法:

log.shippers.retryTasks(
  projectName: string,
  logstoreName: string,
  retryQuery: RetryTaskQuery,
)

参数：

retryQuery:

interface RetryTaskQuery {
  shipperName: string,
  taskids: string[],
}

RetryTaskQuery 参数说明:

# 索引 indexs

# 创建索引

对日志库创建一个索引。API 源

创建索引的具体参数文档请务必阅读源 API，此外，索引只对创建以后录入的日志生效。

方法:

log.indexs.create(
  projectName: string,
  logstoreName: string,
  indexEntity: IndexsCreateOption,
)

参数：

indexEntity:

interface IndexsCreateOption {
  keys: { [key: string]: FieldIndexValue },
  line: LineIndex,
}

FieldIndexValue:

FieldIndexValue {
  type: string,
  alias?: string,
  chn?: boolean,
  token?: string[],
  caseSensitive?: boolean,
  doc_value?: boolean,
}

LineIndex:

interface LineIndex {
  token: string[],
  caseSensitive?: boolean,
  chn?: boolean,
  include_keys?: string[],
  exclude_keys?: string[],
}

# 更新索引

更新索引。API 源

方法:

log.indexs.update(
  projectName: string,
  logstoreName: string,
  indexEntity: IndexsCreateOption,
)

参数：

# 删除索引

删除日志库的索引。API 源

方法: log.indexs.destroy(projectName: string, logstoreName: string)

参数：

# 获取索引

获取指定日志库的所有。API 源

方法: log.indexs.findAll(projectName: string, logstoreName: string)

参数：