描述

单据实例中，图片控件、附件控件和富文本控件的文件上传。

上传文件需要分两步：

  1. 获取上传文件前参数；
  2. 上传文件到文件服务器。

获取上传文件前参数

请求

名称 是否必需 类型 描述
idOrName 是 String 单据模板 Id/名称/实体名称。如果field是子表控件，则这里的是子表单据模板的 Id/名称/实体名称（具体请查看模板的SubEntityForm）。
instanceId 否 String 单据实例Id，字段在子表则为每行对应的实例Id；
没有真正实例时需要客户端生成一个以temp_为前缀的临时实例Id。
field 是 String 要上传的单据图片或附件字段 Id/[组名-]名称/实体属性名称/FieldName。
keyOption 否 String field参数字段以什么为属性名（键名）。
属性名：
- Entity 以实体属性名为属性名；
- Caption 以[组名-]控件名为属性名；
- Id 以字段的Id为属性名；
- FieldName 以字段的FieldName为属性名，默认。
fileName 否 String 单文件上传时，文件名称（加后缀，如test.jpg）。
isMultiFileUpload 否 Boolean 是否多文件上传：
- true 是；
- false 否。
true的时候fileName将不起作用，强制为${filename}。
多文件上传，只需请求该接口获取一次，然后使用此请求响应的参数发送多个文件上传到文件服务器的请求即可。

响应

  • 返回参数
名称 类型 描述
fileServerEndpoint String 文件服务器Endpoint。
formField Object[] 上传到文件服务器时，POST请求中表单域需要提交的键值对。

上传成功如何获取文件对象：

  1. 表单域formField中固定有key表示文件对象（文件对象Id）；
  2. 如果是单文件上传，文件对象就是key；如果是多文件上传，上传后的文件，把key后缀 ${filename} 替换成上传的文件名称。例如key为a/b/${filename}，上传文件 a1.txt，那么最终的文件对象就是 a/b/a1.txt；

文件对象的作用：

  • 如果单据模板设置的此图片或附件控件，允许公开访问，则可以直接通过 文件服务器Endpoint+key 直接可以访问或下载此文件，否则不能直接访问，只能通过平台返回的地址去访问或下载；
  • 在单据实例中，如果此单据实例还没保存过，或者子表新增一行没有执行保存操作（即都没有实例Id），那么也可以上传文件到文件服务器，但是在文件服务器中的位置是临时的，没有与单据实例关联。当单据实例新建或修改时，提交的实例数据中，需要把上传后的文件对象作为一个字段值，赋值给该图片或附件字段的属性，这样在保存成功后才能与单据实例关联。如下：
{
    "其它字段属性":"其它字段值",
    "Portrai": [//主表图片或附件字段
        {
            "Id": "form/.../myPortrai.jpg",//文件对象
        }
    ],
    "Educations": [
        {
            "其它字段属性":"其它字段值",
            "Portrai2": [//子表图片或附件字段
                {
                    "Id": "form/.../myPortrai2.jpg",//文件对象
                }
            ]
            "OrderIndex": 0
        }
    ]
}

示例

请求实例1

单个文件上传

/v1/form/templates/4bc85381-2209-4f36-a073-b1a7795bcd00/instances/012c7cfc-21d3-4977-a0ba-35600c5d2f23/fields/Portrai/upload_data?keyOption=Entity&fileName=myPortrai.jpg  HTTP/1.1
Host: api.dadayun.cn
Date: Mon, 03 Sep 2018 01:49:35 GMT

响应实例1 

HTTP/1.1 204 No Content
Date: Mon, 03 Sep 2018 01:49:35 GMT

{
    "fileServerEndpoint": "https://test.oss-cn-hangzhou.aliyuncs.com",
    "formField": {
        "OSSAccessKeyId": "zNmKWvIcsEkwYLDs",
        "policy": "eyJleHBpcmF0aW9uIjoiMjAxNy0wOC0wOVQwNzo0NDowMC4xMDhaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoianotZmlsZSJ9XX0=",
        "Signature": "QipFHmc4QCgCm6bm9189+LetOlM=",
        "key": "testupload/myPortrai.jpg"
    }
}

请求实例2

多个文件上传

GET  /v1/form/templates/4bc85381-2209-4f36-a073-b1a7795bcd00/instances/012c7cfc-21d3-4977-a0ba-35600c5d2f23/fields/Portrai/upload_data?keyOption=Entity&isMultiFileUpload=true  HTTP/1.1
Host: api.dadayun.cn
Date: Mon, 03 Sep 2018 01:49:35 GMT

响应实例2 

HTTP/1.1 204 No Content
Date: Mon, 03 Sep 2018 01:49:35 GMT

{
    "fileServerEndpoint": "https://test.oss-cn-hangzhou.aliyuncs.com",
    "formField": {
        "OSSAccessKeyId": "zNmKWvIcsEkwYLDs",
        "policy": "eyJleHBpcmF0aW9uIjoiMjAxOC0wOS0wOFQwNTo1MjoyNi4wODNaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoianotZmlsZSJ9XX0=",
        "Signature": "jJ3WlFrEfjKumnUQx3rePRxDfrY=",
        "key": "testupload/${filename}"
    }
}

上传文件到文件服务器

利用上一步请求的参数，以POST操作提交表单，表单编码为“multipart/form-data”，即header中Content-Type为multipart/form-data; boundary=xxxxxx这样的形式； 把返回参数中的formField中的每一项作为表单域和值，最后把文件放在最后一个表单域中，表单域的名称为file，提交表单就可上传文件。

请求

  • URL

    上一步请求结果中的fileServerEndpoint

  • HTTP请求方式

    POST

  • Header参数

    {
  "Content-Type":"multipart/form-data; boundary=xxxxxx"
}

  • HTTP请求参数

    上一步请求结果中的formField，把每一项作为表单域和值，最后把文件放在最后一个表单域中，表单域的名称为file。

响应

当上传成功时，HTTP 的返回是 204 No Content：

HTTP/1.1 204 No Content

示例

本示例以第一步1. 获取上传文件前参数（文件服务器Endpoint、token等）获取的上传参数为前提

请求示例 

POST  /  HTTP/1.1
Host: test.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 03 Sep 2018 01:49:35 GMT
content-type: multipart/form-data; boundary=--------------------------595475130274562452316578
content-length: 150087
Connection: keep-alive

----------------------------595475130274562452316578
Content-Disposition: form-data; name="OSSAccessKeyId"

zNmKWvIcsEkwYLDs
----------------------------595475130274562452316578
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAxNy0wOC0wOVQwNzo0NDowMC4xMDhaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoianotZmlsZSJ9XX0=
----------------------------595475130274562452316578
Content-Disposition: form-data; name="Signature"

QipFHmc4QCgCm6bm9189+LetOlM=
----------------------------595475130274562452316578
Content-Disposition: form-data; name="key"

form/.../myPortrai.jpg
----------------------------595475130274562452316578
Content-Disposition: form-data; name="file"; filename="myPortrai.jpg"

正常返回示例 

HTTP/1.1 204 No Content
Date: Mon, 03 Sep 2018 01:49:35 GMT

results matching ""

    No results matching ""