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中定义好的类(下面说明各类),重写某些方法即可。
类关系图
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) ` 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 ` object
:rtype: requests.Response