GetCursor接口用于根据时间获取对应的游标(cursor)。

通过游标(cursor)可以获取特定日志对应的位置。关于cursor与Project、Logstore、Shard的关系如下图所示。 游标
  • Project下有多个Logstore。
  • 每个Logstore会有多个Shard。
  • 通过cursor可以获得特定日志对应的位置。

请求语法

GetCursor接口的请求语法如下所示。
GET /logstores/ay42/shards/2?type=cursor&from=1402341900 HTTP/1.1
Authorization: <AuthorizationString>
Date: <GMT Date>
Host: <Project Endpoint>
x-log-apiversion: 0.6.0

请求参数

  • 请求头

    GetCursor接口无特有请求头。关于Log Service API的公共请求头,请参见公共请求头

  • 请求参数
    参数名称 类型 是否必须 描述
    shard string Shard名称。
    type string 此处为cursor。
    from string 时间点(Unix时间戳)或者字符串 beginend
    通过from可以在Shard中定位生命周期内的日志,假设Logstore的生命周期为[begin_time,end_time),from=from_time,那么:
    • from_time ≤ begin_time or from_time = "begin"时:返回时间点为begin_time对应的cursor位置。
    • from_time ≥ end_time or from_time = "end"时:返回当前时间点下一条将被写入的cursor位置(当前该 cursor 位置上无数据)。
    • from_time > begin_time and from_time < end_time时:返回第一个服务端接收时间大于等于from_time的数据包对应的 cursor。
    说明 Logstore生命周期由属性中TTL字段指定。例如,当前时间为2018-11-11 09:00:00,TTL=5。则每个Shard中可以消费的数据时间段为 [2018-11-05 09:00:00,2018-11-11 09:00:00),这里的时间指的是Server端时间。

响应参数

  • 响应头

    GetCursor接口无特有响应头。关于Log Service API的公共响应头,请参见公共响应头

  • 响应元素
    {
        "cursor": "MTQ0NzI5OTYwNjg5NjYzMjM1Ng=="
    }

错误码

GetCursor接口除了返回Log Service API的通用错误码,还可能返回如下特有错误码:
HTTP 状态码 ErrorCode ErrorMessage
404 LogStoreNotExist Logstore {Name} does not exist
400 ParameterInvalid Parameter From is not valid
400 ShardNotExist Shard {ShardID} does not exist
500 InternalServerError Specified Server Error Message
400 LogStoreWithoutShard the logstore has no shard

示例

  • 请求示例
    GET /logstores/sls-test-logstore/shards/0?type=cursor&from=begin
    Header:
    {
        "Content-Length": 0, 
        "x-log-signaturemethod": "hmac-sha1", 
        "x-log-bodyrawsize": 0, 
        "User-Agent": "log-python-sdk-v-0.6.0", 
        "Host": "ali-test-project.cn-hangzhou-devcommon-intranet.sls.aliyuncs.com", 
        "Date": "Thu, 12 Nov 2015 03:56:57 GMT", 
        "x-log-apiversion": "0.6.0", 
        "Content-Type": "application/json", 
        "Authorization": "LOG <yourAccessKeyId>:<yourSignature>"
    }
  • 响应示例
    Header:
    {
        "content-length": "41", 
        "server": "nginx/1.6.1", 
        "connection": "close", 
        "date": "Thu, 12 Nov 2015 03:56:57 GMT", 
        "content-type": "application/json", 
        "x-log-requestid": "56440E0999248C070600C6AA"
    }
    Body:
    {
        "cursor": "MTQ0NzI5OTYwNjg5NjYzMjM1Ng=="
    }