YD/T 2977-2015
标准分类号
关联标准
出版信息
相关单位信息
标准简介
YD/T 2977-2015.RESTful based Service Capability Open API一SMS and MMS.
1范围
YD/T 2977本标准规定了基于表述性状态转移(REST) 的针对短消息业务和多媒体消息业务的API接口定义,包括接口流程,接口数据结构,接口定义和接口安全要求等。
YD/T 2977适用于提供短消息业务和多媒体消息能力开放的应用程序接口。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件,仅注日期的版本适用于本文件。凡事不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。
IETF RFC 2316超文本传输 协议1.1 (Hypertext Transfer Protocol - HTTP/1.1)
OMA OMA-ER-Autho4API-V1_ 0网络API授权框架 (Authorization Framework for Network APIs)
OMA OMA-TS ParlayREST_ ShortMessaging-V1_ 1 OMA 中用于短消息REST风格接口定义(RESTful bindings for Parlay X Web Services-Short Messaging)
OMA OMA-TS-ParlayREST _MultiMediaMessaging-V1_1 OMA中用于多媒体消息REST风格接口定义(RESTful bindings for Parlay X Web Services-Multi-media Messaging)
3术语、定义和缩略语
下列术语、定义和缩略语适用于本文件。
3.1术语和定义
3.1.1
表述性状态转移 Representational State Transfer
一种针对网络应用的设计和开发方式,指的是一组架构约束条件和原则,可以降低开发的复杂性,提高系统的可伸缩性。[YD/T 2423-2012]
3.1.2
Web服务 Web Service
标准内容
ICS33.030
中华人民共和国通信行业标准
YD/T2977-2015
基于表述性状态转移(REST)技术的业务能力开放应用程序接口(API)短消息和多媒体消息业务
RESTfulbasedServiceCapabilityOpenAPl-SMSandMMS
2015-10-14发布
2016-01-01实施
中华人民共和国工业和信息化部发布前
2规范性引用文件
3术语、定义和缩略语·
3.1术语和定义
3.2缩略语
4短消息和多媒体消息业务概述
5接口定义说明
数据结构定义和类型定义·
数据结构定义
6.2数据类型定义
7接口流程
短消息接口流程
7.2多媒体消息接口流程…
8接口定义
短消息接口定义
8.2多媒体消息接口定义
9授权框架
使用Autho4API框架.
“acr.auth”的用法.
附录A(规范性附录)响应码要求·附录B(资料性附录)消息样例
参考文献·
YD/T2977-2015
YD/T2977-2015
本标准是““基于表述性状态转移(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给出的规则起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。本标准起草单位:中国移动通信集团公司、中国联合网络通信有限公司、中国信息通信研究院。本标准主要起草人:尼凌飞、王亚晨,管晓培、俞承志,吴伟、刘晓靖。I
1范围
基于表述性状态转移(REST)技术的业务能力开放应用程序接口(APD)短消息和多媒体消息业务
YD/T2977-2015
本标准本标准规定了基于表述性状态转移(REST)的针对短消息业务和多媒体消息业务的API接口定义,包括接口流程,接口数据结构,接口定义和接口安全要求等。本标准适用于提供短消息业务和多媒体消息能力开放的应用程序接口。2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件,仅注日期的版本适用于本文件。凡事不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。IETFRFC2316超文本传输协议1.1(HypertextTransferProtocol-HTTP/1.1))OMAOMA-ER-Autho4API-V1_0网络API授权框架(AuthorizationFrameworkforNetworkAPIs)OMAOMA-TS-ParlayREST_ShortMessaging-V1_1OMA中用于短消息REST风格接口定义(RESTful bindingsfor ParlayXWebServices-Short Messaging)OMAOMA-TS-ParlayREST_MultiMediaMessaging-V1_1OMA中用于多媒体消息REST风格接口定义 (RESTful bindings for Parlay X Web Services-Multi-media Messaging)3术语、定义和缩略语
下列术语、定义和缩略语适用于本文件。3.1术语和定义
表述性状态转移RepresentationalStateTransfer一种针对网络应用的设计和开发方式,指的是一组架构约束条件和原则,可以降低开发的复杂性,提高系统的可伸缩性。[YD/T2423-2012]3.1.2
Web服务WebService
Webservice是一个平台独立的、低耦合的、自包含的、基于可编程的Web的应用程序,可使用开放的XML(标准通用标记语言下的一个子集)标准来描述、发布、发现、协调和配置这些应用程序,用于开发分布式的互操作的应用程序,3.1.3
简单对象访问协议SimpleObjectAccessProtocol一种轻量的、简单的、基于XML的协议,它被设计在Web上交换结构化的和固化的信息。3.1.4
通知通道NotificationChannel
一个在客户端请求下创建的通道,用于服务器向客户端发送通知。该通道被表示为一个资源,为服1
YD/T2977-2015
务器发布通知和客户端通过发送机制接收通知提供不同的方式。3.1.5
通知服务器NotificationServer一个具有创建和维护通知通道能力的服务器。3.1.6
客户端侧通知URLClient-SideNotificationURL一个由客户端发布的的HTTPURL。它用于客户端接收和订阅通知。3.1.7
服务器侧通知URLServer-SideNotificationURL一个由通知服务器发布的的HTTPURL。它用来标识一个通知通道并可被客户端用于订阅通知。3.2缩略语
下列缩略语适用于本文件。
Application Programming InterfaceThe Extensible Markup LanguageSession Initiation Protocol
4短消息和多媒体消息业务概述
应用程序编程接口
可扩展标记语言
会话发起协议
短消息业务通过开放接口提供发送短信、查询接收短信、获取递送报告、订阅短信通知和上行短信通知等功能。
多媒体消息业务通过开放接口提供发送彩信、查询接收彩信、获取彩信递送报告、订阅彩信通知和上行彩信通知等功能。
5接口定义说明
本标准接口基于表述性状态转移技术进行定义,第6章对接口使用的数据结构进行了具体定义,第7章对接口进行了具体定义。
6数据结构定义和类型定义
6.1数据结构定义
DeliveryStatus:枚举。描述短消息/多媒体消息发送状态值,具体见表1。表1DeliveryStatus:枚举
枚举值
DeliveredToNetwork
DeliveryUncertain
Deliverylmpossible
MessageWaiting
DeliveredToTerminal
DeliveryNotificationNot Supported6.2数据类型定义
6.2.1 SmsMessageParam
信息已成功发送到网络使能引擎,使能引擎将在网络中进一步分发发送状态未知,例如信息被传送到另一个网络发送不成功,信息在超时前未能被发送信息仍然在队列中等待发送,此状态为一个临时状态成功发送到终端
不能够提供状态发送报告
描述短消息发送内容,涵盖短消息的相关信息,具体见表2。表2SmsMessageParam
参数名
deliveryStatus
senderAddress
Address
参数名
Message
参数类型
String
[1.. unbounded]
参数类型
String
MmsMessageParam
必选/可选
必选/可选
YD/T2977-2015
on|off。是否需要发送状态报告,on表示需要:ofr表示不需要。若此参数在消息体中不存在,业务平台将默认设置此参数的值为off表示发送者地址
tel::(msisdn1),tel:(msisdn2),,tel:(msisdnn),接收者的列表。若有多个接收者,之间用”\分格。每个接收者用一个URI表示,scheme为tel:(msisdn),其中(msisdn)为此接收者的MSISDN描述
文本短消息内容。最大长度35700字节(长短消息:140字节×255条)描述多媒体消息发送内容,涵盖多媒体消息的相关信息,具体见表3。表3MmsMessageParam
参数名
deliveryStatus
Address
senderAddress
Subject
参数类型
String
[l..unbounded]
String
String
Deliverylnformation
必选/可选
onloff。是否需要发送状态报告,on表示需要:off表示不需要。若此参数在消息体中不存在,业务平台将默认设置此参数的值为offtel:(msisdnl),tel:(msisdn2),.*.tel:(msisdnn),接收者的列表。若有多个接收者,之间用”\分格。每个接收者用一个URL表示,scheme为tel:(msisdn),其中(msisdn)为此接收者的MSISDN表示发送者姓名,最大长度255字节。默认为发送方URI多媒体消息主题。最大长度40字节描述单条短消息/多媒体消息发送状态,具体见表4。表4Deliverylnformation
参数名
Address
deliveryStatus
Description
参数类型
DeliveryStatus
String
6.2.4 DeliverlnformationList必选/可选
表示与发送报告关联目的地址
表示目的地址的发送结果。见6.1附加描述信息。最大长度256字节描述多条短消息/多媒体消息发送状态,具体见表5。表5DeliverlnformationList
参数名
deliveryInformationList
参数类型
DeliveryInformation[o..unbounded]SimpleReference
消息通知接口,具体见表6。
必选/可选
表6SimpleReference
参数名
endpoint
interfaceName
correlator
参数类型
xsd:anyURI
String
String
必选/向选
状态报告列表,见4.2.3
提供接收消息的HTTPURL
接口名。最大长度20字节
接口标识。最大长度128字节
YD/T2977-2015
6.2.6SmsReferenceMessageParam短消息相关消息参数,具体见表7。表7
参数名
senderAddress
smsServiceActivationNumber
message
dateTime
ReceivedSMSList
参数类型
String
dateTime
获得的短消息列表,具体见表8。参数名
receivedSMSList
参数类型
SmsMessageParam
[o..unbounded]
8MmsReferenceMessageParam
SmsReferenceMessageParam
必选/可选
发送者地址
上行短消息接入码
短消息文本内容。最大长度35700字节(长短消息:140字节×255条)
短消息发送时间
表8ReceivedSMSList
必选/可选
多媒体消息参考消息参数,具体见表9。描述
获取的短消息列表,见4.2.1
MmsReferenceMessageParam
参数名
messageldentifier
messageServiceActivation
Number
参数名
senderAddress
subject
message
dateTime
参数类型
String
参数类型
String
String
dateTime
6.2.9 ReceivedMMSList
必选/可选
必选/可选
获取的多媒体消息列表,具体见表10。表10
参数名
receiveMMSList
参数类型
MmsReferenceMessage
Paramlo..unbounded
SMSNotification
短消息通知,具体见表11。
参数名
smsServiceActivationNumber
reference
criteria
参数类型
多媒体消息标识。
如果多媒体消息不带附件,则该值为空。最大长度128字节上行多媒体消息接入码
发送者地址。
多媒体消息主题。最大长度40字节多媒体消息文本消息。最大长度50kB多媒体消息发送时间。格式为“\YYYY-MM-DDThh:mm:ss”ReceivedMMSList
必选/可选
SMSNotification
必选/可选
SimpleReference
String
获取的多媒体消息列表
短消息上行接入码
通知接口定义,见4.2.5
如果配置此参数,则表示该接口只接收以该关键字为前缀的短消息。最大长度20字节6.2.11MMSNotification
多媒体消息通知,具体见表12。参数名
messageServiceActivation
Number
reference
参数名
criteria
参数类型
SimpleReference
参数类型
String
DeliverNotification
消息递送报告,具体见表13。
参数名
requestld
参数名
deliveryInformation
接口流程
7.1短消息接口流程
参数类型
String
参数类型
表12MMSNotification
必选/可选
必选/可选
多媒体消息上行接入码
通知接口定义,见4.2.5
YD/T2977-2015
如果配置此参数,则表示该接口只接收以该关键字为前缀的多媒体消息。最大长度20字节表13DeliverNotification
必选/可选
必选/可选
DeliveryInformation
RESTTOP
业务平台产生的对发送短消息操作的唯一标识。最大长度32字节
状态报告,见4.2.3
RESTTOP
StartSmsNotification
SendSms
GetSmsDeliveryStatus
GetReceivedSms
NotifySmsReception
StopSmsNotification
图1短消息API调用流程
流程中,StartSmsNotification需在NotifySmsReception,StopSmsNotification之前,NotifySmsReception需在StopSmsNotification之前;SendSms需在GetSmsDeliveryStatus之前,其他消息顺序均可调整。7.2多媒体消息接口流程bzxZ.net
YD/T2977-2015
RESTTOP
SendMms
RESTTOP
GetMmsDeliveryStatus
GetReceivedMessages
GetMessage
StartMessageNotification
NotifyMessageReception
StopMessageNotification
图2多媒体消息API调用流程
流程中,StartMessageNotification 需在NotifyMessageReception,StopMessageNotification 之前,NotifyMessageReception需在StopMessageNotification之前:SendMms需在GetMmsDeliveryStatus之前。8接口定义
本接口基于REST风格进行定义。8.1短消息接口定义
8.1.1发送文本短消息(SendSms)8.1.1.1发送文本短消息(SendSms)资源URlhttp://serverRoot)/apiVersion)/sms/rest/textMessage8.1.1.2请求URI变量
请求URI变量,具体见表14。
表14URI变量说明
serverRoot
apiVersion
8.1.1.3响应码
对响应码要求见附录A。
8.1.1.4POST操作
8.1.1.4.1请求
服务器基本URL
API版本
发送文本短消息请求消息,具体见表15。表15发送文本短消息请求消息
HTTP方法
http:/(serverRoot)/(apiVersion)/sms/rest/textMessage
小提示:此标准内容仅展示完整标准里的部分截取内容,若需要完整标准请到上方自行免费下载完整标准文档。