【YD通讯标准】 基于表述性状态转移(REST)技术的业务能力开放应用程序接口(API)图片共享

ICS33.040
中华人民共和国通信行业标准
YD/T3081-2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）图片共享REsTful based service capabiluty open APl-lmage share2016-04-05发布
2016-07-01实施
中华人民共和国工业和信息化部发布前
1范围
2规范性引用文件
3术语、定义和缩略语
3.1术语和定义·
3.2缩略语
4图片共享业务概述·
5图片共享API定义
5.1概述·
资源概述·
数据类型
流程图
6资源详细定义
通用要求·
所有图片共享通知订阅的资源.
6.3单个图片共享通知订阅的资源·全部图片共享会话资源，
单个图片共享会话资源·
单个图片共享会话状态资源
图片共享通知资源
错误定义
业务异常
7.2策略异常+
附录A（规范性附录）图片共享API授权目
YD/T3081-2016
·*·40
YD/T3081-2016
本标准是“基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）”系列标准之一。该系列标准的结构及名称预计如下：基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）短消息和多媒体消息业务部分：
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）点击拨号：基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端状态：基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端能力信息；基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）微博业务：基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）搜索业务：基于表述性状态转移（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-RESTNetAPIImageShare-V1_O《基于表述性状态转移（REST）技术的图片共享网络应用程序接口（API）》编制，与OMA-TS-REST_NetAPI_ImageShare-V1_O一致性程度为非等效，主要差异如下：
术语定义，增加了REST的定义，删除了Originator和Receiver的定义；-删除了“Application/x-www-form-urlencoded请求消息体格式的要求；删除了JSON消息体例子。
对通知消息的详细定义进行了结构上的调整。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。本标准起草单位：中国电信集团公司、中国信息通信研究院、中讯邮电咨询设计院有限公司、中兴通讯股份有限公司。
本标准主要起草人：吴琳、陈健、周毅、邱芸、崔瑷瑷、吕光绪、黄峰。I
HiiKANiKAca
1范围
YD/T3081-2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（APD）图片共享本标准规定了基于表述性状态转移（REST）技术的图片共享能力开放应用程序接口（API)，包括接口的资源定义、资源操作、数据结构、基本流程和安全要求等。本标准适用于提供图片共享能力开放的应用程序接口（API)。2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件YD/T1363-2012富通信业务技术要求内容共享业务YD/T2423-2012基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求GSMAPRDIR.79图片共享互通规范（ImageShareInteroperabilitySpecification）IETFACRdraft匿名用户的匿名用户参考统一资源标识符（TheacrURIforanonymoususers）IETFRFC2616超文本传输协议1.1（HypertextTransferProtocol--HTTP/1.1）IETFRFC3261初始会话协议（SessionInitiationProtocol）IETFRFC3966电话号码的telURI（ThetelURIforTelephoneNumbers）IETFRFC3986统一资源标识符：通用语法（UniformResourceIdentifier（URI）：GenericSyntax）IETFRFC4627JavaScript对象表示法的application/json”媒体类型（Theapplication/jsonMediaType for JavaScript Object Notation （JSON)）OMAOMA-ER-Autho4API-V1_0网络应用程序接口（API）授权框架（AuthorizationFrameworkfonNetwork APIs)
OMAOMA-TS-REST_NetAPI_Common-V1_0基于表述性状态转移（REST）技术的网络应用程序接（API）通用定义（CommondefinitionsforRESTfulNetworkAPIsV1.o）OMAOMA-TS-REST_NetAPI_ImageShare-V1_0基于表述性状态转移（REST）技术的图片共享网络应用程序接口（API）（RESTfulNetworkAPIforImageShare）OMAOMA-TS-RESTNetAPINotificationChannel-V10基于表述性状态转移（REST）技术的通知通道网络应用程序接口（API）（RESTfulNetworkAPIforNotificationChannelV1.0）W3CXMLSchemal可扩展标识语言架构第1部分：结构（第二版）（XMLSchemaPart1：StructuresSecond Edition)
W3CXMLSchema2可扩展标识语言架构第2部分：数据类型（第二版）（XMLSchemaPart2：Datatypes SecondEdition)
3术语、定义和缩略语
3.1术语和定义
下列术语和定义适用于本文件。HiiKAoNiKAca
YD/T3081-2016
表述性状态转移REpresentationalStateTransfer一种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则：可以降低开发的复杂性提高系统的可伸缩性。[YD/T2423-2012]3.1.2
通知通道NotificationChannel
一个在客户端请求下创建的通道，用于服务器向客户端发送通知。该通道被表示为一个资源，该通道为服务器发布通知和客户端通过发送机制接收通知提供不同的方式。3.1.3
通知服务器NotificationServer一个具有创建和维护通知通道能力的服务器。3.1.4
客户端侧通知URLClient-SideNotificationURL一个由客户端发布的的HTTPURL。它用于客户端接收和订阅通知。3.1.5
服务器侧通知URLServer-SideNotificationURL一个由通知服务器发布的的HTTPURL。它用来标识一个通知通道并可被客户端用于订阅通知。3.2缩略语
下列缩略语适用于本文件。
Autho4API
MSISDN
Anonymous Customer ReferenceApplication Programming InterfaceAuthorizationFrameworkforNetworkAPIsCircuit Switch
Hyper Text Mark-up Language
Hypertext Transfer Protocol
Joint PhotographicExperts GroupJavaScript Object Notation
Multipurpose InternetMailExtensionsMobile Subscriber ISDN NumberOpen Mobile Alliance
Rich Communications Suite
REpresentational State TransferSession Description ProtocolSession Initiation Protocol
Technical Specification
Uniform Resource Identifier
匿名用户参考
应用程序接口
网络应用程序接口授权框架
电路交换
超文本标记语言
超文本传输协议
联合图像专家组规范
JavaScript对象表示法
多用途的网络邮件扩充协议
移动用户综合业务数字网号码
开放移动联盟
富通信套件
表述性状态转移
会话描述协议
会话开始协议
技术规范
统一资源标识符
HiiKAoNiKAca
Uniform Resource Lcator
eXtensible Markup Language
XML Schema Definition
4图片共享业务概述
统一资源定位符
可扩展标识语言
YD/T3081-2016
可扩展标识语言架构定义
图片共享业务是指两个终端之间交换图片内容的一种服务。该业务为单向一对一，即每个共享会话发送接收方均为单一用户。
图片共享业务具有以下业务特征：支持在进行CS语音呼叫和未进行CS语音呼叫时发起图片共享。一支持发送方或接收方在呼叫过程中按以下方式停止共享中的图片。a）由发送方或接收方主动发起：b）在呼叫过程中当能力不可用时。支持在呼叫过程中接收方还未接受时发送方取消共享图片。一支持在呼叫过程中拒绝共享图片。支持在CS呼叫断开时终止图片共享。一支持发送方或接收方非正常终止图片共享。一支持在同一呼叫过程中顺序多次共享图片。图片共享业务详细描述见YD/T1363-20125图片共享API定义
5.1概述
图片共享API支持以下功能：
管理图片共享事件通知订阅：
一管理图片共享1对1会话，支持在进行CS语音呼叫和未进行CS语音呼叫期间进行图片共享：一通知客户端图片共享会话邀请、会话接受、文件链接等事件：通知客户端有关图像共享会话事件。此外图片共享API还支持以下功能一支持OMAOMA-ER-Autho4API-V1_0定义的授权框架中使用的范围值：一支持匿名用户参考（ACR）作为用户标识：一支持“acr:auth\作为资源URL中用户标识的保留字符。附录A定义了图片共享API的资源访问控制的授权。本章节给出了图片共享API的资源和数据结构的定义，同时定义了针对这些资源所充许的操作。在本标准中“客户端\和“应用\是等同的5.2资源概述
本节概要描述了图片共享API所用到的资源。本标准中URL变量“apiVersion\的取值为\vl”，表明该API对应于本标准。URL变量\apiVersion\的语义定义见OMAOMA-TS-REST_NetAPI_Common-V1_0。3
HiiKAoiKAca
YD/T3081-2016
图1为图片共享API的资源树结构。注：资源树中实线框所示的节点表示该节点有关联的HTTP方法。/(serverRoot)/imageshare/(apiVersion//userld)/subseriptions
/(subseriptionId)
/sessions
/(sessionld)
/status
图1图片共享API的资源结构
下面的表格给出了本标准中定义的资源的概述，其数据类型表示和允许的HTTP方法。客户端管理图片共享通知订阅的资源概述见表1图片共享通知订阅资源
基础URL：
http://(serverRoot)/
imageshare/(apiVer
sion)/(userld)
所有图片共享」/subscriptions通知订阅
单个图片共享
通知订阅
/subscriptions/(subs
criptionld)
数据结构
ImageShareSubscriptio
nList（用于GET）
ImageShareNotificatio
nSubscription（用于
common:ResourceRef
erence（POST的另
种可选响应消息）
ImageShareNotificatio
nSubscription
客户端管理图片共享会话的资源概述见表2GET
读取所有可用
的图片共享通
知订阅
读取指定的图
片共享通知订
阅信息
表2图片共享会话管理资源
基础URL：
http:// [serverRoot)/
imageshare/(apiVersi
onyfuserld
所有图片共享/sessions
数据结构
Image ShareSessionwww.bzxz.net
Information
common:Resource
Reference (optional
alternative for POST
response)
HTTP方法
创建一个新
的图片共享
通知订阅
HTTP方法
创建一个
新的图片
共享会话
DELETE
取消订阅，
并中止相
关的通知
DELETE
HiiKAoiKAca
基础URL：
http://(serverRoot)/
imageshare/(apiVersi
on/(userld)
单个图片共享/sessions/(sessionld)会话
数据结构
表2（续）
ImageShareSessionl
nformation
图片共享会话/sessions/(sessionId）ReceiverSessionStat
/status
检索一个有关图片
共享会话的信息
HTTP方法
服务器通知客户端图片共享会话状态和图片文件的链接的资源概述见表3。表3图片共享会话状态和图片文件的链接通知资源基础URL：
有关图片共享
会话邀请的客
户端通知
有关图片共享
会话接受的客
户端通知
有关图片共享
会话事件的客
户端通知
有关图片文件
链接的客户端
http://(serverRoot)/
imageshare/ apiVer
sion/userld)
当订阅被创建或配
置时由客户端指定
当订阅被创建或配
置时由客户端指定
当订阅被创建或配
置时由客户端指定
当订阅被创建或配
置时由客户端指定
有关订阅取消
当订阅被创建或配
的客户端通知置时由客户端指定5.3数据类型
5.3.1XML命名空间
数据结构
ImageShareSession
InvitationNotification
SessionAcceptance
Notification
ImageShareEvent
Notification
ImageShareFile
Notification
图片共享RESTfulAPI数据类型XML命名空间是：urn:oma:xml:rest:netapi:imageshare:lGET
YD/T3081-2016
DELETE
取消一个图片共
享会话（对发送
方而言，在接收
方接受之前）或
是拒绝一个图片
共享会话邀请
（对接收方而
言）：
结束已建立图片
共享会话（发送
方或接收方）
接受一个香
图片共享
会话邀请
HTTP方法
通知客户端图片共享会
话邀请
通知客户端图片共享会
话被接受
通知客户端图片共享会
话事件
通知客户端图片文件链
通知客户端订阅取消
DELETE
TiiKAoNiKAca
YD/T3081-2016
本标准中以xsd”为命名前缀的数据类型引用了W3CXMLSchemal，W3CXMLSchema2中定义的XML数据类型。“common\命名空间前缀引用了OMAOMA-TS-REST_NetAPI_Common-V1_0中定义的数据类型。
5.3.2数据结构
5.3.2.1概述
本节对图片共享RESTful网络API中使用的数据结构进行了定义。6.1中关于“tel\URI、“sip\URI和“acr\URI的声明适用于以下数据结构中包含的用户标识元素。2类型：ImageShareSessionlnformation5.3.2.2
ImageShareSessionInformation数据结构的定义见表4。表4
originatorAddress
originatorName
receiverAddress
callObjectRef
receiverName
status
fileInformation
fileURL
clientCorrelatoi
xsd:anyURI
xsd:string
xsd:anyURI
xsd:anyURI
xsd:string
SessionStatus
FileInformation
xsd:anyURI
xsd:string
ImageShareSessionlnformation数据结构可选
图片共享会话发起方的地址（比如：‘sip'URI，tel\URI,acr'URI)：当客户端代表会话的发起方，其originatorAddress'的值应与resourceURI中的（userId字段相同（当（userld是resourceURL的一部分时）发起方的用户名，当存在“originatorAddress时，receiveName才可能出现图片共享会话接收方的地址（比如：‘sip\URI，tel'URI，acr'URI)：当在未进行CS语音呼叫时发起的图片共享，在创建图片共享会话资源时该参数为必选：否则当在进行CS语音呼叫期间发起图片共享，‘receiveAddress\不能出现在请求消息中，服务器可以通过请求消息中的CallObjectRef得到receiveAddress的值。当客户端代表会话的接收方，其'receiverAddress'的值应与resourceURL中的(userld)字段相同（当(userld)是resourceURL的一部分时）CS语音呼叫对象的参考（链接到该呼叫的接收方），当在CS语音呼叫期间发起的图片共享时，该参数为必选。当在未进行CS呼叫时发起的图片共享时，该参数不能出现接收方的用户名。当存在‘receiveAddress\时，“receiveName'才可能出现图片共享会话状态，由服务器设置。发起方客户端发起图片共享会话创建的请求消息中不能出现该参数共享文件的信息
文件存储URL地址：
如果该参数包含在创建图片共享会话资源的请求消息中，则表明文件内容不包含在请求消息中，但可通过fileURL获取该文件。当该参数不包含在创建图片共享会话资源的请求消息中，则文件内容将包含在请求消息中，此时HTTP请求的消息体的Content-type应为multipart/form-data\，具体见5.3.5的定义在客户端创建资源时，用于客户端标记这个特定的资源表示。这个字段应该包含在请求消息中。注：该参数可充许客户端在资源创建阶段中从通讯故障中恢复过来，从而避免重复图片共享会话创建过程。如果客户端请求中存在这个参数，则服务器不应改变它的值，而且应该将其作为资源表达的一部分：
如果客户端请求中不存在这个参数，则服务器不应产生这个参数的值iiKAoNiKAca
resourceURL
xsd:anyURI
表4（续）
自身URL。
YD/T3081-2016
本参数不能出现在客户端发送的POST方法的请求消息中但应包含在服务器向客户端发送的POST方法的通知消息中（当通知消息中携带完整的资源信息时）：本参数还应出现在使用PUT方法的请求消息中和任何具有消息体的HTTP方法的响应消息中个具有ImageShareSessionInformation数据类型的imageShareSessionInformation根元素允许出现在请求和/或响应的消息体中。
遵循OMAOMA-TS-RESTNetAPICommon-V1O中规定，clientCorrelator用于错误恢复以及客户端内部使用的目的。服务器在创建资源时不需要以任何形式使用clientCorrelator的值。该字段的值的产生的建议见OMAOMA-TS-RESTNetAPICommon-V1O。5.3.2.3类型：FilelnformationFileInformation数据结构的定义见表5。表5
fileSelector
fileDescription
FileSelector
xsd:string
5.3.2.4类型:FileSelector
FileSelector数据结构的定义见表6。Filelnformation数据结构
xsd:string
xsd:string
xsd: unsignedLong
HashInformation
类型:Hashlnformation
HashInformation数据结构的定义见表7。文件属性元组：
SDP发送端将其包含在SDP中用来在SDP接收端决定是否接受该文件。
包括文件名、大小、类型及hash值，见IETFRFC5547文件描述（对应SDP中\i=行），可由发送端设置。见GSMAPRDIR.79和IETFRFC2327
FileSelector数据结构
文件名
文件的MIME类型，由type'/'subtype组成（如image/jpeg)。见IETFRFC2045
文件的大小（用字节数表示）
文件散列信息，其中包括散列算法和散列值表7Hashlnformation数据结构
algorithm
xsd:string
xsd:hexBinary
使用的散列算法（目前只支持sha-1算法）文件的散列值
5.3.2.6类型:ImageShareSessionlnvitationNotificationImageShareSessionInvitationNotification数据结构的定义见表8。7
YD/T3081-2016
callbackData
originatorAddress
originatorName
receiverAddress
callObjectRef
receiverName
fileInformation
表8ImageShareSessionlnvitationNotification数据结构类型
xsd:string
common:Link
[0..unbounded]
xsd:anyURI
xsd:string
xsd:anyURI
xsd:anyURI
xsd:string
Filelnformation
“callbackData”元素包含了创建通知订阅时客户端提供的‘callbackReference”中的callbackData元素的信息。见 OMAOMA-TS-REST_NetAPI Common-V1_0和该通知相关的资源的链接。
该参数应包含
ImageShareSessionInvitationNotification相关的链接，见表23的定义
另外还应包含通知订阅相关链接图片共享会话发起方的地址（比如：‘sip'URI，telURI，'acrURD
当客户端代表会话的发起方，其'originatorAddress的值应与resourceURL中的（userld)字段相同（当（userld)是resourceURL的一部分时）
发起方的用户名，当存在‘originatorAddress时，“originatoName'才可能出现
图片共享会话接收方的地址（比如：‘sip'URItel\URI，'acrURD
当在未进行CS语音呼叫时发起的图片共享，该参数为必选；否则在进行CS语音呼叫期间发起图片共享，“receiveAddress'为可选
当客户端代表会话的接收方，其'receiverAddress的值应与resourceURL中的(userld)字段相同（当(userld)是resourceURL的一部分时）
CS语音呼叫对象的参考（链接到该呼叫的接收方），当在CS语音呼叫期间发起的图片共享时，该参数为必选服务器可通过receiverAddress获取对应CS呼叫的callObjectRef\
在未进行CS语音呼叫时发起图片共享，该参数不能出现
接收方的用户名。当
当存在‘receiveAddress时，
“receiveName才可能出现
图片文件的属性
个具有ImageShareSessionInvitationNotification数据类型的imageShareSessionInvitationNotification根元素允许出现在通知请求消息体中。5.3.2.7类型:ReceiverSessionStatusReceiverSessionStatus数据结构的定义见表9。表9ReceiverSessionStatus数据结构元素
status
SessionStatus
图片共享会话状态。
当指示接收方接受图片共享邀请时，该元素的值应设置为\Connected'
YD/T3081-2016
一个具有ReceiverSessionStatus数据类型的receiverSessionStatus根元素允许出现在请求消息体中。5.3.2.8类型:ImageShareEventNotificationImageShareEventNotification数据结构的定义见表10表10
callbackData
eventType
eventDescription
xsd:string
common:Link
[o..unbounded]
EventType
xsd:string
ImageShareEventNotification数据结构数据结构可选
‘callbackData”元素包含了创建通知订阅时客户端提供的callbackReference”中的callbackData'元素的信息，见OMAOMA-TS-REST NetAPI Common-V1 0和该通知相关的资源的链接。该参数的应包括ImageShareEventNotification相关的链接，见表23的定义。另外服务器还应包含通知订阅相关链接事件类型
事件描述
一个具有ImageShareEventNotification数据类型的imageSharetEventNotification根元素允许出现在通知请求消息体中。
5.3.2.9类型:ImageShareAcceptanceNotificationImageShareAcceptanceNotification数据结构的定义见表11。表11
callbackData
receiverAddress
callObjectRef
receiverName
receiverSessionstatus
xsd:string
common:Link
[O..unbounded]
xsd:anyURI
xsd:anyURI
xsd:string
ImageShareAcceptanceNotification数据结构可选
ReceiverSessionstatus
“callbackData'包含了创建图片共享通知订阅时客户端提供的callbackReference'中的callbackData元素的信息，见OMAOMA-TS-REST_NetAPI_Common-V1_0和该通知相关的其他资源的链接，见表23的定义。服务器还应包含通知订阅相关的链接图片共享会话接收方的地址（比如：‘sip’URI，“te'URI，‘acrURI)：
当在未进行CS语音呼叫时发起图片共享，该参数为必选：当在进行Cs语音呼叫期间发起图片共享，“receiveAddress为可选
CS语音呼叫对象的参考（链接到该呼叫的接收方）。当在进行CS语音呼叫期间发起的图片共享时，该参数为必选在未进行CS语音呼叫时发起图片共享，该参数不能出现接收方的用户名。当存在receiveAddress'时，“receiveName\才可能出现
图片共享会话状态。
当指示接收方接受图片共享邀请时，该元素的值应设置为\Connected
一个具有imageShareAcceptanceNotification数据类型的ImageShareAcceptanceNotification根元素允许出现在通知请求消息体中。
5.3.2.10类型：ImageShareFileNotificationImageShareFileNotification数据结构的定义见表12。9
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。