python sdk接口说明

简介

   本篇章介绍python客户端使用sdk接入cppcloud的接口api使用，主要导入cppcloud包使用里面的函数，在此讲解函数的功能作用，sdk底层是与cppcloud的tcp通信，通信的协议在[服务端]通信协议介绍TCP里有定义，需了解可以点击链接进入阅读。 有如下分类。

准备工作

   sdk要求python3的运行环境（py2不再维护），快速安装使用pip install cppcloud，或者直接copy python_sdk/cppcloud目录到自己的项目里，源代码使用时先导入包import cppcloud

sdk流程部分

包初始化

函数原型

'''
sdk核心初始化，最开始调用的函数， 成功时返回CloudApp实例，失败时None
# kvarg 可选key: svrid, svrname, tag, desc, aliasname, clitype
#                reqTimeOutSec(请求的超时时间); 
#       可以定义其他的key，只不过cppcloud_serv不会用到。
'''
def init(serv_host, serv_port, **kvarg)

功能说明

使用sdk首个要调用函数，进行sdk的一些初始化工作，其间会尝试连接后台cppcloud_serv，并上报自己身份信息，此函数返回成功才可以进行后面其他API调用。成功时返回一个CloudApp对象（定义在cloudapp.py、tcpclient.py、tcpcli.py）

参数说明

参数名 说明
serv_host 要连接的cppcloud_serv的地址主机部分
serv_port 要连接的cppcloud_serv的端口，int类型
kvarg 可选客户端属性: svrid（当前应用的ID，整数值，区分不同客户应用，可以传0代表让serv帮自动分配）, svrname（当前应用名称，后台要区分不同客户接入，应取一个和自身功能相关的名字）, tag（为当前应用指定一个标签值。 当要在元配置_meta.json利用指定不同客户设置不同的主配置(mconf)或设定客户所属机房时用）, desc（描述）, aliasname（别名）, clitype（客户类别py应用取200~299间值）, reqTimeOutSec(请求的超时时间)
返回值 成功返回CloudApp对像，失败返回None

结束退出

函数原型

'程序退出时调用， 与init()成对出现'
def uninit()

分布式配置

加载配置指定文件

功能说明

指定要加载哪些配置文件，把之后运行过程需要访问的配置文件名进行加载；只要先加载，后面的查询接口Query才能使用。~~注意主配置文件默认会自动加载，无需在此加载，当然重复加载也可以~~。

函数原型

# 获取分布式配置的查询实例，传入后续需要用到的配置文件名列表，失败时返回None
def confObject(*listFileName)

参数说明

参数名 说明
listFileName 文件名字符串数组，譬如confObject('app1-dev.json','dev2.json')
返回值 失败返回None，成功返回CloudConf类的对象，接下来讲解下此对象方法

CloudConf类

  • loadConfFile(self, *listfname)

    • 功能：分布式配置初始化，sdk包里cppcloud.confObject()时会自动调用
    • 参数：*listfname 配置文件名列表 *
    • 返回：初始化时列表中给出的文件有几个获取失败。

  • query(self, qkey, defval = None)

    • 功能：查询操作
    • 参数：qkey格式："filename/key1/key2"，查询主配置可以省略filename
    • 返回：json配置里面的值，类型可能是dict,list,str,int,bool之一

  • getMTime(self, fname)

    • 功能：获取某个配置文件的最后修改时间
    • 参数：fname，配置的文件名
    • 返回：整数类型的时间戳（秒），不存在的配置返回0

服务提供

   需要进行对外提供服务，则先调用providerObject()，内部其实就是导入两个模块，也可以直接导入不调用providerObject()。 实现某一服务提供的基本做法是定义一个类继承自sdk中定义好的类（下面说明各类），重写某些方法即可。

类关系图

prvd_class.png

TCP服务提供者

   定义一个tcp服务提供者类继承于TcpProviderBase，在类实现中定义类变量（可选regname，host，port，url，weight，desc，prvdid）和实例方法def onRequest(self)用于处理请求业务。

示例:
``` python class MyPrvdTcp(TcpProviderBase): #regname = 'TestPrvd' # 不设置，默认用cloudapp.svrname #host = '192.168.1.101' # 不设置，默认自动检测 port = 3744 # 不设置，默认用随机端口 url = 'tcp://www.cppcloud.cn:' + str(port) #desc= '描述这是做什么的服务' #weight= #prvdid=

# 默认消息消息处理方法()
# overload
def onRequest(self):
    # 输入信息都放在self的成员里面
    #  self.reqcmdid 请求的命令字ID，这里是CMD_TCP_SVR_REQ
    #  self.reqseqid 请求的编号，是为区分请求包，一般是自增数
    #  self.reqbody  请求包体字符串
    print(("hello ", self.reqcmdid, self.reqseqid, self.reqbody))
    respsor = self.response_async()
    self.seqid = 0
    self.reqcmdid = 0
    respsor("hi, input=" + self.reqbody)

```

成员和方法

名称 类型 说明
request socket BaseRequestHandler成员，TCP socket连接
client_address BaseRequestHandler成员，tuple 客户地址
reqbody str 请求包体字符串
reqcmdid int 命令字，默认是CMD_TCP_SVR_REQ；当使用BindCmdHandle()方法可绑定其他自字义命令字
reqseqid int 请求的编号，是为区分请求包，一般是自增数
response function 同步响应方法，第1个参数是回应包体，第2个参数是是否错误（用于统计）
response_async function 异步响应，返回的闭包可以在以某个时间某个线程中调用，给予响应；

Http服务提供者

   定义http服务提供者更简单，只需自己的类继承ProviderBase，并定义好类属性变量即可，当然这是没有包括http具体业务部分的，具体业务还得自己选择flask，django等适合自己的框架实现。

示例:
python class HttpProvider(ProviderBase): scheme = 'http' port = 3389 http_path = '/proj' url = 'http://www.cppcloud.cn:' + str(port) + http_path

服务消费

初始化

   获取服务消费者操作对象，此对象现已提供tcp和http方式的消费调用，初始时只需传入所要消费的服务名列表，cloudapp核心会维护调用者状态 成功时返回的是CloudInvoker对象，方法可参考cloudinvoker.py

import cppcloud
inker = cppcloud.invokerObject('TestPrvd1', 'TestPrvd2')
if not inker:
    raise ErrException(xxx)

CloudInvoker类实例方法

名称 说明
init 初始化将所有需要消费的服务名传进来，成功返回0， 失败返回服务发现时失败服务个数，包里会被cppcloud.invokerObject调用
setRefreshTimeout 设置服务列表的刷新时间 （秒）
setInvokeTimeout 设置发起调用时的超时时间（秒）
call 最重要的实例方法，发起调用就是用call。第1个参数是服务名称，后面是不定项参数，不同协议这里不一样；返回(callresult, response, errCallBack)，分别对应（结果0＝成功，响应报文体内容，反馈闭包回调）

call()的不定项参数：

取决于调用的协议，TCP下层对应于TcpInvokerCli.call()，Http下层对应于HttpInvokerCli.call() - TCP 原型call(self, reqmsg, cmdid = CMD_TCP_SVR_REQ, todict = False) reqmsg：请求消息体；
cmdid：缺省CMD_TCP_SVR_REQ，自定义消息时自行指定；
todict：返回值的response（即tuple的第2个值）是否转化成dict。

  • Http

    原型call(self, method='GET', **kwargs)
    method：可以是'GET' 'POST' 'DELETE' 'PUT'等 kwargs: 可选[params, timeout, method, headers, cookies, files]是对应于requests包里的request函数的关键字参数。 如下引用requests原码一段注释。

    code :param method: method for the new :class:`Request` object. :param url: URL for the new :class:`Request` object. :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`. :param data: (optional) Dictionary or list of tuples ``[(key, value)]`` (will be form-encoded), bytes, or file-like object to send in the body of the :class:`Request`. :param json: (optional) json data to send in the body of the :class:`Request`. :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`. :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`. :param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``) for multipart encoding upload. ``file-tuple`` can be a 2-tuple ``('filename', fileobj)``, 3-tuple ``('filename', fileobj, 'content_type')`` or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``, where ``'content-type'`` is a string defining the content type of the given file and ``custom_headers`` a dict-like object containing additional headers to add for the file. :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth. :param timeout: (optional) How many seconds to wait for the server to send data before giving up, as a float, or a :ref:`(connect timeout, read timeout) <timeouts>` tuple. :type timeout: float or tuple :param allow_redirects: (optional) Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to ``True``. :type allow_redirects: bool :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy. :param verify: (optional) Either a boolean, in which case it controls whether we verify the server's TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to ``True``. :param stream: (optional) if ``False``, the response content will be immediately downloaded. :param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair. :return: :class:`Response <Response>` object :rtype: requests.Response