YD/T 3081-2016 基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API） 图片共享

ICS33.040

M21YD

中华人民共和国通信行业标准

YD/T3081-2016

基于表述性状态转移（REST)技术的业务

能力开放应用程序接口（API)图片共享

RESTfulbasedservicecapabilutyopenAPI-lmageshare

2016—04一05发布2016-07-01实施

中华人民共和国工业和信息化部发布

YD/T3081-2016

目次

ttS...............................................................................................................................................II

1范围..........................................................................................................................................................................1

2规范性引用文件.......................................................................................................................................................1

3术语、定义和缩略语...............................................................................................................................................1

3.1术语和定义.......................................................................................................................................................1

3.2雜i吾...............................................................................................................................................................2

4图片共享业务概述...................................................................................................................................................3

5图片共享API定义....................................................................................................................................................3

5.1概述...................................................................................................................................................................3

5.2资源概述...........................................................................................................................................................3

5.3数据类型...........................................................................................................................................................5

5.4流程图.............................................................................................................................................................12

6资源详细定义.........................................................................................................................................................16

6.1通用要求.........................................................................................................................................................16

6.2所有图片共享通知订阅的资源.................................................................................................................17

6.3单个图片共享通知订阅的资源................................................................................................20

6.4全部图片共享会话资源...............................................................................................................................22

6.5单个图片共享会话资源...............................................................................................................................27

6.6单个图片共享会话状态资源......................................................................................................................30

6.7图片共享通知资源.......................................................................................................................................32

7错误定义..................................................................................................................................................................40

7.1业务异常........................................................................................................................................................40

7.2策略异常........................................................................................................................................................40

附录A(规范性附录）图片共享API授权.................................................................................................................41

I

YD/T3081-2016

刖目

本标准是“基于表述性状态转移（REST)技术的业务能力开放应用程序接口（AW)”系列标准之

一。该系列标准的结构及名称预计如下：

.一~■基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)短消息和多媒体消息业

务部分；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)点击拨号；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)终端状态；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)终端能力信息；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)微博业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)搜索业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)地址本；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)文件传输业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)定位业务；

—基于表述性状态转移（REST)技术的业务能力开放应用程序接口（AH)状态呈现业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)聊天业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)用户信息业务；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)支付业务；

一基于表述性状态转移（REST)技术的业务能力开放应用程序接口（A；PI)视频共享；

■——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)图片共享；

——基于表述性状态转移（REST)技术的业务能力开放应用程序接口（API)移动互联网用户上下文

感知业务。

随着技术和市场的发展，还将根据情况制定后续相关标准。

本标准按照GB/T1.1-2009给出的规则起草。

本标准使用重新起草法参考OMA-TS-REST_NetAPI_ImageShare-Vl《基于表述性状态转移（REST)

技术的图片共享网络应用程序接口（API)》编制，与OMA-TS-REST_NetAPI_ImageShare-Vl_0—致性程

度为非等效，主要差异如下：

——术语定义，增加了REST的定义，删除了Originator和Receiver的定义；

------删除了“AppUcation/x-www-form-urlencoded请求消息体格式”的要求；

——删除了JSON消息体例子。

——对通知消息的详细定义进行了结构上的调整。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

本标准由中国通信标准化协会提出并归口。

本标准起草单位：中国电信集团公司、中国信息通信研究院、中讯邮电咨询设计院有限公司、中兴

通讯股份有限公司。

本标准主要起草人:吴琳、陈健、周毅、邱芸、崔瑗瑗、吕光绪、黄峥。

YD/T3081-2016

基于表述性状态转移（REST)技术的业务能力

开放应用程序接口（API)图片共享

1范围

本标准规定了基于表述性状态转移（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/jsonMedia

TypeforJavaScriptObjectNotation(JSON))

OMAOMA-ER-Autho4API-Vl_0网络应用程序接口（AF*I)授权框架（AuthorizationFrameworkfor

NetworkAPIs)

OMAOMA-TS-REST_NetAPI_Common-Vl_0基于表述性状态转移（REST)技术的网络应用程序

接口（API)通用定义（CommondefinitionsforRESTfUlNetworkAPIsV1.0)

OMAOMA-TS-REST_NetAPI_ImageShare-Vl_0基于表述性状态转移（REST)技术的图片共享网

络应用程序接口（AF〇(RESTfulNetworkAPIforImageShare)

OMAOMA-TS-REST_NetAPI_NotificationChannel-V1_0基于表述性状态转移（REST)技术的通知

通道网络应用程序接口（API)(RESTfulNetworkAPIforNotificationChannelVI.0)

W3CXMLSchemal可扩展标识语言架构第1部分:结构（第二版）（XMLSchemaPart1:Structures

SecondEdition)

W3CXMLSchema2可扩展标识语言架构第2部分：数据类型（第二版）（XMLSchemaPart2:

DatatypesSecondEdition)

3术语、定义和缩略语

3.1术语和定义

下列术语和定义适用于本文件。

1

YD/T3081-2016

3.1.1

表述性状态转移REpresentationalStateTransfer

一种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则，可以降低开发的复杂性，

提高系统的可伸缩性。[YD/T2423-2012]

3.1.2

通知通道NotificationChannel

一个在客户端请求下创建的通道，用于服务器向客户端发送通知。该通道被表示为一个资源，该通

道为服务器发布通知和客户端通过发送机制接收通知提供不同的方式。

3.1.3

通知服务器NotificationServer

一个具有创建和维护通知通道能力的服务器。

3.14

客户端侧通知URLClient-SideNotificationURL

一个由客户端发布的的HTTPURL。它用于客户端接收和订阅通知。

3.1.5

服务器侧通知URLServer-SideNotificationURL

一个由通知服务器发布的的HTTPURL。它用来标识一个通知通道并可被客户端用于订阅通知。

3.2缩略语

下列缩略语适用于本文件。

ACRAnonymousCustomerReference匿名用户参考

APIApplicationProgrammingInterface应用程序接口

Autho4APIAuthorizationFrameworkforNetworkAPIs网络应用程序接口授权框架

CSCircuitSwitch电路交换

HTMLHyperTextMark-upLanguage超文本标记语言

HTTPHypertextTransferProtocol超文本传输协议

JPEGJointPhotographicExpertsGroup联合图像专家组规范

JSONJavaScriptObjectNotationJavaScript对象表示法

MIMEMultipurposeInternetMailExtensions多用途的网络邮件扩充协议

MSISDNMobileSubscriberISDNNumber移动用户综合业务数字网号码

OMAOpenMobileAlliance开放移动联盟

RCSRichCommunicationsSuite富通信套件

RESTREpresentationalStateTransfer表述性状态转移

SDPSessionDescriptionProtocol会话描述协议

SIPSessionInitiationProtocol会话开始协议

TSTechnicalSpecification技术规范

URIUniformResourceIdentifier统一资源标识符

2

YD/T3081-2016

URLUniformResourceLcator统一资源定位符

XMLextensibleMarkupLanguage可扩展标识语言

XSDXMLSchemaDefinition可扩展标识语言架构定义

4图片共享业务概述

图片共享业务是指两个终端之间交换图片内容的一种服务。该业务为单向一对一，即每个共享会话

发送接收方均为单一用户。

图片共享业务具有以下业务特征：

一支持在进行CS语音呼叫和未进行CS语音呼叫时发起图片共享。

一支持发送方或接收方在呼叫过程中按以下方式停止共享中的图片。

a)由发送方或接收方主动发起；

b)在呼叫过程中当能力不可用时。

一支持在呼叫过程中接收方还未接受时发送方取消共享图片。

一支持在呼叫过程中拒绝共享图片。

一支持在CS呼叫断开时终止图片共享。

一支持发送方或接收方非正常终止图片共享。

一支持在同一呼叫过程中顺序多次共享图片。

图片共享业务详细描述见YD/T1363-2012。

5图片共享API定义

5.1概述

图片共享API支持以下功能：

一管理图片共享事件通知订阅；

一管理图片共享1对1会话，支持在进行CS语音呼叫和未进行CS语音呼叫期间进行图片共享；

一通知客户端图片共享会话邀请、会话接受、文件链接等事件；

一通知客户端有关图像共享会话事件。

此外图片共享API还支持以下功能：

一支持OMAOMA-ER-Autho4API-Vl_0定义的授权框架中使用的范围值；

一支持匿名用户参考（ACR)作为用户标识；

—支持“acr:auth”作为资源URL中用户标识的保留字符。

附录A定义了图片共享API的资源访问控制的授权。

本章节给出了图片共享API的资源和数据结构的定义，同时定义了针对这些资源所允许的操作。

在本标准中“客户端”和“应用”是等同的。

5.2资源概述

本节概要描述了图片共享API所用到的资源。

本标准中URL变量“apiVersion”的取值为“vl”，表明该API对应于本标准。URL变量“apiVersion”的

语义定义见OMAOMA-TS-REST_NetAPI_Common-Vl_0。

3

YD/T3081-2016

图1为图片共享API的资源树结构。

注：资源树中实线框所示的节点表示该节点有关联的HTTP方法。

//{serverRoot}/imageshare/{apiVersion}/{userId}

I___|/status

图1图片共享API的资源结构

下面的表格给出了本标准中定义的资源的概述，其数据类型表示和允许的HTTP方法。

客户端管理图片共享通知订阅的资源概述见表1。

表1图片共享通知订阅资源

基础URL:HTTP方法

http;//{serverRoot}/

资源/数琚结构

imageshare/{apiVer^GETPUTPOSTDELETE

sion}/{user!d}

所有图片共享/subscriptionsImageShareSubscriptio读取所有可用否创建一个新否

通知订阅nList(用于GET)的图片共享通的图片共享

ImageShareNotificatio知订阅通知订阅

nSubscription(用于

POST)

common:ResourceRef

erence(POST的另一

种可选响应消息）

单个图片共享/subscriptions/{subsImageShareNotificatio读取指定的图否否取消订阅，

通知订阅criptionld}nSubscription片共享通知订并中止相

阅信息关的通知

客户端管理图片共享会话的资源概述见表2。

表2图片共享会话管理资源

::基础URL:HTTP方法

http://{serverRoot}/

资源数据结构

imageshare/{apiVersiGETPUTPOSTDELETE

on}/{userId}

所有图片共享/sessionsImageShareSession否否创建一个否

会话Information新的图片

common(Resource共享会话

Reference(optional

alternativeforPOST

response)

4

YD/T3081-2016

表2(续)

基础URL:HTTP方法

http://{serverRoot}/

资源_数据结构\

imageshare/{apiVersi-GETPUTPOSTDELETE

on}/{userId}

单个图片共享/sessions/{sessionId}ImageShareSessionI检索一个有关图片否否取消一个图片共

会话nformation共享会话的信息享会话（对发送

方而言，在接收

方接受之前）或

是拒绝一个图片

共享会话邀请

(对接收方而

言)；

结束已建立图片

共享会话（发送

方或接收方）

图片共享会话/sessions/{sessionId)ReceiverSessionStat否否接受一个否

状态/statusus图片共享

会话邀请

服务器通知客户端图片共享会话状态和图片文件的链接的资源概述见表3。

表3图片共享会话状态和图片文件的链接通知资源

.基础'URL:.HTTP方法

http://{serverRopt}/

资源^据结构:

imageshare/{apiVerGETPUTPOSTDELETE

sion}/{userId}

有关图片共享当订阅被创建或配ImageShareSession否否通知客户端图片共享会否

会话邀请的客置时由客户端指定InvitationNotification话邀请

户端通知

有关图片共享当订阅被创建或配SessionAcceptance否否通知客户端图片共享会否

会话接受的客置时由客户端指定Notification话被接受

户端通知

有关图片共享当订阅被创建或配ImageShareEvent否否通知客户端图片共享会否

会话事件的客置时由客户端指定Notification话事件

户端通知

有关图片文件当订阅被创建或配ImageShareFile否否通知客户端图片文件链否

链接的客户端置时由客户端指定Notification接

通知

有关订阅取消当订阅被创建或配否否否通知客户端订阅取消否

的客户端通知置时由客户端指定

5.3数据类型

5.3.1XML命名空间

图片共享RESTfulAPI数据类型XML命名空间是:

urn:oma:xml:rest:netapi:imageshare:l

5

YD/T3081-2016

本标准中以“xsd”为命名前缀的数据类型引用了W3CXMLSchemal,W3CXMLSchema2中定义的

XML数据类型。“common”命名空间前缀引用了OMAOMA-TS-REST_NetAPI_Common-Vl_0中定义的数

据类型。

5.3.2数据结构

概述

本节对图片共享RESTful网络API中使用的数据结构进行了定义。

6.1中关于“tel”URI、“sip”URI和“acf’URI的声明适用于以下数据结构中包含的用户标识元素。

类型：ImageShareSessionlnformation

ImageShareSessionlnformation数据结构的定义见表4〇

表4ImageShareSessionlnformation数据结构

元素类型::対选描述

originatorAddressxsd:anyURI否图片共享会话发起方的地址（比如：WURI/terURI,'acr-URI)；

当客户端代表会话的发起方，其’originatorAddress’的值应与resourceURL

中的{userid}字段相同（当{userid}是resourceURL的一部分时）

originatorNamexsd:string是发起方的用户名，当存在‘originatorAddress’时，receiveName才可能出现

receiverAddressxsd:anyURI是图片共享会话接收方的地址（比如：Sip'URI，'terURI,'acr'URI);

当在未进行CS语音呼叫时发起的图片共享，在创建图片共享会话资源

时该参数为必选；否则当在进行CS语音呼叫期间发起图片共享，

‘rcceiveAddress’不能出现在请求消息中，服务器可以通过请求消息中的

CallObjectRef得到receiveAddress的值。

当客户端代表会话的接收方，其’receiverAddress’的值应与resourceURL

中的{userid}字段相同（当{userid}是resourceURL的一部分时）

callObjectRefxsd:anyURI是CS语音呼叫对象的$考（链接到该呼叫的接收方)，当在CS语音呼叫

期间发起的图片共享&•，该参数为必选。

当在未进行CS呼叫时发起的图片共享时，该参数不能出现

receiverNamexsd:string是接收方的用户名。当存在‘receiveAddress’时，‘receiveName’才可能出现

statusSessionStatus是图片