对象存储BOS

    SelectObject

    接口描述

    此接口用于向Bucket中指定object执行SQL语句,选取出指定内容返回。请求者必须对选取的object具有read权限。在SelectObject前需要确保对应的Bucket和Object已经存在,详细信息参考 SelectObject 开发者文档。

    请求(Request)

    • 请求语法

      POST /<ObjectKey>?select&type=json/csv HTTP/1.1
      Host: <BucketName>.bj.bcebos.com
      Date: <Date>
      Authorization: <Authorization_String>
      Content-Type: application/json; charset=utf-8
      Content-Length: <Content_Length>
      {
          "selectRequest": {
              "expression": "Base64Encode(Select * from BosObject)",
              "expressionType": "SQL",
              "inputSerialization": {
                  "compressionType": "GZIP/NONE",
                  // JSON or CSV
              },
              "outputSerialization": {
                  // JSON or CSV
              },
              "requestProgress": {
                  "enabled": false/true
              }
          }
      } 
    • 请求参数

      名词 类型 描述 是否必须
      type string select的目标object类型,目前支持json/csv
    • 请求主体

      JSON文件

      名称 是否必须 类型 描述
      selectRequest - json body根节点
      + expression string 经过base64编码的sql语句
      + expressionType string 查询语句语法类型,只支持"SQL"
      + inputSerialization - 输入流节点,其子节点描述查询的object格式信息
      ++compressionType string 指定查询的object是否压缩,可选值为"NONE"或"GZIP"
      ++ json - json节点,其子节点描述json文件相关信息
      +++ type string json type,查询的json object格式,可选值为"DOCUMENT"或"LINES"
      + outputSerialization - 输出流节点,其子节点描述查询结果返回格式信息
      ++ json json节点,其子节点描述返回的json数据相关信息
      +++ recordDelimiter string 指定换行符,以Base64编码。默认值为\n(可选)
      + requestProgress - select进度信息节点,其子节点描述select操作的执行进度,3s定时返回给用户
      ++ enabled boolean 描述是否需要定时返回进度信息,可选值为false/true;如果数据筛选耗时久可能导致504超时,设置其为true可以维持http连接

      CSV文件

      名称 是否必须 类型 描述
      selectRequest - json body根节点
      + expression string 经过base64编码的sql语句
      + expressionType string 查询语句语法类型,只支持"SQL"
      + inputSerialization - 输入流节点,其子节点描述查询的object格式信息
      ++ compressionType string 指定查询的object是否压缩,可选值为"NONE"或"GZIP"
      ++ csv - csv节点,其子节点描述csv文件相关信息
      +++ fileHeaderInfo string 可选值NONE/IGNORE/USE,指定CSV文件首行头信息,默认值NONE代表无header信息,IGNORE代表有header信息但是忽略,NONE和IGNORE意味着只能用列序号取出某一列;USE表示使用header信息,只能用header名取出某一列
      +++ recordDelimiter string 指定csv文件换行符,以Base64编码,默认值为\n(可选),最多为2个字符,例如\r\n
      +++ fieldDelimiter string 指定csv文件列分隔符,以Base64编码,默认值为,(可选),最多为1个字符,例如;
      +++ quoteCharacter string 指定csv文件引号字符,以Base64编码,在CSV中引号内的换行符,列分隔符将被视作普通字符;默认值为双引号"(可选),最多为1个字符,例如单引号'
      +++ commentCharacter string 指定csv文件注释符,以Base64编码,一行以注释符开头则表示改行可以忽略;默认值为#(可选),最多为2个字符,例如//
      + outputSerialization - 输出流节点,其子节点描述查询结果返回格式信息
      ++ outputHeader boolean 在返回结果开头输出CSV头信息,默认false; 需要fileHeaderInfo字段取值USE,该值为true会在返回结果的每一个Records message第一行加上对应的csv header名称;可选值为false/true
      ++ csv - csv节点,其子节点描述返回的csv数据相关信息
      +++ quoteFields string 可选值ALWAYS/ASNEEDED,指定返回的csv数据每个字段是否使用""包围; ASNEEDED表示返回文件中原始数据,ALWAYS表示总是用""包围field; 默认是ASNEEDED
      +++ recordDelimiter string 指定返回的csv数据的换行符,以Base64编码。默认值为\n(可选),最多为2个字符,例如\r\n
      +++ fieldDelimiter string 指定返回的csv数据的列分隔符,以Base64编码。默认值为,(可选),最多为1个字符,例如;
      +++ quoteCharacter string 指定返回的csv数据的引号字符,以Base64编码,在CSV中引号内的换行符,列分隔符将被视作普通字符;默认值为双引号"(可选),最多为1个字符,例如单引号'
      + requestProgress - select进度信息节点,其子节点描述select操作的执行进度,3s定时返回给用户
      ++ enabled boolean 描述是否需要定时返回进度信息,可选值为false/true;如果数据筛选耗时久可能导致504超时,设置其为true可以维持http连接
    • 请求头域

      无特殊头域

    响应(Response)

    • 响应头域

      名称 类型 描述
      Transfer-Encoding String 值为chunked,表示返回内容以http1.1 chunked编码方式分块返回
    • 响应参数

    • 响应主体

      SelectObject接口响应以chunk形式返回,包括Records message,Continuation message,End message三种类型:

      message 格式 描述
      Records message prelude(8 byte) + n * (header_key_len(1 byte) + header_key + header_val_len(2 byte) + header_val) + payload + crc32(4 byte) 包含Select请求返回的数据,可以是一行,也可以是多行记录
      Continuation message 同上,固定格式,只是payload内容不一样 每3秒定时给client返回当前select进展(扫描字节数/返回字节数)以及维持http连接
      End message 同上,固定格式,payload内容为空 标志着该次select请求的结束,headers字段包括error-code,error-message,message-type,bytes-scanned等信息

      message具体格式详细说明:

      select-msg.png

      1. prelude部分一共8个byte,前4byte表示message总长度,后4byte表示headers部分总长度,chunk总长度(prelude前4byte存储的值) - header总长度 - 8byte的prelude - 4byte的crc32 = payload部分数据总长度;crc32表示整个message的纠删码
      2. headers包含以下自定义<key,value>:“message-type”: {"Records", "Cont", "End"} ; "error-code": 具体错误码 ; "error-message": "详细错误信息"
      3. Payload表示返回的真实数据,可以是任意格式;其中Continuation message的Payload里边包括BytesScanned和BytesReturned两个字段表示的select进度信息

    示例

    • CSV文件请求示例

      POST /object?select&type=csv HTTP/1.1
      Host: bucket.bj.bcebos.com
      Date: Thu, 15 May 2017 00:17:23 GMT
      Authorization: <Authorization_String>
      Content-Type: application/json; charset=utf-8
      Content-Length: 512
      {
          "selectRequest": {
              "expression": "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
              "expressionType": "SQL",
              "inputSerialization": {
                  "compressionType": "NONE",
                  "csv": {
                      "fileHeaderInfo": "NONE",
                      "recordDelimiter": "Cg==",
                      "fieldDelimiter": "LA==",
                      "quoteCharacter": "Ig==",
                      "commentCharacter": "Iw=="
                  }
              },
              "outputSerialization": {
                  "outputHeader": FALSE,
                  "csv": {
                      "quoteFields": "ALWAYS",
                      "recordDelimiter": "Cg==",
                      "fieldDelimiter": "LA==",
                      "quoteCharacter": "Ig=="
                  }
              },
              "requestProgress": {
                  "enabled": false
              }
          }
      }
    • CSV文件响应示例

      HTTP/1.1 200 OK
      x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
      Date: Wed, 06 Apr 2016 06:34:40 GMT
      ETag: "1b2cf535f27731c974343645a3985328"
      Transfer-Encoding: chunked
      Connection: close
      Server: BceBos
      ----- Body ------
      <Records message>
      ……
      <Continuation Message>
      ……
      <Records message>
      <Continuation Message>
      <End message>
    • JSON文件请求示例

      POST /object?select&type=json HTTP/1.1
      Host: bucket.bj.bcebos.com
      Date: Thu, 15 May 2017 00:17:23 GMT
      Authorization: <Authorization_String>
      Content-Type: application/json; charset=utf-8
      Content-Length: 512
      {
          "selectRequest": {
              "expression": "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
              "expressionType": "SQL",
              "inputSerialization": {
                  "compressionType": "NONE",
                  "json": {
                      "type": "DOCUMENT"
                  }
              },
              "outputSerialization": {
                  "json": {
                      "recordDelimiter": "Cg=="
                  }
              },
              "requestProgress": {
                  "enabled": false
              }
          }
      }
    • JSON文件响应示例

      HTTP/1.1 200 OK
      x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
      Date: Wed, 06 Apr 2016 06:34:40 GMT
      ETag: "1b2cf535f27731c974343645a3985328"
      Transfer-Encoding: chunked
      Connection: close
      Server: BceBos
      ----- Body ------
      <Records message>
      ……
      <Continuation Message>
      ……
      <Records message>
      <Continuation Message>
      <End message>  
    上一篇
    权限控制
    下一篇
    软链接