智能多媒体 API

  • 快速入门

    最近更新时间:2017-07-31 16:40:38

    本教程分三部分介绍如何快速开发、部署和使用一个自定义数据处理的应用。

    前期准备:

    1 开发自定义数据处理程序

    在开发自定义数据处理程序前,用户需要先在七牛创建一个自定义数据处理,主要是为了确定自定义数据处理的名称和访问模式。

    创建一个自定义数据处理

    Step1 登录七牛账号

    通过 qdoractl 工具登录您的七牛账号,登录可以使用以下两种方式:

    $ qdoractl login -u <access key> -p <secret key>
    或
    $ qdoractl login 进入命令行交互界面进行登录
    

    其中\ 和 \ 可以在您的密钥管理中找到。

    Step2 创建一个自定义数据处理

    使用如下命令创建一个自定义数据处理:

    qdoractl register <ufop> [-d <description>] [-m <mode>]
    

    参数、标志说明:

    名称 说明 类型 必填
    ufop 自定义数据处理名称,创建后不能修改 string
    -d 或 --description 设置自定义数据处理的描述 string
    -m 或 --mode 设置访问模式
    public : 任何人都能访问
    protected : apply过的用户才能访问
    private : 只有自己才能访问。普通用户只能创建private或protected的自定义数据处理,默认是private
    string

    例如:

    $ qdoractl register doraufoptest -m private -d 'it is a test!'
    

    会创建一个信息如下的自定义数据处理

    • 名称:doraufoptest
    • 模式:私有
    • 描述:it is a test!

    命令参数介绍可以参考命令行工具 qdoractl

    开发自定义数据处理程序

    自定义数据处理程序需要是一个基于Linux构建的,可运行的Docker镜像。镜像的构建和验证可以参考Demo

    什么是可运行的Docker镜像?

    可运行的Docker镜像在构建时需要在Dockerfile中指定入口程序(ENTRYPOINTCMD),同时该入口程序需要满足:

    • 启动后监听 9100 端口
    • 接受 HTTP POST /handler?cmd=XXX&url=XXX 的请求,并返回数据处理结果
    • 在一个自定义的路径上接收HTTP GET 请求,并返回该程序当前的健康状态(可选)

    数据处理

    数据处理接口如下:

    METHOD PATH NOTE
    POST /handler?cmd=XXX&url=XXX [cmd的值为该自定义数据处理名称,url为待处理资源的地址

    请求包:

    POST /handler?cmd=XXX&url=XXX
    
    [body]
    

    返回包:

    200 OK
    
    数据(可能二进制或 json 格式数据,由 APP 语义来定)
    

    错误码:

    • 由 APP 定义,由 APP 使用方解释和使用

    Note:

    • 请求包 query 参数中的 url 是可选参数,若有该参数且合法,则表明待处理的资源是通过 url 表征
    • 否则待处理资源通过请求body传递
    • 自定义数据程序必须同时支持这两种请求格式 http://oano6er3n.bkt.clouddn.com/ufop-developing-logic.png

    健康检查

    建议用户配置健康检查url,七牛自定义数据处理框架会按照用户配置的调用间隔定时向该url发送GET请求来判断实例的健康状态,如果返回的status code是非200,则七牛自定义数据处理框架会将该实例标示为非健康,并不再向该实例发送数据处理请求,从而将有问题的实例隔离出去。

    验证镜像

    在镜像制作完毕后,建议在本地运行该docker镜像,并发送两种数据请求和健康检查请求,来确认镜像功能正常。

    2 部署自定义数据处理

    部署自定义数据处理分为三步。

    Step1 上传自定义数据处理程序

    把第一部分中开发并验证完的可运行的docker镜像,推送到七牛自定义数据处理镜像仓库,运行命令:

    qdoractl push <image_name>
    

    例如:

    qdoractl push ufopdemo:v1
    

    会将名为 ufopdemo:v1 的镜像推送到七牛自定义数据处理镜像仓库

    在推送成功后可以运行如下命令:

    qdoractl image
    

    来查看当前用户所拥有的所有镜像,如:

    $ qdoractl image
    Name             Ctime
    ufopdemo:v1      2016-11-28 20:19:05
    

    Step2 创建发布版本

    在镜像上传成功后,创建一个发布版本。

    首先,需要准备发布版本的配置文件。运行以下命令:

    qdoractl release --mkconfig .
    

    当前目录会生成一份名叫dora.yaml的配置文件,该配置文件包含下列参数:

    名称 说明 类型 必填
    ufopname 自定义数据处理名称 string
    verstr 该发布的版本号 string
    image 镜像名(可通过命令 qdoractl image 找到所有可用镜像) string
    desc 设置发布的说明信息 string
    flavor 设置需要的资源配置(可通过命令 qdoractl flavor 找到所有可用资源配置 ) string
    health_check 设置健康检查
    path : string, 健康检查url,平台会向该url发送GET请求,并根据返回的http status code是否是200来判断该应用是否健康
    timeout : int, 调用健康检查的时间间隔,单位为秒
    struct
    log_file_paths 用户自定义日志路径,该路径下的用户日志会被采集并自动回收 [string]

    修改dora.yaml的配置文件。如下是一个已经修改好的配置文件的内容:

    $ cat dora.yaml
    
    ---
    ufopname: doraufoptest
    verstr: v1 
    image: ufopdemo:v1 
    desc:  a demo
    flavor: C1M1 
    health_check:
      path: "/health" 
      timeout: 3 
    log_file_paths: []
    

    在修改完dora.yaml后,运行命令:

    qdoractl release --config .
    

    基于当前目录下配置文件dora.yaml,向服务器发出一个创建发布版本请求, 以上面的实例配置为例,执行结果如下:

    $ qdoractl release --config .
    Build success
    Ufop:      doraufoptest
               Version:      v1
               Image:        ufopdemo:v1
               Flavor:       C1M1
               Desc:         a demo
    You can also see the release via run `qdoractl release doraufoptest -d`
    

    创建成功后, 可以使用命令:

    qdoractl release <ufop> -d
    

    查看该自定义数据处理所有发布版本的详细信息,参数说明:

    名称 说明 类型 必填
    ufop 自定义数据处理名称 string

    例如:

    $ qdoractl release doraufoptest -d
    Mode:             PRIVATE
    
    Releases:
    Version  Image  Flavor  Desc  Health Check Path  Health Check Timeout      LogFilePaths
    v1       ufopdemo:v1     C1M1    a demo    /health      3    []
    
    Deploys:
    Version      Region      Expect      Actual
    

    Step3 调整实例数

    创建完一个发布版本后,运行如下命令调整该发布版本的运行实例数:

    qdoractl deploy <ufop> <release_version> --region <region_name> --expect <number>
    

    参数、标志说明:

    名称 说明 类型 必填
    ufop 自定义数据处理名称 string
    release_version 设置发布版本(与创建发布版本中dora.ymal中的verstr一致) string
    -r 或 --region 设置设置实例部署的区域 (qdoractl region 可以列出所有可用区域) string
    -e 或 --expect 设置期望实例数 int

    例如:

    $ qdoractl deploy doraufoptest v1 --region z0 --expect 2
    Deploy success
    Please run `qdoractl deploy doraufoptest --id deploy-aeff0dc6-b5de-11e6-88be-6c92bf2f06d8-1480387870674711630` to view you deploy
    Please run `qdoractl release doraufoptest v1 -d` to view you release
    

    调整实例数命令成功后,命令行工具会提示运行命令:

    qdoractl deploy <ufop> --id <deployment_id>
    

    查看这次实例调整的最终执行状况

    参数、标志说明:

    名称 说明 类型 必填
    ufop 自定义数据处理名称 string
    -i 或 --id 查看指定id的部署信息(调整实例数执行成功后,会返回一个id,可以根据此id来查询该次调整的最终执行情况) string

    示例执行该命令,输出如下:

    $ qdoractl deploy doraufoptest --id deploy-aeff0dc6-b5de-11e6-88be-6c92bf2f06d8-1480387870674711630
    
    Version      Expect      Region      Created    Id    Status     Message
    
    v1           2           z0          2016-11-29 10:51:10      deploy-aeff0dc6-b5de-11e6-88be-6c92bf2f06d8-1480387870674711630      RUNNING
    

    3 如何使用自定义数据处理

    自定义数据处理启动(运行实例数大于0)之后,就可以直接通过 URL 同步触发或者使用持久化数据处理操作使用该自定义数据处理。

    http://<resource_url>?<ufop>
    

    参数说明:

    名称 说明 类型 必填
    ufop 自定义数据处理名称 string
    resource_url 处理对象的地址 string
    以上内容是否对您有帮助?
  • Close