Awesome

又拍云 lua SDK

又拍云存储lua SDK，基于又拍云存储HTTP REST API接口，nginx，ngx_lua 开发。

下载地址：

更新说明

云存储基础接口

准备操作

创建空间

大家可通过又拍云主站创建自己的个性化空间。具体教程请参见“创建空间”。

初始化UpYun

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            endpoint = 0, --接入点
                            author = "upyun" --认证方式
                            }
            local upyun = yun:new(config)

            ...
        ';
    }

在使用lua SDK中的任何操作之前，都必须先按上述方式创建一个upyun本地变量。

若不了解授权操作员，请参见“授权操作员”

选择最优的接入点

根据国内的网络情况，又拍云存储API目前提供了电信、联通网通、移动铁通三个接入点。

在upyun初始化前，可以通过endpoint配置项进行设置。若没有明确进行设置，upyun默认将根据网络条件自动选择接入点。

接入点有四个值可选：

endpoint = 0 ：根据网络条件自动选择接入点(默认值)
endpoint = 1 ：电信接入点
endpoint = 2 ：联通网通接入点
endpoint = 3 ：移动铁通接入点

**注：**建议大家根据服务器网络状况，手动设置合理的接入点已获取最佳的访问速度。

选择http请求认证方式

根据用户需求，又拍云存储API目前提供了HTTP基本认证，又拍云签名认证两种认证方式，用户可以自行选择一种，为确保安全性，建议使用又拍云签名认证方式。

在upyun初始化前，可以通过author配置项进行设置。若没有明确进行设置，upyun默认将采用又拍云签名认证方式。

认证方式有两个值可选：

author = "basic" ：HTTP基本认证
author = "upyun" ：又拍云签名认证(默认值)

上传文件

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample.jpg"
            local gmkerl = nil
            local options = {
                             mkdir = true, 
                             md5 = true, 
                             secret = "secret", 
                             otype = "JPEG"
                            }
            local info, err = upyun:upload_file(savePath, gmkerl, options)
            if not info then
                ngx.say("failed to upload image file : " .. err)
                return
            end
        ';
    }

参数说明

savePath(必须项，不可为nil)，要保存到又拍云存储的具体地址
- 比如/acayf-img/sample.jpg表示以sample.jpg为文件名保存到/acayf-img空间下；
- 若保存路径为/sample.jpg，则表示保存到根目录下，也可以保存到该空间的其他目录下，如/acayf-img/dir/sample.jpg；
- 注意savePath的路径必须是以/开始的，下同。
gmkerl(非必须项，可为nil)，上传图片时，允许直接对图片进行旋转、裁剪、缩略图等操作，具体请参见图片处理接口
options(非必须项，可为nil)：
- mkdir，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）
- md5，表示上传文件时是否进行文件的MD5校验：若又拍云服务端收到的文件MD5值与用户设置的不一致，将返回 406 Not Acceptable 错误。对于需要确保上传文件的完整性要求的业务，可以设置该参数。
- secret，用于提供用户密钥，图片类空间若设置过缩略图版本号，即可使用原图保护功能（文件类空间无效）。原图保护功能需要设置一个自定义的密钥（只有您自己知道，如上面的secret）。待文件保存成功后，将无法根据http://空间名.b0.upaiyun.com/文件名直接访问上传的文件，而是需要在 URL 后面加上缩略图间隔标志符+密钥进行访问。比如当缩略图间隔标志符为!，密钥为secret，上传的文件路径为/dir/sample.jpg，那么该图片访问 URL 为: http://空间名.b0.upaiyun.com/dir/sample.jpg!secret，若原图保护密钥若与缩略图版本号名称相同，则在对外访问时将被视为是缩略图功能，而原图将无法访问，请慎重使用。
- otype，用于指定文件类型，当待上传的文件扩展名不存在，或扩展名不足以判断文件的Content-Type时，允许用户自己设置文件的Content-Type值。又拍云存储默认使用文件名的扩展名进行自动设置。

其他说明

具体用户希望上传到又拍云空间的 文件内容将从用户向Nginx发起的请求包体中获得
文件上传成功后，可直接通过http://空间名.b0.upaiyun.com/文件名来访问文件
图片类空间上传文件后，函数会返回文件的基本信息，可通过info返回值来获取：

        info["width"]      // 图片宽度
        info["height"]     // 图片高度
        info["frames"]     // 图片帧数
        info["file-type"]  // 图片类型

注意事项

如果空间内savePath已经存在文件，将进行覆盖操作，并且是不可逆的。所以如果需要避免文件被覆盖的情况，可以先通过获取文件信息操作来判断是否已经存在旧文件。
图片类空间只允许上传图片类文件，其他文件上传时将返回“不是图片”的错误。
如果上传失败，则会抛出异常。

下载文件

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample.jpg"
            local ok, err = upyun:download_file(savePath)
            if not ok then
                ngx.say("failed to downlod file : " .. err)
                return
            end
        ';
    }

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/acayf-img/sample.jpg。

注意事项

下载文件时必须确保空间下存在该文件，否则将返回文件不存在错误

获取文件信息

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample.jpg"
            local info, err = upyun:get_fileinfo(savePath)
            if not info then
                ngx.say("failed to get file info : " .. err)
                return
            end
        ';
    }

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/acayf-img/sample.jpg。

其他说明

最终返回的结果保存在info变量中，变量中包含了文件的“文件类型”、“文件大小”和“创建日期”信息

   * info["type"]; // 文件类型
   * info["size"]; // 文件大小
   * info["date"]; // 创建日期

若文件不存在，则抛出异常，请做好对结果的判断。

删除文件

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-file/test.txt"
            local ok, err = upyun:remove_file(savePath)
            if not ok then
                ngx.say("failed to remove file : " .. err)
                return
            end

        ';
    }

参数说明

savePath：又拍云存储中文件的具体保存地址。比如/acayf-file/test.txt。

其他说明

删除文件时必须确保空间下存在该文件，否则将返回文件不存在的错误

创建目录

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local dir = "/acayf-file/dir/test/"
            local ok, err = upyun:make_dir(dir, {mkdir = true})
            if not ok then
                ngx.say("failed to make dir : " .. err)
                return
            end

        ';
    }

参数说明

dir：待创建的目录结构。比如/acayf-file/dir/test/
mkdir：可选的boolean类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）

其他说明

待创建的目录路径必须以斜杠 / 结尾
创建目录操作可在上传文件时一并完成，功能是相同的
若空间相同目录下已经存在同名的文件，则将返回不允许创建目录的错误

删除目录

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local dir = "/acayf-file/test/"
            local ok, err = upyun:remove_file(dir)
            if not ok then
                ngx.say("failed to remove dir : " .. err)
                return
            end

        ';
    }

参数说明

dir：待删除的目录结构。比如/acayf-file/test/

其他说明

该操作只能删除单级目录，不能一次性同时删除多级目录，比如当存在/dir1/dir2/dir3/目录时，不能试图只传递/dir1/来删除所有目录。
若待删除的目录dir下还存在任何文件或子目录，将返回不允许删除的错误。比如当存在/dir1/dir2/dir3/目录时，将无法删除/dir1/dir2/目录。

获取目录文件列表

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                           }
            local upyun = yun:new(config)

            local dir = "/acayf-file/test/"
            local info, err = upyun:read_dir(dir)
            if not info then
                ngx.say("failed to read dir : " .. err)
                return
            end
        ';
    }

参数说明

dir：待获取文件列表的目录。比如/acayf-file/test/

其他说明

可以循环获取info中文件的“名称”、“类型”（文件或目录）、“文件大小”和“最后修改时间”
info[1].name，第一个文件的名字
info[1].type，第一个文件的类型，N表示普通文件，F表示文件夹
info[1].size，第一个文件的大小
info[1].lastmodified，第一个文件的最后修改时间
info[2]包含第二个文件的信息，以此类推

获取使用量情况

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                           }
            local upyun = yun:new(config)

            local dir = "/acayf-file/test/"
            local info, err = upyun:get_usage(dir)
            if not info then
                ngx.say("failed to get usage : " .. err)
                return
            end
        ';
    }

参数说明

dir：待获取使用量的目录。比如/acayf-file/test/

其他说明

使用量的单位为 byte，比如1M的使用量将以1048576这样的数字返回
整个空间的使用量等效于/根目录的使用量

图片处理接口

对于图片的自定义处理，又拍云存储支持以下两种方式：

自定义版本方式
上传图片时传递图片处理参数

虽然两种方式都能够达到图片处理的效果，但存在以下区别：

区别点	自定义版本方式	参数处理方式
是否保留原图	是，各个缩略图都在这个原图的基础上制作	否，只保留处理后的图片，若再使用缩略图版本号的方式来访问（这种方法是可行的），则将在处理后的图片基础上制作
空间使用量	以原图的大小计算使用量，后续各个版本的缩略图都不会计算在用户的空间使用量中	以处理后的图片大小计算使用量，大小视具体的处理参数而定
灵活性	可通过修改自定义版本的参数来满足变化的需求，参数修改后若没有自动刷新缓存，则可以手动强制刷新来确保新参数生效	只能调整代码中的处理参数，且原先保存的图片无法自动更新

我们更推荐大家使用自定义版本的方式对图片进行处理，但您可以根据自己业务的使用场景来选用合适的方式。

以下内容只是介绍“传递图片处理参数”的方法。

缩略图

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample_fixwidth.jpg"
            local gmkerl = {
                            type = "fix_width",
                            value = 200,
                            quality = 95,
                            unsharp = true
                           }
            local options = {mkdir = true}
            local info, err = upyun:upload_file(savePath, gmkerl, options)
            if not info then
                ngx.say("failed to upload image file : " .. err)
                return
            end

            savePath = "/acayf-img/sample_thumbnail.jpg"
            gmkerl = {
                        thumbnail = "fixwidth"
                     }
            options = {mkdir = true}
            info, err = upyun:upload_file(savePath, gmkerl, options)
            if not info then
                ngx.say("failed to upload image file : " .. err)
                return
            end
        ';
    }

参数说明

savePath：要保存到又拍云存储的具体地址
- 比如/acayf-img/sample_fixwidth.jpg表示以sample_fixwidth.jpg为文件名保存到/acayf-img空间的根目录下；
- 注意savePath的路径必须是以/开始的。
gmkerl：自定义组合的图片处理参数，现提供的参数有：
- type：缩略图类型，必须搭配缩略图参数值（value）使用，否则无效
- value：缩略图参数值，必须搭配缩略图类型（type）使用，否则无效
- quality：缩略图的质量，默认 95
- unsharp：缩略图的锐化，默认值为true，默认开启
- thumbnail：自定义缩略图版本号，需要通过UPYUN后台来创建和配置
- crop：图片裁剪
- rotate：图片旋转
mkdir：可选的boolean类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）

其他说明

图片处理参数的具体使用方法，请参考标准API上传文件
缩略图功能只能处理图片文件；若上传非图片文件且传递了图片处理参数时，将返回不是图片的错误

图片旋转

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample_rotate.jpg"
            local gmkerl = {
                            rotate = 90
                           }
            local options = {mkdir = true}
            local info, err = upyun:upload_file(savePath, gmkerl, options)
            if not info then
                ngx.say("failed to upload image file : " .. err)
                return
            end
        ';
    }

参数说明

savePath：要保存到又拍云存储的具体地址
gmkerl：自定义组合的图片处理参数
rotate：旋转参数
mkdir：可选的boolean类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）

其他说明

旋转参数暂时只接受auto，90，180，270四种参数，其中auto处理时需要图片包含EXIF信息
具体旋转参数的说明可参考图片旋转

图片裁剪

    location /t {
        content_by_lua '
            local yun = require "resty.upyun"
            local config = {
                            user = "acayf", --授权操作员名称
                            passwd = "testupyun", --操作员密码
                            }
            local upyun = yun:new(config)

            local savePath = "/acayf-img/sample_crop.jpg"
            local gmkerl = {
                            crop = "0,0,200,160"
                           }
            local options = {mkdir = true}
            local info, err = upyun:upload_file(savePath, gmkerl, options)
            if not info then
                ngx.say("failed to upload image file : " .. err)
                return
            end
        ';
    }

参数说明

savePath：要保存到又拍云存储的具体地址
gmkerl：自定义组合的图片处理参数
crop：裁剪参数，接受x,y,width,height格式的参数
mkdir：可选的boolean类型参数，表示当不存在父级目录时是否自动创建父级目录（只支持自动创建10级以内的父级目录）

其他说明

具体裁剪参数的说明可参考图片裁剪

错误代码表

HTTP状态码	返回代码	描述
400	Bad Request	错误请求(如 URL 缺少空间名)
401	Unauthorized	访问未授权
401	Sign error	签名错误(操作员和密码,或签名格式错误)
401	Need Date Header	发起的请求缺少 Date 头信息
401	Date offset error	发起请求的服务器时间错误，请检查服务器时间是否与世界时间一致
403	Not Access	权限错误(如非图片文件上传到图片空间)
403	File size too max	单个文件超出大小(100Mb 以内)
403	Not a Picture File	图片类空间错误码，非图片文件或图片文件格式错误。针对图片空间只允许上传 jpg/png/gif/bmp/tif 格式。
403	Picture Size too max	图片类空间错误码，图片尺寸太大。针对图片空间，图片总像素在 200000000 以内。
403	Bucket full	空间已用满
403	Bucket blocked	空间被禁用,请联系管理员
403	User blocked	操作员被禁用
403	Image Rotate Invalid Parameters	图片旋转参数错误
403	Image Crop Invalid Parameters	图片裁剪参数错误
404	Not Found	获取文件或目录不存在；上传文件或目录时上级目录不存在
406	Not Acceptable(path)	目录错误（创建目录时已存在同名文件；或上传文件时存在同名目录)
503	System Error	系统错误