YD/T 3188-2016
基本信息
标准号： YD/T 3188-2016
中文名称：基于表述性状态转移 (REST) 技术的业务能力开放应用程序接口 (API) 文件传输业务
标准类别：通信行业标准(YD)
标准状态：现行
出版语种：简体中文
下载格式：.zip .pdf
下载大小：6095771
相关标签： 基于 表述 状态 转移 技术 业务 能力 开放 应用 程序接口
标准分类号
关联标准
出版信息
相关单位信息
标准简介
YD/T 3188-2016.RESTful based service capability open API-File transfer.
1范围
YD/T 3188规定了基于表述性状态转移(REST) 的针对文件传输业务的API接口定义，包括接口流程、接口数据结构、接口定义和接口安全要求等。
YD/T 3188适用于提供文件传输能力开放的应用程序接口。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本( 包括所有的修改单)适用于本文件。
YD/T 2423-2012基于表述性状态转移(REST) 技术的电信业务能力开放平台技术要求
OMA-ER-网络API授权框架( Authorization Framework for Network APIs)
Autho4API-V1_ 0
OMA-TS-REST_ N RESTful风格 的网络API通用定义1.0版本(Common definitions for RESTful etAPI Common Network APIs)
IETF RFC2045 多功能英特网邮件扩展功能(MIME)第一部分:英特网消息体格式(Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies)
ETF RFC2046 多功能英特网邮件扩展功能(MIME)第二部分:媒体类型(Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types)
IETF RFC2327 SDP:会话描述协议(SDP: Session Description Protocol)
IETF RFC2392 内容标识和消息标识统一资 源定位符(Content-ID and Message-ID Uniform Resource Locators )
1范围
YD/T 3188规定了基于表述性状态转移(REST) 的针对文件传输业务的API接口定义，包括接口流程、接口数据结构、接口定义和接口安全要求等。
YD/T 3188适用于提供文件传输能力开放的应用程序接口。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本( 包括所有的修改单)适用于本文件。
YD/T 2423-2012基于表述性状态转移(REST) 技术的电信业务能力开放平台技术要求
OMA-ER-网络API授权框架( Authorization Framework for Network APIs)
Autho4API-V1_ 0
OMA-TS-REST_ N RESTful风格 的网络API通用定义1.0版本(Common definitions for RESTful etAPI Common Network APIs)
IETF RFC2045 多功能英特网邮件扩展功能(MIME)第一部分:英特网消息体格式(Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies)
ETF RFC2046 多功能英特网邮件扩展功能(MIME)第二部分:媒体类型(Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types)
IETF RFC2327 SDP:会话描述协议(SDP: Session Description Protocol)
IETF RFC2392 内容标识和消息标识统一资 源定位符(Content-ID and Message-ID Uniform Resource Locators )
标准图片预览
标准内容
ICS33.040
中华人民共和国通信行业标准
YD/T3188—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）
文件传输业务
RESTful based service capability open APIFile transfer(OMA-TS-REST NetAPI FileTransfer-V1 0-20140218-D ,RESTful Network APIFile Transfer vl.0,NEQ)2016-10-22发布
中华人民共和国工业和信息化部2017-01-01实施
前言．
1范围，
2规范性引用文件
3术语、定义和缩略语
3.1术语和定义
3.2缩略语，
4文件传输业务概述
5文件传输RESTfulAPI定义
5.1资源概述.wwW.bzxz.Net
5.2枚举类型定义
5.3数据结构定义
5.4流程图.
6接口定义
文件传输订阅管理
创建对一文件传输.
查询和释放对--文件传输.
被叫文件传输请求状态
被叫收到文件传输通知
主叫侧文件传输接受通知
通知文件传输内容链接。
6.8文件传输结束通知..
7错误定义.
7.1、业务异常.
7.2策略异常..
8授权框架
8.1使用Autho4API框架...
8.2“acr:auth'的用法
参考文献．
YD/T3188—2016
YD/T3188-2016
本标准是“基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）”系列标准之：，该系列标推的缔构及名称预计如下：一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）短消息和多媒体销息业务部分：
一基丁表述性状态转移（REST）技术的业务能力开放应用程序接凹（API）点击拨号；
一基丁表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端状态：
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端能力信息：一基·F表述性状态转移（REST）技术的业务能力开放应用程序接口（API）微博业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）搜索业务；
地址本：
一基丁表述性状态转移（REST）技术的业务能力开应用程序接口（AP）一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）文件传输业务；
基表述性状态转移（REST）技术的业务能力开放应用程序接口（API）定位业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）状态呈现业务；
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）聊天业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）用户信息业务：支付业务；
一一基表述性状态转移（REST）技术的业务能力开放应用程序接口（API）一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）视频共享；
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）图片共享；
移动互联网用户
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）上下文感知业务：
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）非结构化补充数据业务。
随着技术和市场的发展，还将根据情况制定后续相关标准。本标准按照GB/T1.1-2009给出的规则起草。本标准使用重新起草法参考OMA-TS-REST NetAPIFileTransfer-V1_0-20140218-D.《基于表述性状态转移（REST）技术的文件传输应用程序接口（API）（OMARESTfulNetworkAPIFileTransfervl.0）》编制，本标准与OMA-TS-REST_NetAPI_FileTransfer-V1_0-20140218-D的一致性程度为非等效。本标准由中国通信标准化协会提出并归口。本标准起草单位：中国移动通信集团公司、中国信息通信研究院、中国联合网络通信集团有限公司、中国电信集团公司。
本标准主要起草人：刘悦、庞亚昆、杨波、赵婷、汪洋。1范圈
基干表述性状态转移（REST）
技术的业务能力开放应用程序接口（AP）文件传输业务
YD/T3188—2016
本标准规定了基于表述性状态转移（REST）的针对文件传输业务的API接口定义，包括接口流程、接门数据结构、接口定义和接口安全要求等。本标准适用于提供文件传输能力开放的应用程序接口。2
规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注月期的版本适用于本文件。凡事不注口期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T 2423-2012
OMA-ER-
Autho4API-V1_ 0
OMA-TS-REST N
etAPI_Common
IETF RFC2045
IETFRFC2046
IETFRFC2327
IETFRFC2392
IETFRFC2616
IETF RFC3261
IETFRFC3966
IETFRFC3986
IETFRFC4627
基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求网络API授权框架 （Authorization Framework for Network APIs）RESTful风格的网络API通用定义1.o版本（Commondefinitionsfor RESTfulNetwork APIs)
多功能英特网邮件扩展功能（MIME）第一部分：英特网消息体格式(Multipurpose Internet Mail Extensions (MIME) Part One: Format of InternetMessage Bodies )
多功能英特网邮件扩展功能（MIME）第二部分：媒体类型（MultipurposeIntemet Mail Extensiops (MIME)Part Two: Media Types)SDP:会话描述协议（SDP:Session Description Protocol）内容标识和消息标识统一资源定位符（Content-IDand Message-IDUniformResource Locators)
超文本传输协议——HTTP/1.1(Hypertext Transfer Protocol --HTTP/1.1)SIP：会话发起协议（SIP:Sessjon InitiationProtocol）电话号码的Tel LIRI（ThetelURIforTelephoneNumbers）统—资源标示符(URI)：—般语法(UniformResourceIdentifier(URI)：GenericSyntax)
Java描述语言对象符号的应用/基于java描述语言的轻量级数据交换格式（Theapplication/jsonMediaTypeforJavaScriptObjectNotation (JSON))1
YD/T 3188—2016
IETF RFC4975
IETFRFC5547
OMA RC API RD
XMLSchemal
XMLSchema2
3术语、定义和缩略语
消息会话中继协议（MSRP）（TheMessageSessionRelayProtocol（MSRP)）用于许可文件传输的会话描述协议提议/回答机制（SessionDescriptionProtocol (SDP) Offer/Answer Mechanism to Enable File Transfer )OMA富通信API需求:OMARCSProfileofRESTfulNetworkAPIsv2.0可扩展标识语言架构第1部分：结构（第二版）（W3CXMLSchemaDefinitionLanguage (XSD) I.1 Part l: Structures Second Edition)可扩展标识语言架构第2部分（W3CXMLSchemaDefinitionLanguage（XSD）1.1 Part 2: Datatypes)
下列术语、定义和缩略语适用丁本文件。3.1术语和定义
表述性状态转移RepresentationalStateTransfer一种针对网络应用的设计和开发方式，指的是：组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性，具体见YD/T2423-2012对REST的定义。3.1.2
Web服务WebService
一种构建应用程序的普遍模型，“可以在任何支持网络通信的操作系统中实施运行：是一种新的web应用程序分支，是自包含、自描述、模块化的应用，可以发布、定位、通过web调用，3.1.3
简单对象访问协议SimpleObjectAccessProtocol一种轻量的、简单的、基于XML的协议，它被设计成在web上交换结构化的和固化的信息。3.2缩略语
下列缩略语适用丁本文件。
Application Prograruming InterfaceHyperText Transfer Protocol
Identitifer
Multipurpose InternetMail ExtensionsRepresentational State TransferSession Description ProtocolUniform Resoure Locator
Extensible Markup Language
应用程序编程接口
超文本传输协议
多用途网际邮件扩充协议
表述性状态转移
会话描述协议
统一资源定位符
扩展标记语言
文件传输业务概述
YD/T 3188—2016
文件传输业务通过开放接口提供文件传输订阅管理、传输和释放文件传输、被叫收到文件传输通知后处理、文件接收通知、文件传输通知、文件结束通知等功能。文件传输RESTfulAPI定义
5.1资源概述
本节概要描述了图片共享的RESTfulAPI所用到的资源。本标准中URL变量“apiVersion”的取值为“vl”，表明该API对应于本标准。URL变量“apiVersion”的语义定义见OMA-TS-RESTNetAPICommon-V1 O。图1为图片共享RESTfulAPI的资源树结构。注：资源树中实线框所示的节点表示该节点有关联的HTTP方法。atserverRooljifiletransfer:tapiversinny'tusurld)/subseriptios
I(subacripliond)0
Busionidy
utalus
图1文件传输RESTfulAPI资源树结构表1给出了本标准中定义的客户端管理文件传输通知订阅的资源概述，其数据类型表示允许的HTTP方法，其中数据结构的具体定义见5.3。见表1。
表1客户端管理文件传输通知订阅基础URL：
全部的对于
文件传输通
知的订阅通
http:/l (serverRoot)
/filetranafer/ (spi
Version)/(userld)
/subscriptions
数据结构
FileTransferSubscriptionList（用于GET操作）
FileTraasferNotification
Subscription（用于POST操作）common:ResourceReference
（POST操作的响应中可选）
读取·个用户
的所有活跃的
文件传输订阅
HTTP方法
创建··个
用户新的
文件传输
DELETE
YD/T 3188—2016
基础URL：
单独的个
对于文件传
输通知的订
阅通知
表1客户端管理文件传输通知订阅（续）http:/ (serverRoot)
/fletransfer/(api
Version)/ (userld)
/subscriptions/ (subs
criptionId)
激据结构
FileTransferNotificationSubscription
客户端管理一对一文件传输资源概述见表2。获得一个与某
“用户相关的
活跃的文件传
输订阅
表2客户端管理一对一文件传输
基础URL：
所有…·对一文
件传输会话
特定的一对一
文件传输会话
会话状态
http:// (serverRoot)
/filetransfer/(api
Vergion)/(userid)
/sessions
/scssions/ [sesion]
/sessions/ (sessionl
dy/status
数据结构
FileTransferSessiounf
ormation（用于POST）
common:ResourceRef
erence（在POST响应
中可选）
FileTransferSessionInf
ormation
ReceiverSessionStatus
检索文件
传输会话
HTTP方法
HTTP方法
创建一个
对一文件传
输会话
接受一对
文件传
输邀请
服务器通知客户端文件传输状态和文件链接输资源概述见表3。表3服务器通知客户端文件传输状态和文件链接资源
通知客户端会话
基础URL：
由客户端指定
当订阅被创建或分
配时由客户端指定
通知客户端文件当订阅被创建或分传输事件
通知户端文件
传输内穿的链接
通知客户端文件
传输被接受
配时由客户端指定
当订阅被创建或分
配时由客户端指定
当订阅被创建或分
配时由客户端指定
数据结构
FileTransferSession
InvitatiocNotification
FileTransferEvent
Notification
FileTransferFile
Notification
FileTransferAcceptance
Notification
HTTP方法
DELETE
停止订阅
并停止相
关的通知
DELETE
取消文件传输
会话邀请（主叫
侧）拒绝文件传
输邀请（被叫
侧）终结会话
DELETE
通知客户端有发给其的
文件传输邀请
通知客户端文件传输事
订阅恢复时通知客户端
文件传输内察的链接
通知客户端接收方同意
了接受文件传输
通知客广端订阅
关系取消
表3服务器通知客户端文件传输状态和文件链接（续）基础URL：
由客户端指定
当订阅被创建或分
配时由客户端指定
5.2枚举类型定义
5.2.1FileDisposition
数据结构
FileTransferSubscriptio
nCancellationNotificati
YD/T 3188—2016
HTTP方法
通知客户端订阅关系被
取消（如超时）
该参数为枚举类型。描述文件传输中的文件展现方式状态值，具体见表4。表4FileDisposition：枚举
枚举值
Render
Attachment
5.2.2 EventType
文件应当被自动展示
文件不应当被自动展示，
该参数为枚举类型。描述通告中可能出现的事件类型，具体见表5。表5EventType：枚举
枚举值
ScssionCancelled
SessionEnded
Deelined
Successful
Failed
Aborted
ReceiverStatus
在发出邀请的阶段，发送方放弃了文件传输文件传输会话被终止
接收方拒绝了文件传输会话邀请文件鼓成功传输
因为出现错误导致文件传输失败发送方终止了文件传输
该参数为枚举类型。描述文件接收者在文件传输中可能的状态值，具体见表6。表6ReceiverStatus：枚举
枚举值
Invited
Connected
Disconnected
5.3数据结构定义
用广被邀请加入文件传输会话
用户已经连接文件传输会话
用户与文件传输会话的链接中断5.3.1FileTransferSessionlnfornation描述文件传输会话的信息，具体见表7。描速
DELETE
YD/T3188—2016
参数名
originatorAddress
originatorName
receiverAddress
receiverName
status
fileInformation
clientCorrelator
resourceURL
参数类型
Xsd:anyURI
xsd:string
xsd:anyURI
xsd:string
ReceiverStatus
FileInfomation
xsd:string
xsd:anyURI
5.3.2Filelnformation
表7FileTransferSessionlnformation必选/可选
描述文件的属性集，具体见表8。参数名
fileSelector
fileDisposition
fleDescription
参数类型
FileSelcctor
IFileDispasition
xsd:string
必选/可选
文件传输会话发起者的地址（如SIPURI或TELURI)。如果发起方的地址同时也是request URI的部分，则该地址与request URl应相同各类URI定义分别见ETFRFC3261、IETF RFC3966及IETFRFC3986文件传输会话发起者的名学
文件传输会话接收者的地址（如SIPURI或TELURI）。如果接收方的地址:同时也是requestURI的一部分，则该地址与requestURI应相同文件传输会话接收者的名字
服务器设置的接收方连接状态。在资源创建的过程中不应在request体内出现
文件的属性集
在RC API RD的定义中，每个会话中只能传输一-个文件，后续的版本中将支持一个会中传输多个文件用户可以在请求中标注特定资源的参数，可以在服务器上创建相关的资源
这个参数应当被提出。让意：这个参数可以用于用户因资源创建时出现错误而导致传输失败时的恢复，避免重复建立相同的文件传输会话。当消息中包含改数据项时，服务器不应改变改数据的值，同时应该将该数据项作为这个资源的代衣。当消息中没有包含该数据项时，服务器不应创建该数据项
自我指涉URL
ResourceURL不应包含在客户端发起的POST请求中，但是当服务器发给绘客户端的通告中包含完整的资源信息时，该参数应被包含在服务器发给客户端的相关的POST请求中。在对任何HTTP请求回复的响应中包含消息体时，ResouTceURL参数应包含在该响应中，同时包含在相关的PUT请求中
表 8 Filelnformation
SDP提供者在SDP中提供的文件属性集，用于从SDP应答者处选择某文件
IR.79 和 RFC5547中定义的文件名、大小、类型和哈希值都可以作为属性被包含在该参数中
SDP定义见IETF RFC2327
表明文件发送方希望的文件处理方式。荐希望文件被自动展现，该值应设为“Render\，否则设为“Attachment”见JETFRFC5547
该参数的默认值为“Atachment\”接收人可理解的对文件的描述（与SDP中的”“i-”行一致，由发起方设置)。IR.79和IETFRFC5547
参数名
fileDate
fileicon
fileURL
参数类型
FileDate
xsd:anyURI
xsd:anyURI
5.3.3FileSelector
表8Filelnfomation（续）
必选/可选
YD/T3188—2016
文件最后被创建，改或读取的时间。见IR79和IETFRFC5547定义传输文件的预览图，接收方可以根据此预览图判断是否接收此文件该参数包含了一个Content-ID URL，RFC2392中定义了可以增加一个消息体，该消息体的MIM正multipartrelated中包含了缩略图信息。见IETFRFC5S47和RCAPIRD的RCAPI-RCFT-001。MIME见IETFRFC2045和IETF RFC 2046
实际文件内容的URL
描述文件名等文件基本信息，具体见表9。表9FileSelector
参数名
参数类型
xsd:string
xsd:string
unsignedLang
HashInfomation
5.3.4 FileDate
必选/可选
文件名称
LIR.79和 IETF RFC5547
注意：在同一个文件传输会话中，文件名是唯一的文件的MIME类型，由类型、\P\个子类型组成。见IR.79和 IETFRFC5547
用8进制表示的文件大小。
见IR.79和IFTFRFC5547
文件的哈希信息，包括哈希算法和哈希值见IR.79和ETF RFC5547
描述文件创建、修改或最后读取的时间，可以包含\cDate\\mDate\和\rDate\的任意组合，具体见表10。
表10FileDate
参数名
参数类型
xsd:dateTimeStamp
xsd:dateTimeStamp
xsddaleTimeStamp
Hashinformation
描述文件的哈希信息，具体见表11。必选/可选
表11 Hashlnformation
参数名
algorithm
参数类型
xsd:string
xsd:bexBinary
必选/可选
文件最后被创建的时间。见IETF RFC5547文件最后被格改的时间。见IETFRFC5547文件最后被读取的时间。见ETF RFC5547描述
使月的哈希算法（当前只支持\sha-1\算法）。见正TFRFC5547文件的哈希值。见IETFRFC5547
YD/T 3188—2016
5.3.6FileTransferSessionlnvitationNotification描述文件传输会话的建立邀请信息，县体见表12表12FileTranisferSessionlnvitationNotification参数名
calbackData
originatorAddress
originatorName
ReceiverAddress
receiverName
FileInformation
参数类型
xsd:string
common:Link
0..unbounded
xsd:anyURI
xsd:string
xsd:anyURI
xsd:string
FileInfomation
5.3.7ReceiverSessionstatus
必选/可选
当“个文件传输通知的订阅被创建时，“callbackData”通过callbackRefcreuce'中的应用被创链见OMA-TS-REST_NetAPICommon
与通知相关的其他资源的链接（例如其他相关的文件传输会话）服务器应当为相关订阅加入一个链接文件传输会话发起者的地址（如SIP URI、TELURI或arURI)文件传输会话发起者的名
文件传输会话接收者的地址（如SIPURI、TELURI或acrURI）文件传输会话接收者的名字
文件的属性集。
在RC APIRD的定义中，每个会话中只能传输个文件，后续的版本中将支持···个会话中传输多个文件描述文件传输会话接收者的信息，具体见表13。表13
ReceiverSessionStatus
参数名
status
参数类型
ReceiverStatus
5.3.8FileTransferEventNotification必选/可选
接收方的状态
为表明接收方接受了文件传输请求，该参应被设为\connect\
描述对只需要传递事件类型而不需要传递特定类型参数的文件传输事件的通知，具体见表14。表14FileTransferEventNotification参数名
callbackData
event'Type
eventDescription
参数类型
xsd:string
common:Link
[o..umbounded]
EveatType
xsd:string
必选/可选
当一个文件传输通知的订阅被创建时，“callbackData”通过‘callbackReference\中的应用被创建见REST_NeiAPI_Common
与通知相关的其他资源的链接（例如其他相关的文件传输会话）
服务器应当为相关订阅加入一个链接，同时应根据
FileTransferEventNotification定义的情况加入链接事件类型
事件的文本描述
5.3.9FileTransferSubscriptionList描述了文件传输通告的订阅者列表，具体见表15。表 15 FileTransferSubscriptionList参数名
fileTransferNotificatio
nSubscription
resourceURL
参激类型
FileTransferNotificationSubscription[0..unbounded]
xsd:anyURI
5.3.10 FileTransferNotificationSubscription必选/向选
文件传输通知订阅者列表
自我指涉URL
YD/T3188—2016
描述了一个与文件传输相关的通告的订阅，例如特定用户的FileTransferEventNotification，FileTransferSessionInvitationNotification、FileTransferFileNotification和FileTransferAcceptanceNotification,其体见表16。
表 16FileTransferNotiticationsubscription参数名
callbackReference
duration
clientCorrelator
resourceURL
参数类型
common:
CallbackReference
xsd:int
xsd:string
xsd:anyURI
必选/可选
5.3.11FileTransferFileNotification描述
客户端的通知地址和可选的callbackDala通知提供的时间（以秒为单位）。如果将这一参数的值设暨为0，那么将根据服务策略确定个默认的时间。如果末设置这参数，通知将直持续到服务策略确定的最大持续时间，除非取消通知订阅
该参数可以由客户端在资源创建时给出，用丁表示客户端希望订阅持续的时间。服务器应该在该参数中回复订阅可以保证有效的时段
用可以在请求中标注特定资源的参数，可以在服务器上创建相关的资源
这个参数可以被提出。注意：这个参数可以用于用户因资源创建时山现错误而导致传输失败时的恢复，避免重复建立相同的文件传输会话
当消息中包舍改数据项时，服务器不应改变改数据的值，同时应当应该将该数据项作为这个资源的代表。当消息中没有包含该数据项时，服务器不应创建该数据项自我指涉URL
ResourceURL不应包含在客户端发起的POST请求中，但足当服务器发给客户端的通告中包含完整的资源信息时，该参数应被包含在服务器发给客户端的相关的POST请求中。在对任何HTTP请求回复的响应中包含消息体时，ResourceURL参数应包含在该响应中，同时包含在相关的PUT请求中描述了携带个文件URL的通知，具体见表17。
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。
中华人民共和国通信行业标准
YD/T3188—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）
文件传输业务
RESTful based service capability open APIFile transfer(OMA-TS-REST NetAPI FileTransfer-V1 0-20140218-D ,RESTful Network APIFile Transfer vl.0,NEQ)2016-10-22发布
中华人民共和国工业和信息化部2017-01-01实施
前言．
1范围，
2规范性引用文件
3术语、定义和缩略语
3.1术语和定义
3.2缩略语，
4文件传输业务概述
5文件传输RESTfulAPI定义
5.1资源概述.wwW.bzxz.Net
5.2枚举类型定义
5.3数据结构定义
5.4流程图.
6接口定义
文件传输订阅管理
创建对一文件传输.
查询和释放对--文件传输.
被叫文件传输请求状态
被叫收到文件传输通知
主叫侧文件传输接受通知
通知文件传输内容链接。
6.8文件传输结束通知..
7错误定义.
7.1、业务异常.
7.2策略异常..
8授权框架
8.1使用Autho4API框架...
8.2“acr:auth'的用法
参考文献．
YD/T3188—2016
YD/T3188-2016
本标准是“基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）”系列标准之：，该系列标推的缔构及名称预计如下：一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）短消息和多媒体销息业务部分：
一基丁表述性状态转移（REST）技术的业务能力开放应用程序接凹（API）点击拨号；
一基丁表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端状态：
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端能力信息：一基·F表述性状态转移（REST）技术的业务能力开放应用程序接口（API）微博业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）搜索业务；
地址本：
一基丁表述性状态转移（REST）技术的业务能力开应用程序接口（AP）一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）文件传输业务；
基表述性状态转移（REST）技术的业务能力开放应用程序接口（API）定位业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）状态呈现业务；
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）聊天业务；
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）用户信息业务：支付业务；
一一基表述性状态转移（REST）技术的业务能力开放应用程序接口（API）一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）视频共享；
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）图片共享；
移动互联网用户
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）上下文感知业务：
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）非结构化补充数据业务。
随着技术和市场的发展，还将根据情况制定后续相关标准。本标准按照GB/T1.1-2009给出的规则起草。本标准使用重新起草法参考OMA-TS-REST NetAPIFileTransfer-V1_0-20140218-D.《基于表述性状态转移（REST）技术的文件传输应用程序接口（API）（OMARESTfulNetworkAPIFileTransfervl.0）》编制，本标准与OMA-TS-REST_NetAPI_FileTransfer-V1_0-20140218-D的一致性程度为非等效。本标准由中国通信标准化协会提出并归口。本标准起草单位：中国移动通信集团公司、中国信息通信研究院、中国联合网络通信集团有限公司、中国电信集团公司。
本标准主要起草人：刘悦、庞亚昆、杨波、赵婷、汪洋。1范圈
基干表述性状态转移（REST）
技术的业务能力开放应用程序接口（AP）文件传输业务
YD/T3188—2016
本标准规定了基于表述性状态转移（REST）的针对文件传输业务的API接口定义，包括接口流程、接门数据结构、接口定义和接口安全要求等。本标准适用于提供文件传输能力开放的应用程序接口。2
规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注月期的版本适用于本文件。凡事不注口期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T 2423-2012
OMA-ER-
Autho4API-V1_ 0
OMA-TS-REST N
etAPI_Common
IETF RFC2045
IETFRFC2046
IETFRFC2327
IETFRFC2392
IETFRFC2616
IETF RFC3261
IETFRFC3966
IETFRFC3986
IETFRFC4627
基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求网络API授权框架 （Authorization Framework for Network APIs）RESTful风格的网络API通用定义1.o版本（Commondefinitionsfor RESTfulNetwork APIs)
多功能英特网邮件扩展功能（MIME）第一部分：英特网消息体格式(Multipurpose Internet Mail Extensions (MIME) Part One: Format of InternetMessage Bodies )
多功能英特网邮件扩展功能（MIME）第二部分：媒体类型（MultipurposeIntemet Mail Extensiops (MIME)Part Two: Media Types)SDP:会话描述协议（SDP:Session Description Protocol）内容标识和消息标识统一资源定位符（Content-IDand Message-IDUniformResource Locators)
超文本传输协议——HTTP/1.1(Hypertext Transfer Protocol --HTTP/1.1)SIP：会话发起协议（SIP:Sessjon InitiationProtocol）电话号码的Tel LIRI（ThetelURIforTelephoneNumbers）统—资源标示符(URI)：—般语法(UniformResourceIdentifier(URI)：GenericSyntax)
Java描述语言对象符号的应用/基于java描述语言的轻量级数据交换格式（Theapplication/jsonMediaTypeforJavaScriptObjectNotation (JSON))1
YD/T 3188—2016
IETF RFC4975
IETFRFC5547
OMA RC API RD
XMLSchemal
XMLSchema2
3术语、定义和缩略语
消息会话中继协议（MSRP）（TheMessageSessionRelayProtocol（MSRP)）用于许可文件传输的会话描述协议提议/回答机制（SessionDescriptionProtocol (SDP) Offer/Answer Mechanism to Enable File Transfer )OMA富通信API需求:OMARCSProfileofRESTfulNetworkAPIsv2.0可扩展标识语言架构第1部分：结构（第二版）（W3CXMLSchemaDefinitionLanguage (XSD) I.1 Part l: Structures Second Edition)可扩展标识语言架构第2部分（W3CXMLSchemaDefinitionLanguage（XSD）1.1 Part 2: Datatypes)
下列术语、定义和缩略语适用丁本文件。3.1术语和定义
表述性状态转移RepresentationalStateTransfer一种针对网络应用的设计和开发方式，指的是：组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性，具体见YD/T2423-2012对REST的定义。3.1.2
Web服务WebService
一种构建应用程序的普遍模型，“可以在任何支持网络通信的操作系统中实施运行：是一种新的web应用程序分支，是自包含、自描述、模块化的应用，可以发布、定位、通过web调用，3.1.3
简单对象访问协议SimpleObjectAccessProtocol一种轻量的、简单的、基于XML的协议，它被设计成在web上交换结构化的和固化的信息。3.2缩略语
下列缩略语适用丁本文件。
Application Prograruming InterfaceHyperText Transfer Protocol
Identitifer
Multipurpose InternetMail ExtensionsRepresentational State TransferSession Description ProtocolUniform Resoure Locator
Extensible Markup Language
应用程序编程接口
超文本传输协议
多用途网际邮件扩充协议
表述性状态转移
会话描述协议
统一资源定位符
扩展标记语言
文件传输业务概述
YD/T 3188—2016
文件传输业务通过开放接口提供文件传输订阅管理、传输和释放文件传输、被叫收到文件传输通知后处理、文件接收通知、文件传输通知、文件结束通知等功能。文件传输RESTfulAPI定义
5.1资源概述
本节概要描述了图片共享的RESTfulAPI所用到的资源。本标准中URL变量“apiVersion”的取值为“vl”，表明该API对应于本标准。URL变量“apiVersion”的语义定义见OMA-TS-RESTNetAPICommon-V1 O。图1为图片共享RESTfulAPI的资源树结构。注：资源树中实线框所示的节点表示该节点有关联的HTTP方法。atserverRooljifiletransfer:tapiversinny'tusurld)/subseriptios
I(subacripliond)0
Busionidy
utalus
图1文件传输RESTfulAPI资源树结构表1给出了本标准中定义的客户端管理文件传输通知订阅的资源概述，其数据类型表示允许的HTTP方法，其中数据结构的具体定义见5.3。见表1。
表1客户端管理文件传输通知订阅基础URL：
全部的对于
文件传输通
知的订阅通
http:/l (serverRoot)
/filetranafer/ (spi
Version)/(userld)
/subscriptions
数据结构
FileTransferSubscriptionList（用于GET操作）
FileTraasferNotification
Subscription（用于POST操作）common:ResourceReference
（POST操作的响应中可选）
读取·个用户
的所有活跃的
文件传输订阅
HTTP方法
创建··个
用户新的
文件传输
DELETE
YD/T 3188—2016
基础URL：
单独的个
对于文件传
输通知的订
阅通知
表1客户端管理文件传输通知订阅（续）http:/ (serverRoot)
/fletransfer/(api
Version)/ (userld)
/subscriptions/ (subs
criptionId)
激据结构
FileTransferNotificationSubscription
客户端管理一对一文件传输资源概述见表2。获得一个与某
“用户相关的
活跃的文件传
输订阅
表2客户端管理一对一文件传输
基础URL：
所有…·对一文
件传输会话
特定的一对一
文件传输会话
会话状态
http:// (serverRoot)
/filetransfer/(api
Vergion)/(userid)
/sessions
/scssions/ [sesion]
/sessions/ (sessionl
dy/status
数据结构
FileTransferSessiounf
ormation（用于POST）
common:ResourceRef
erence（在POST响应
中可选）
FileTransferSessionInf
ormation
ReceiverSessionStatus
检索文件
传输会话
HTTP方法
HTTP方法
创建一个
对一文件传
输会话
接受一对
文件传
输邀请
服务器通知客户端文件传输状态和文件链接输资源概述见表3。表3服务器通知客户端文件传输状态和文件链接资源
通知客户端会话
基础URL：
由客户端指定
当订阅被创建或分
配时由客户端指定
通知客户端文件当订阅被创建或分传输事件
通知户端文件
传输内穿的链接
通知客户端文件
传输被接受
配时由客户端指定
当订阅被创建或分
配时由客户端指定
当订阅被创建或分
配时由客户端指定
数据结构
FileTransferSession
InvitatiocNotification
FileTransferEvent
Notification
FileTransferFile
Notification
FileTransferAcceptance
Notification
HTTP方法
DELETE
停止订阅
并停止相
关的通知
DELETE
取消文件传输
会话邀请（主叫
侧）拒绝文件传
输邀请（被叫
侧）终结会话
DELETE
通知客户端有发给其的
文件传输邀请
通知客户端文件传输事
订阅恢复时通知客户端
文件传输内察的链接
通知客户端接收方同意
了接受文件传输
通知客广端订阅
关系取消
表3服务器通知客户端文件传输状态和文件链接（续）基础URL：
由客户端指定
当订阅被创建或分
配时由客户端指定
5.2枚举类型定义
5.2.1FileDisposition
数据结构
FileTransferSubscriptio
nCancellationNotificati
YD/T 3188—2016
HTTP方法
通知客户端订阅关系被
取消（如超时）
该参数为枚举类型。描述文件传输中的文件展现方式状态值，具体见表4。表4FileDisposition：枚举
枚举值
Render
Attachment
5.2.2 EventType
文件应当被自动展示
文件不应当被自动展示，
该参数为枚举类型。描述通告中可能出现的事件类型，具体见表5。表5EventType：枚举
枚举值
ScssionCancelled
SessionEnded
Deelined
Successful
Failed
Aborted
ReceiverStatus
在发出邀请的阶段，发送方放弃了文件传输文件传输会话被终止
接收方拒绝了文件传输会话邀请文件鼓成功传输
因为出现错误导致文件传输失败发送方终止了文件传输
该参数为枚举类型。描述文件接收者在文件传输中可能的状态值，具体见表6。表6ReceiverStatus：枚举
枚举值
Invited
Connected
Disconnected
5.3数据结构定义
用广被邀请加入文件传输会话
用户已经连接文件传输会话
用户与文件传输会话的链接中断5.3.1FileTransferSessionlnfornation描述文件传输会话的信息，具体见表7。描速
DELETE
YD/T3188—2016
参数名
originatorAddress
originatorName
receiverAddress
receiverName
status
fileInformation
clientCorrelator
resourceURL
参数类型
Xsd:anyURI
xsd:string
xsd:anyURI
xsd:string
ReceiverStatus
FileInfomation
xsd:string
xsd:anyURI
5.3.2Filelnformation
表7FileTransferSessionlnformation必选/可选
描述文件的属性集，具体见表8。参数名
fileSelector
fileDisposition
fleDescription
参数类型
FileSelcctor
IFileDispasition
xsd:string
必选/可选
文件传输会话发起者的地址（如SIPURI或TELURI)。如果发起方的地址同时也是request URI的部分，则该地址与request URl应相同各类URI定义分别见ETFRFC3261、IETF RFC3966及IETFRFC3986文件传输会话发起者的名学
文件传输会话接收者的地址（如SIPURI或TELURI）。如果接收方的地址:同时也是requestURI的一部分，则该地址与requestURI应相同文件传输会话接收者的名字
服务器设置的接收方连接状态。在资源创建的过程中不应在request体内出现
文件的属性集
在RC API RD的定义中，每个会话中只能传输一-个文件，后续的版本中将支持一个会中传输多个文件用户可以在请求中标注特定资源的参数，可以在服务器上创建相关的资源
这个参数应当被提出。让意：这个参数可以用于用户因资源创建时出现错误而导致传输失败时的恢复，避免重复建立相同的文件传输会话。当消息中包含改数据项时，服务器不应改变改数据的值，同时应该将该数据项作为这个资源的代衣。当消息中没有包含该数据项时，服务器不应创建该数据项
自我指涉URL
ResourceURL不应包含在客户端发起的POST请求中，但是当服务器发给绘客户端的通告中包含完整的资源信息时，该参数应被包含在服务器发给客户端的相关的POST请求中。在对任何HTTP请求回复的响应中包含消息体时，ResouTceURL参数应包含在该响应中，同时包含在相关的PUT请求中
表 8 Filelnformation
SDP提供者在SDP中提供的文件属性集，用于从SDP应答者处选择某文件
IR.79 和 RFC5547中定义的文件名、大小、类型和哈希值都可以作为属性被包含在该参数中
SDP定义见IETF RFC2327
表明文件发送方希望的文件处理方式。荐希望文件被自动展现，该值应设为“Render\，否则设为“Attachment”见JETFRFC5547
该参数的默认值为“Atachment\”接收人可理解的对文件的描述（与SDP中的”“i-”行一致，由发起方设置)。IR.79和IETFRFC5547
参数名
fileDate
fileicon
fileURL
参数类型
FileDate
xsd:anyURI
xsd:anyURI
5.3.3FileSelector
表8Filelnfomation（续）
必选/可选
YD/T3188—2016
文件最后被创建，改或读取的时间。见IR79和IETFRFC5547定义传输文件的预览图，接收方可以根据此预览图判断是否接收此文件该参数包含了一个Content-ID URL，RFC2392中定义了可以增加一个消息体，该消息体的MIM正multipartrelated中包含了缩略图信息。见IETFRFC5S47和RCAPIRD的RCAPI-RCFT-001。MIME见IETFRFC2045和IETF RFC 2046
实际文件内容的URL
描述文件名等文件基本信息，具体见表9。表9FileSelector
参数名
参数类型
xsd:string
xsd:string
unsignedLang
HashInfomation
5.3.4 FileDate
必选/可选
文件名称
LIR.79和 IETF RFC5547
注意：在同一个文件传输会话中，文件名是唯一的文件的MIME类型，由类型、\P\个子类型组成。见IR.79和 IETFRFC5547
用8进制表示的文件大小。
见IR.79和IFTFRFC5547
文件的哈希信息，包括哈希算法和哈希值见IR.79和ETF RFC5547
描述文件创建、修改或最后读取的时间，可以包含\cDate\\mDate\和\rDate\的任意组合，具体见表10。
表10FileDate
参数名
参数类型
xsd:dateTimeStamp
xsd:dateTimeStamp
xsddaleTimeStamp
Hashinformation
描述文件的哈希信息，具体见表11。必选/可选
表11 Hashlnformation
参数名
algorithm
参数类型
xsd:string
xsd:bexBinary
必选/可选
文件最后被创建的时间。见IETF RFC5547文件最后被格改的时间。见IETFRFC5547文件最后被读取的时间。见ETF RFC5547描述
使月的哈希算法（当前只支持\sha-1\算法）。见正TFRFC5547文件的哈希值。见IETFRFC5547
YD/T 3188—2016
5.3.6FileTransferSessionlnvitationNotification描述文件传输会话的建立邀请信息，县体见表12表12FileTranisferSessionlnvitationNotification参数名
calbackData
originatorAddress
originatorName
ReceiverAddress
receiverName
FileInformation
参数类型
xsd:string
common:Link
0..unbounded
xsd:anyURI
xsd:string
xsd:anyURI
xsd:string
FileInfomation
5.3.7ReceiverSessionstatus
必选/可选
当“个文件传输通知的订阅被创建时，“callbackData”通过callbackRefcreuce'中的应用被创链见OMA-TS-REST_NetAPICommon
与通知相关的其他资源的链接（例如其他相关的文件传输会话）服务器应当为相关订阅加入一个链接文件传输会话发起者的地址（如SIP URI、TELURI或arURI)文件传输会话发起者的名
文件传输会话接收者的地址（如SIPURI、TELURI或acrURI）文件传输会话接收者的名字
文件的属性集。
在RC APIRD的定义中，每个会话中只能传输个文件，后续的版本中将支持···个会话中传输多个文件描述文件传输会话接收者的信息，具体见表13。表13
ReceiverSessionStatus
参数名
status
参数类型
ReceiverStatus
5.3.8FileTransferEventNotification必选/可选
接收方的状态
为表明接收方接受了文件传输请求，该参应被设为\connect\
描述对只需要传递事件类型而不需要传递特定类型参数的文件传输事件的通知，具体见表14。表14FileTransferEventNotification参数名
callbackData
event'Type
eventDescription
参数类型
xsd:string
common:Link
[o..umbounded]
EveatType
xsd:string
必选/可选
当一个文件传输通知的订阅被创建时，“callbackData”通过‘callbackReference\中的应用被创建见REST_NeiAPI_Common
与通知相关的其他资源的链接（例如其他相关的文件传输会话）
服务器应当为相关订阅加入一个链接，同时应根据
FileTransferEventNotification定义的情况加入链接事件类型
事件的文本描述
5.3.9FileTransferSubscriptionList描述了文件传输通告的订阅者列表，具体见表15。表 15 FileTransferSubscriptionList参数名
fileTransferNotificatio
nSubscription
resourceURL
参激类型
FileTransferNotificationSubscription[0..unbounded]
xsd:anyURI
5.3.10 FileTransferNotificationSubscription必选/向选
文件传输通知订阅者列表
自我指涉URL
YD/T3188—2016
描述了一个与文件传输相关的通告的订阅，例如特定用户的FileTransferEventNotification，FileTransferSessionInvitationNotification、FileTransferFileNotification和FileTransferAcceptanceNotification,其体见表16。
表 16FileTransferNotiticationsubscription参数名
callbackReference
duration
clientCorrelator
resourceURL
参数类型
common:
CallbackReference
xsd:int
xsd:string
xsd:anyURI
必选/可选
5.3.11FileTransferFileNotification描述
客户端的通知地址和可选的callbackDala通知提供的时间（以秒为单位）。如果将这一参数的值设暨为0，那么将根据服务策略确定个默认的时间。如果末设置这参数，通知将直持续到服务策略确定的最大持续时间，除非取消通知订阅
该参数可以由客户端在资源创建时给出，用丁表示客户端希望订阅持续的时间。服务器应该在该参数中回复订阅可以保证有效的时段
用可以在请求中标注特定资源的参数，可以在服务器上创建相关的资源
这个参数可以被提出。注意：这个参数可以用于用户因资源创建时山现错误而导致传输失败时的恢复，避免重复建立相同的文件传输会话
当消息中包舍改数据项时，服务器不应改变改数据的值，同时应当应该将该数据项作为这个资源的代表。当消息中没有包含该数据项时，服务器不应创建该数据项自我指涉URL
ResourceURL不应包含在客户端发起的POST请求中，但足当服务器发给客户端的通告中包含完整的资源信息时，该参数应被包含在服务器发给客户端的相关的POST请求中。在对任何HTTP请求回复的响应中包含消息体时，ResourceURL参数应包含在该响应中，同时包含在相关的PUT请求中描述了携带个文件URL的通知，具体见表17。
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。