API文档
############

签名方法
===========

.. http:get:: http://g.sae.sina.com.cn/(string:uri)

   访问sinacloud的API接口。

   :reqheader x-sae-accesskey: 应用的Accesskey
   :reqheader x-sae-timestamp: unix时间戳
   :reqheader Authorization: 本次请求的认证签名。

   :statuscode 200: 无错误
   :statuscode 403: 认证失败
   :statuscode 404: 接口不存在，etc
   :statuscode 405: 不支持的http method

   **Example request**:

   .. sourcecode:: http

      GET /log/http/2015-06-05/1-access.log HTTP/1.1
      Host: g.sae.sina.com.cn
      Accept: text/plain
      x-sae-accesskey: 0xdeadbeef
      x-sae-timestamp: 1433495016
      Authorization: SAEV1_HMAC_SHA256 VQdy0s/D4aEn6QXAexr0onGmz+QObDwkWcZCCKcxMws=

将所有x-sae-开头的http header(小写)按key排序后用冒号(:)连接key和value，放在method、uri(包含query string，不要转义)后以换行符分隔拼接为签名原文字符串，再以Secretkey为密钥用hmac sha256计算哈希值（二进制），再经base64编码，前面加上"SAEV1_HMAC_SHA256 "，得到本次请求的认证签名，即Authorization字段

.. code-block:: php

   <?php
    $method = 'GET';
    $AccessKey = '******';
    $Secretkey = '******';
    $uri = '/log/http/2021-05-07/3-access.log?head/0/1';

    $a = array();
    $a[] = $method;
    $a[] = $uri;
    $timeline = time();
    $b = array('x-sae-accesskey' => $AccessKey, 'x-sae-timestamp' => $timeline);
    ksort($b);
    foreach ($b as $key => $value) {
        $a[] = sprintf("%s:%s", $key, $value);
    }
    $str = implode("\n", $a);
    $s = hash_hmac('sha256', $str, $Secretkey, true);
    $b64_s = base64_encode($s);

.. note::
    timestamp与服务器时间相差不得超过120秒。

接口列表
=========

实时日志
-------------

.. http:get:: /log/(string:service)/(string:date)/(string:ident).log?(string:fop)

   获取应用的日志

   本接口支持Range访问返回部分内容，支持通过fop来在服务端直接处理日志内容。

   :statuscode 200: 无错误
   :statuscode 206: 部分文件内容（Range访问时）
   :statuscode 400: 客户端参数错误
   :statuscode 500: 服务端错误

日志接口支持通过fop在服务端处理日志（grep，uniq，tail等）并直接返回处理后的结果。处理指令类似于linux shell命令。 ::

    [GET] /app/log?fop1|fop2|fop3|fopN

处理指令和指令之间通过竖线（｜）来隔开，称之为管道，上一条指令的输出是下一条指令的输入。命令名后的第一个字符为命令与参数的分隔符，如"grep/login.php"的分隔符为"/"。

fop操作指令列表：

- head/OFFSET/LIMIT：获取日志开头行，OFFSET是起始行号，LIMIT是获取的最大行数。
- tail/OFFSET/LIMIT：获取日志末尾行，OFFSET是起始行号（最后一行行号为1），LIMIT是获取的最大行数。
- grep/PATTERN/PLAIN：关键字匹配，PATTERN为关键字，支持部分正则，遵循lua正则语法，如 `yq2[^6]+$` ，指定PLAIN为plain时禁用正则。
- fields/SEPERATOR/COL1/COL2/...：取部分列。SEPERATOR指定列与列的分隔符，COL1等是要取的列的序号，从1开始。
- uniq/SEPERATOR/COL1/COL2/...：去除相邻重复的行，可以指定通过哪些列来排重，若无参数则比较整行，参数同fields指令。

service及ident列表:

==========  ===============================================
service     ident
==========  ===============================================
http        access、error、alert、debug、warning、notice
taskqueue   error
cron        error
mail        access、error
rdc         error、warning
storage     access
push        access
fetchurl    access
caas        stdout、stderr
afw         block
==========  ===============================================

.. note:: http的日志需要在ident前面加上版本号，比如版本1的access日志为1-access.log。

日志下载
-------------

.. http:get:: /log/(string:service)/(string:date)/(string:ident).tar.gz?(string:token)

   获取日志下载路径、下载日志，格式与实时日志雷同

   下载时支持Range访问返回部分内容

   路径右侧参数不全时列出本级路径下的资源，如请求路径/log/http/2015-08-03:2015-08-05/返回应用3日至5日的http日志备份文件信息，使用其中的uri无需签名即可下载文件，uri有效期5分钟。
   需要预先访问/log/(string:service)/(string:date)/(string:ident)如/log/http/2015-08-03:2015-08-05/1-access获取日志的备份文件列表，再根据列表中提供的链接下载，uri有效期5分钟。其中结束日期不能包含当天，起始日期必须在30天以内。

   :statuscode 200: 无错误
   :statuscode 206: 部分文件内容（Range访问时）
   :statuscode 400: 客户端参数错误
   :statuscode 403: 认证错误
   :statuscode 500: 服务端错误

新浪财经实时报价
-------------------

.. http:get:: /financehq/list=(string:stockcode)

   从新浪财经获取股票的实时报价

   输出为csv格式，stockcode可以是半角逗号分隔的多个股票代码

* 沪深股:

   .. http:get:: /financehq/list=sh000001,sz000001

   **Example response**:

   .. sourcecode:: text

      上证指数,2897.2731,2927.1590,2833.0707,2911.1582,2832.5072,0,0,169255434,198547765495,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2016-06-13,15:01:55,00
      平安银行,8.570,8.570,8.580,8.610,8.540,8.570,8.580,31517300,270236697.970,85260,8.570,348828,8.560,75620,8.550,490667,8.540,405600,8.530,19237,8.580,603684,8.590,960868,8.600,879238,8.610,724880,8.620,2016-06-17,15:05:03,00


   ========  ============
   字段序号    内容
   ========  ============
   1         证券简称
   2         今日开盘价
   3         昨日收盘价
   4         最近成交价
   5         最高成交价
   6         最低成交价
   7         买入价
   8         卖出价
   9         成交数量
   10        成交金额
   11        买数量一
   12        买价位一
   13        买数量二
   14        买价位二
   15        买数量三
   16        买价位三
   17        买数量四
   18        买价位四
   19        买数量五
   20        买价位五
   21        卖数量一
   22        卖价位一
   23        卖数量二
   24        卖价位二
   25        卖数量三
   26        卖价位三
   27        卖数量四
   28        卖价位四
   29        卖数量五
   30        卖价位五
   31        行情日期
   32        行情时间
   33        停牌状态
   ========  ============

   停牌状态：

   ======  ============
   状态码   状态
   ======  ============
   00      正常
   01      停牌一小时
   02      停牌一天
   03      连续停牌
   04      盘中停牌
   05      停牌半天
   07      暂停
   -1      无该记录
   -2      未上市
   -3      退市
   ======  ============

.. note::
   指数成交量的单位是手，个股是股，需要特别注意！

:statuscode 200: 无错误
:statuscode 400: 客户端参数错误
:statuscode 403: 认证错误
:statuscode 500: 服务端错误

.. include:: ./common/segment.rst

.. include:: ./common/channel.rst