YD/T 3189-2016
基本信息
标准号： YD/T 3189-2016
中文名称：基于表述性状态转移 (REST) 技术的业务能力开放应用程序接口 (API) 状态呈现业务
标准类别：通信行业标准(YD)
标准状态：现行
出版语种：简体中文
下载格式：.zip .pdf
相关标签： 基于 表述 状态 转移 技术 业务 能力 开放 应用 程序接口
标准分类号
关联标准
出版信息
相关单位信息
标准简介
YD/T 3189-2016.RESTful based service capability open API-presence.
1范围
YD/T 3189规定了基于表述性状态转移(REST)的针对状态呈现业务的API接口定义，包括接口流程，接口数据结构，接口定义和接口安全要求等。
YD/T 3189适用于提供状态呈现能力开放的应用程序接口。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。
YD/T 2423-2012 基于表述性状态转移(REST)技术的电信业务能力开放平台技术要求
ISO ISO.3166 国家编码(Country Codes)
OMA OMA-ER-Autho4 网络API授权框架(Authorization Framework for Network APIs)
API-V1_ _0]
OMA OMA-TS-REST_RESTful风格的网络API通用定义1.0版本
NetAPI_ Common RESTful风格的网络API通用定义1.0版本( Common definitions for RESTful Network APIs)
OMA OMA-ERP-REST_ RESTful风格的通知通道网络API1.0版本(RESTful Network API for NetAPI_ NotificationChannel Notification Channel )
IETF RFC2616 超文本传输协议一HTTP/1.1 (Hypertext Transfer Protocol - HTTP/1.1)
IETF RFC3261 SIP:会话发起协议(SIP: Session Initiation Protocol)
IETF RFC3966 电话号码的Tel URI (The tel URI for Telephone Numbers)
IETF RFC3986 统一资源标示符(URI) :一般语法( Uniform Resource Identifer(URI) : Generic Syntax)
1范围
YD/T 3189规定了基于表述性状态转移(REST)的针对状态呈现业务的API接口定义，包括接口流程，接口数据结构，接口定义和接口安全要求等。
YD/T 3189适用于提供状态呈现能力开放的应用程序接口。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。
YD/T 2423-2012 基于表述性状态转移(REST)技术的电信业务能力开放平台技术要求
ISO ISO.3166 国家编码(Country Codes)
OMA OMA-ER-Autho4 网络API授权框架(Authorization Framework for Network APIs)
API-V1_ _0]
OMA OMA-TS-REST_RESTful风格的网络API通用定义1.0版本
NetAPI_ Common RESTful风格的网络API通用定义1.0版本( Common definitions for RESTful Network APIs)
OMA OMA-ERP-REST_ RESTful风格的通知通道网络API1.0版本(RESTful Network API for NetAPI_ NotificationChannel Notification Channel )
IETF RFC2616 超文本传输协议一HTTP/1.1 (Hypertext Transfer Protocol - HTTP/1.1)
IETF RFC3261 SIP:会话发起协议(SIP: Session Initiation Protocol)
IETF RFC3966 电话号码的Tel URI (The tel URI for Telephone Numbers)
IETF RFC3986 统一资源标示符(URI) :一般语法( Uniform Resource Identifer(URI) : Generic Syntax)
标准图片预览
标准内容
ICS33.030
中华人民共和国通信行业标准
YD/T3189—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）状态呈现业务RESTful based service capability open API-presence( 0MA-ERP-REST NetAPI Presence-V1 0-20130212-C,RESTful Network API for Presence 1.0,NEQ)2016-10-22发布
中华人民共和国工业和信息化部2017-01-01实施
范围、
2规范性引用文件.
3术语、定义和缩略语。
3.1术语和定义，
3.2缩略语.
4状态呈现业务概述..
5状态呈现业务RESTfulAPI定义
资源概述
枚举类型定义，
5.3数据结构定义，
接口流程.
6接口定义
创建和获取状态呈现源信息
创建和获取观看者订阅信息
观看者通知bzxz.net
创建和获取状态呈现订阅信息
状态呈现通知，
获取和更新状态呈现源
创建/获取授权规则
创建/更新特定授权规则
错误定义
业务异常.
策略异常.
8授权框架
使用Autho4API框架
范围值
‘acrauth'的用法
参考文献.
YD/T31892016
YD/T3189—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）移动互联网用户_上下文感知业务：
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）非结构化补充数据业务。
随着技术和市场的发展，还将根据情况制定后续相关标准。本标准按照GB/T1.1—2009给出的规则起草。本标准使用重新起草法参考OMA-ERP-REST_NetAPI_Presence-V1_0-20130212-C.《基于表述性状态转移（REST）技术的显现业务应用程序接口（API）（OMARESTfulNetworkAPIforPresence1.0）》编制，本标准与OMA-ERP-REST_NetAPlPrcsencc-V1_0-20130212-C的一致性程度为非等效。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。本标准起草单位：中国移动通信集团公司、中国信息通信研究院、中国联合网络通信有限公司、中国电信集团公司。
本标准主要起草人：刘悦、庞亚昆、杨波、赵婷、汪洋。I
1范围
YD/T 3189—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（APD）
状态呈现业务
本标准规定了基于表述性状态转移（REST）的针对状态呈现业务的API接[1定义，包括接L1流程，接口数据结构，接山定义和接山安全要求等。本标准适用于提供状态呈现能力开放的应用程序接口。2 规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T2423—2012
ISO ISO.3166
OMA OMA-ER-Auth04
API-VI_01
OMA OMA-TS-REST
NetAPI_Common
OMAOMA-ERP-REST
NetAPINotificationChannel
IETF RFC2616
IETFRFC3261
IETF RFC3966
1ETFRFC3986
IETF RFC4627
W3C W3C_URLENC
W3C XMLSchemal
基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求国家编码（CountryCodes）
网络API授权框架（AuthorizationFrameworkforNetworkAPIs）RESTful风格的网络API通用定义1.0版本RESTful风格的网络API通用定义1.o版本（CommondefiaitionsforRESTful Network APIs )
RESTful风格的通知通道网络API1.0版本（RESTfulNetworkAPIforNotification Channel)
超文本传输协议——HTTP/1.1 (Hypertext Transfer Protocol -- HTTP/1,1)SIP：会话发起协议(SIP:Session Initiation Protocol)电话号码的TelURI（ThetelURIforTelephoneNumbers）统一资源标示符（URI）：一般语法（Uniform Resource Identifier(URI) : Generic Syntax)
Java描述语言对象符号的应用/基于java描述语言的轻量级数据交换格式(The application/json Media Type for JavaScript Object Notation (JSON))超文本标记语言4.01规范：17.13.4章节：表单内容类型（HTMIL，4.01Specification, Section 17.13.4 Form content types, The World Wide WebConsortium)
可扩展标识语言架构第1部分：结构（第一版）（W3CXMLSchema1
YD/T3189—2016
W3C XMLSchema2
3术语、定义和缩略语
3.1术语和定义
Definition Language(XSD)1.1Part l:Structures Second Edition)可扩展标识语言架构第2部分（W3CXMLSchemaDefinitionLanguage（XSD）1.1Part2：Datatypes）下列术语和定义适用于本文件。3.1.1
表述性状态转移RepresentationalStateTransfer：种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性，具体见《基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求》对REST的定义。
Web 服务Web Service
一种构建应用程序的普遍模型,可以在任何支持网络通信的操作系统中实施运行；是一种新的web应用程序分支，是自包含、自描述、模块化的应用，可以发布、定位、通过web调用。3.1.2
简单对象访问协议SimpleObjectAccessProtocol种轻量的、简单的、基于XML的协议，它被设计成在WEB上交换结构化的和固化的信息。3.2缩略语
下列缩略语适用丁本文件。
ApplicationProgrammingInterfaceHyperText Transfer Protocol
Identitifer
Representational StateTransferUaiform Resoue Locator
Extensible Markup Language
4状态呈现业务概述
应程序编程接口
超文本传输协议
表述性状态转移
统资源定位符
扩展标记语言
状态呈现业务通过开放接口提供创建状态呈现信息源、订阅者、观看者，创建、呈现订阅信息和通知等功能。
5状态呈现业务RESTfulAPI定义
5.1资源概述
本节概要描述了图片共享的RESTfuLAPI所用到的资源。YD/T 31892016
本标准中URL变量\apiVersion”的取值为“v1\表明该API对应于本标准。URL变量“apiVersion”的语义定义见OMA-TS-RESTNetAPICommon-Vl_O。图1为图片共享RESTfulAPI的资源树结构。注：资源树中实线握所示的节点表示该节点有关联的HTTP方法。na
L(userin)
tresencescairces
treenasoxreiai
iesnurelkelipah]
pursrstent
12ortenl
jwaichers
auihorizaho
oomeiy
ipxisil ucn
watcrer.Jserd,
Trulee
ipresenceContacts
SuusvrltlyUsarlogy
IpresenceLists
caesenceLi6tar
prexe\cuCoutsGurile
r(cresert yuserlds
xerietos
[ResuuraRueh
ruieliag
Mcantentid]
walcheiSubscripirulis
H rsubsreluonldy
peenesscrpiane
Ppresentyuger ay ]
[isubeclweionle]
rhe asris, is ir inerresery rakLhe useria: isir he wahetor role gisrldg isnoheleerPrmty
Tielarenairn lor Ighl wright reto.etprekenceLletsubecrpiois
Licveaence_mie
rsubscriplicndCk
图1状态呈现业务RESTfulAPI资源结构3
YD/T 3189—2016
表1给出了本标准中定义的呈现者管理自身呈现信息的资源概述，其数据类型表示和允许的HTTP方法。其中数据结构的具体定义见5.3节。呈现者管理自身呈现信息
基础URL：
呈现源
特定皇现源
特定是现源
持久化呈现
特定持久化
皇现源的鳳
http:// [serverRoot)/
presence/ (apiVersion)
(userld)/presence
Sources
/ (userld)/presence
Sources/(presence
Sourceldi
(userld)/presence
Sources(presence
SorcedResource
RelPath]
/(userid)/presence
Sources/persistent
/(userld)/presence
Sources/persistent
[ResourceRelPath]
数据结构
PresenceSourceList
(用于GET) Presence
Source（用于POST)
common:ResourceRef
erence（在POST响应
中条件可选）
PresenceSource（用于
PUT/GET)
数据结懋相当于呈现
源中说我U措性
的一个元题
(用PUT/GET)
PresenceSource
数据结构相当于呈瑰
源中由销求URL指出
的一个元素
（用于PUT/GET）
呈现者管理自身内容的资源概述见表2。GET
获得所有与
某‘呈现者
相关的星现，
获得某一呈
现者的特定
是现源的呈
现信息
注：观看者不
应使用这一
获得一个特
定呈现源的
特定基现属
性的值
获得一个呈
现者的持久
化的垦现源
的信息
获得一个特定
持久化是现源
的特定呈现属
性的值
表2呈现者管理自身内容
基础URL:
http://(serverRoot)
presence/ [apiVersion]
垦现者内容
fuserldfcontent
特定呈现体userldycontent/
(contentId)
数据结构
ContentList
在意MIME内
获与呈现体相关的所
有内容标识
获得一个垦现体的一个特
定内容（例如~个图片）
注：观看者不应使用这
一操作
HTTP方法
更新某一呈现
者的特定呈现
源的品现信息
创建或更新一
个特定呈现源
的个呈现属
创建更新
个呈现者的持
久化的呈现源
的信息
创建或更新一
个特定持久化
呈现源的一个
是现属性
HTTP方法
创建或替换服
务器上一个堂
现体的一个特
定内容
为是现
者创建
现资源
DELETE
删除某一呈
现者的特定
呈现源的呈
现信息
删除一个特
定呈现源的
“-个呈现属
删除．个望
现者的持久
化的垦现
的信息
删除一个特
定持久化呈
现源的一个
早现属性
DELETB
从服务器上
删除一个特
定内容
导现者头像
基础URL：
http:// (serverRoot)
presencel (apiVersian)
/(userld)/content/port
raiticon
表2呈现者管理自身内容（续）
数据结构
在意与…个
图片相关的
M内容
获得一个早现体的头像
图标注：观看者不应使
用这一操作
呈现者检索观看者感兴趣的信息资源概述见表3。HTTP方法
创建或替换
服务器上一
个呈现体的
头像图标，同
时服务器更
新这个图标
的链接
表3呈现者检索观看者感兴趣的信息基磁URL：
观看者列表
特定观看者
http://(serverRoot))
presence/ (apiVersion)
/ [userld) /watchers
userld] /watchers/ [wat
cherUserld!
数据结构
WatcherList
Watcher
HTTP方法
获得对呈现者的呈现信
息，包含当前的订阅状态，
感兴趣的观察者列表
默得一个特定观看者当前
的订阅状态和订阅属性
呈现者管理观看者对呈现信息的访间的资源概述见表4。表4呈现者管理观看者对呈现信息的访问基础URL：
鉴权规则
特定的整权
特定的鉴权
规则参数
http:/f (serverRoot)!
presence [apiVersion)
/(userld) /autharization
frules
/ userld]/authorization
frules/truleld!
fuserId)fauthorization
frulestfruleldResour
ceRelPatb
数据结构
（用于
RuleList
Rule（用于POST)
common:ResourceR
eference（在POST响
应中条件可选）
Rule（用于PUT/
散据结构相当丁星
现源中由请求URL
指出的一个元
(用于 PUT/GET)
获得所有鉴
权规则
HTTP方法
获得一个特「更新一个特
定的鉴权规
获得一·个特
定鉴权规则
的特定规则
定的鉴权规
创建或更新
个特定鉴
权规则的特
定规参数
YD/T 31892016
创建一个
新的鉴权
DELETE
从服务器上
删除一个皇
现体的头像
DELETE
DELETE
删除一个特
定的鉴权规
删除个特
定鉴权规则
的特定规划
YD/T 31892016
观看者从现者或垦现者列表中检索呈现信息的资源概述见表5。表5观看者从呈现者或呈现者列表中检索呈现信息基础URL：
个单独呈
现体的观察
者望现俯息
观看者的特
定呈现属性
呈现体列表
的观察者呈
现信息
http:// [serverRoot)?
presence/ (apiVersion)
I fuserld)/presence
Contacts/(presentity
Userldy
(userid)/presence
Cantacts/(presentity
Userld]/[ResourceRe]
/ (useriId)/presence
Lists/ (presezceListid)
数据结构
PresenceContact
数据结构相当于呈现
联系结构中由请求
URL指出的一个元索
PresenceList
观看者从呈现者中检索内容的资源概述见表6。GET
从··个呈现体获得
符合的皇现信息
江：获得的垦现信息
可包含从多个显现
源获得的呈现信息
获得一个呈现体的
特定呈现属性
获得特定呈现列表
中所有呈现体的呈
现信息
表6观看者从呈现者中检索内容
基础URL：
观看者内穿
http:// (serverRoot)/
presence/(apiVersion)
/(userld)/PresenceConta
ctsContenu (presentityUs
erId]/[contentId]
数据结构
年章MIME内容
获得一个特定呈现
者的·个特定内容
（例如一-张图片）
用户（包括观看者和呈现者）检索自身的订阅关系的资源概述见表7。HTTP方法
HTTP方法
表7用户（包括观看者和呈现者）检索自身的订阅关系基础URL：
所有订阅
http://[serverRoot))
presence/ (apiVersion)
/fuserld)fsubscriptions
数据结构
SubscriptionList
HTTP方法
获得。个用户的所有订阅
呈现者在观看者信息变化时管理通知的订阅的资源概述见表8。6
DELETE
DELETE
DELETE
所有观看
者的订阅
特定的观
看者订阅
表8呈现者在观看者信息变化时管理通知的订阅基础URL：
http://(serverRoot)/prese
ace/(apiVersion）
fuserld) /subscriptions/
watchersSubscriptions
/(userId)/subscriptions/
watchersSubscriptions/
[subscriptionld
数据结构
WatchersSubseription
List（用于 GET)
WatchersSubscription
（用于POST）
common:ResourceRef
erence（在POST响应
中条件可选）
WatchersSubscription
获得与观看者列
表相关的所有订
在管按着列表变
化时获得一个特
定的订阅
服务器向呈现者通知观看者订阅状态变化的资源概述见表9。HTTP方法
更新用户
列表的一
个特定订
表9服务器向呈现者通知观看者订阅状态变化资源
基础URL：
由客户端指定
观着者通
当观看者信息列表被创
建或者在配置过程中订
阅通知由变化时由客广
端确定
数据结构
WatchersNotification
YD/T 31892016
在观看者
列表变化
时创建—
个订阅通
HTTP方法
当呈现者信息变化时观看者管理自身通知的订阅的资源概述见表10。GET
向客户端通知
观看者订阅状
态的变化
表10当呈现者信息变化时观看者管理自身通知的订阅基础URL：
所有是现
一个单一
呈现体的
呈现订阅
特定的呈
现订阅
http:// (serverRoot)/
preseace/ (apiVersion)
/(userld) /subscriptions/
prescaceSubscriptions
/ userld]/subscriptions
presenceSubscriptions/
(presentityUserId)
ffuserld/subscriptions!
presenceSubsoriptions/
f presentityUserld)?
fsubscriptionld?
数据结构
PresenceSubscription
PresenceSubscription
List（用于GET）
PresenceSubscription
（用于POST)
common:ResourceRef
erence（在POST响
应中条件可选）
PresenceSubscription
（用于GET/PUT）
获得所有呈
现者的呈现
信息的所有
活跃的订阅
获得．个特
定呈现者的
呈现信息的
所有活跃的
获得现信
息的一个特
定活跃订阅
HTTP方法
更新星现信
息的特定订
在“个特定
的呈现体的
呈现信息变
化时创建一
个订阅通知
DELETE
终止用户
列表的一
个特定订
DELETE
DELETE
终结呈现
信息的特
定订阅
YD/T3189—2016
服务器向观看者通知呈现者信息变化的资源概述见表11。表11服务器向观看者通知呈现者信息变化资源
呈现通知
基础URL:
由客户端指定
当观看者倍息列表被
创建或者在配置过程
中订阅通知山变化时
由客端碗定
数据结构
PrescuceNotification
服务器向观看者通知呈现者信息变化的资源概述见表12。HTTP方法
表12服务器向观看者通知呈现者信息变化资源
所有星现列
表的订阅A1l
单一是现列
表的皇现列
表订阅
基础URL：
http://(serverRoot)
presence/ (apiVersion)
/(userld)/subscriptions/
presetceListsubscriptions
/(userid)/subscriptions
presenceListSubscriptions
fpresenceListId)
特定的现
/(userid)/subscriptions/
列表订闻
preseuceListSubscriptions/
(presenccListid)/
(subscriptiorld
数据结构
PresepceListSubsc
riptionCollection
PresenceListSubsc
riptionCollection
（用于GET）
PresenceListSubsc
ription
（用于POST）
common:Resource
Reference（在
POST啊应中条件
可选》
PresenceListSubsc
ription（用于GET/
获得所有垦现
列表的活跃的
订阅刻表
获得一个特定
的订阅列表的
所有活跃望现
列表订阅
获得一个特定
的呈现列表的
向客户端通知
一个单一呈现
体的呈现信感
HTTP方法
更新一个
特定的呈
现列表的
在特定的
呈现列表
的星现信
息变化时
创建一个
订阅通知
服务器向观看者通知呈现者列表中的某些呈现者信息发生变化的资源概述见表13。表13服务器向观看者通知呈现者列表中的某些呈现者信息发生变化资源
星现列表通知
基础URL:
由客户端指定
当观看者信息列表被
创建或者在配置过程
中订阅通知由变化时
由客户端确定
数据结构
PresenceListNotification
HITTP方法
向客户端通
知呈现列表
的呈现信息
的变化
DELETE
DELETE
终结·~个特
定的呈现列
表的订闵
DELETE
5.2枚举类型定义
ActivityValue
YD/T 3189-2016
该参数为枚举类型。描述用户活动状态的可能值，继承自IETFRFC4480，具体见表14。表14ActivityValue：枚举
枚举值
Appointment
Available
OnThePhone
Steering
Meeting
Breakfast
Dinner
PermanentAbsence
Vacation
Holiday
Performance
InTransit
Travel
Sleeping
LookingForWork
Playing
Presentation
Shopping
Spectalor
Working
Worship
ActivitiesUnknown
ActivitiesOther
PlaceTypeValue
这个用户有一个约会
这个用户有空聊人
这个用户忙，除非有骚急的事情这个用户正在通话中
这个用户正在驾驶汽车/火车/飞机等这个用户正在开会
这个用户离开了，但是不知道他在做什么这个用户正在吃饭
这个用户正在吃早餐
这个用户正在吃乍餐
这个用户正在吃晚餐
这个用户离开了，并且较长时间内不会回来这个用户正在度假
·个预定的国家或传统节月
这个用户在剧院/会议室
这个用户正在登机口的中转区
这个用户止在旅行
这个用广正在睡觉
这个用户正在找工作
这个用户在花时间在娱乐、运动或其他休闲上这个用户止在做演示、演讲或者参加一个圆桌讨论这个用户正在连商店寻找商品或服务这个用户正在观看一个赛事，例如体育赛事这个用户正在看电视
这个用广正在工作
这个用广正在参宗教仪式
这个用户的活跃度未知
这个用户在做不在列表中的活动该参数为枚举类型，描述用户当前所在的位置信息。继承自IETFRFC4480，具体见表15。表15PlaceTypeValue：枚举
枚举值
这个用户在体育场
这个用户在家
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。
中华人民共和国通信行业标准
YD/T3189—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）状态呈现业务RESTful based service capability open API-presence( 0MA-ERP-REST NetAPI Presence-V1 0-20130212-C,RESTful Network API for Presence 1.0,NEQ)2016-10-22发布
中华人民共和国工业和信息化部2017-01-01实施
范围、
2规范性引用文件.
3术语、定义和缩略语。
3.1术语和定义，
3.2缩略语.
4状态呈现业务概述..
5状态呈现业务RESTfulAPI定义
资源概述
枚举类型定义，
5.3数据结构定义，
接口流程.
6接口定义
创建和获取状态呈现源信息
创建和获取观看者订阅信息
观看者通知bzxz.net
创建和获取状态呈现订阅信息
状态呈现通知，
获取和更新状态呈现源
创建/获取授权规则
创建/更新特定授权规则
错误定义
业务异常.
策略异常.
8授权框架
使用Autho4API框架
范围值
‘acrauth'的用法
参考文献.
YD/T31892016
YD/T3189—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）移动互联网用户_上下文感知业务：
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）非结构化补充数据业务。
随着技术和市场的发展，还将根据情况制定后续相关标准。本标准按照GB/T1.1—2009给出的规则起草。本标准使用重新起草法参考OMA-ERP-REST_NetAPI_Presence-V1_0-20130212-C.《基于表述性状态转移（REST）技术的显现业务应用程序接口（API）（OMARESTfulNetworkAPIforPresence1.0）》编制，本标准与OMA-ERP-REST_NetAPlPrcsencc-V1_0-20130212-C的一致性程度为非等效。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。本标准起草单位：中国移动通信集团公司、中国信息通信研究院、中国联合网络通信有限公司、中国电信集团公司。
本标准主要起草人：刘悦、庞亚昆、杨波、赵婷、汪洋。I
1范围
YD/T 3189—2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（APD）
状态呈现业务
本标准规定了基于表述性状态转移（REST）的针对状态呈现业务的API接[1定义，包括接L1流程，接口数据结构，接山定义和接山安全要求等。本标准适用于提供状态呈现能力开放的应用程序接口。2 规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡事不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T2423—2012
ISO ISO.3166
OMA OMA-ER-Auth04
API-VI_01
OMA OMA-TS-REST
NetAPI_Common
OMAOMA-ERP-REST
NetAPINotificationChannel
IETF RFC2616
IETFRFC3261
IETF RFC3966
1ETFRFC3986
IETF RFC4627
W3C W3C_URLENC
W3C XMLSchemal
基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求国家编码（CountryCodes）
网络API授权框架（AuthorizationFrameworkforNetworkAPIs）RESTful风格的网络API通用定义1.0版本RESTful风格的网络API通用定义1.o版本（CommondefiaitionsforRESTful Network APIs )
RESTful风格的通知通道网络API1.0版本（RESTfulNetworkAPIforNotification Channel)
超文本传输协议——HTTP/1.1 (Hypertext Transfer Protocol -- HTTP/1,1)SIP：会话发起协议(SIP:Session Initiation Protocol)电话号码的TelURI（ThetelURIforTelephoneNumbers）统一资源标示符（URI）：一般语法（Uniform Resource Identifier(URI) : Generic Syntax)
Java描述语言对象符号的应用/基于java描述语言的轻量级数据交换格式(The application/json Media Type for JavaScript Object Notation (JSON))超文本标记语言4.01规范：17.13.4章节：表单内容类型（HTMIL，4.01Specification, Section 17.13.4 Form content types, The World Wide WebConsortium)
可扩展标识语言架构第1部分：结构（第一版）（W3CXMLSchema1
YD/T3189—2016
W3C XMLSchema2
3术语、定义和缩略语
3.1术语和定义
Definition Language(XSD)1.1Part l:Structures Second Edition)可扩展标识语言架构第2部分（W3CXMLSchemaDefinitionLanguage（XSD）1.1Part2：Datatypes）下列术语和定义适用于本文件。3.1.1
表述性状态转移RepresentationalStateTransfer：种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性，具体见《基于表述性状态转移（REST）技术的电信业务能力开放平台技术要求》对REST的定义。
Web 服务Web Service
一种构建应用程序的普遍模型,可以在任何支持网络通信的操作系统中实施运行；是一种新的web应用程序分支，是自包含、自描述、模块化的应用，可以发布、定位、通过web调用。3.1.2
简单对象访问协议SimpleObjectAccessProtocol种轻量的、简单的、基于XML的协议，它被设计成在WEB上交换结构化的和固化的信息。3.2缩略语
下列缩略语适用丁本文件。
ApplicationProgrammingInterfaceHyperText Transfer Protocol
Identitifer
Representational StateTransferUaiform Resoue Locator
Extensible Markup Language
4状态呈现业务概述
应程序编程接口
超文本传输协议
表述性状态转移
统资源定位符
扩展标记语言
状态呈现业务通过开放接口提供创建状态呈现信息源、订阅者、观看者，创建、呈现订阅信息和通知等功能。
5状态呈现业务RESTfulAPI定义
5.1资源概述
本节概要描述了图片共享的RESTfuLAPI所用到的资源。YD/T 31892016
本标准中URL变量\apiVersion”的取值为“v1\表明该API对应于本标准。URL变量“apiVersion”的语义定义见OMA-TS-RESTNetAPICommon-Vl_O。图1为图片共享RESTfulAPI的资源树结构。注：资源树中实线握所示的节点表示该节点有关联的HTTP方法。na
L(userin)
tresencescairces
treenasoxreiai
iesnurelkelipah]
pursrstent
12ortenl
jwaichers
auihorizaho
oomeiy
ipxisil ucn
watcrer.Jserd,
Trulee
ipresenceContacts
SuusvrltlyUsarlogy
IpresenceLists
caesenceLi6tar
prexe\cuCoutsGurile
r(cresert yuserlds
xerietos
[ResuuraRueh
ruieliag
walcheiSubscripirulis
H rsubsreluonldy
peenesscrpiane
Ppresentyuger ay ]
[isubeclweionle]
rhe asris, is ir inerresery rakLhe useria: isir he wahetor role gisrldg isnoheleerPrmty
Tielarenairn lor Ighl wright reto.etprekenceLletsubecrpiois
Licveaence_mie
rsubscriplicndCk
图1状态呈现业务RESTfulAPI资源结构3
YD/T 3189—2016
表1给出了本标准中定义的呈现者管理自身呈现信息的资源概述，其数据类型表示和允许的HTTP方法。其中数据结构的具体定义见5.3节。呈现者管理自身呈现信息
基础URL：
呈现源
特定皇现源
特定是现源
持久化呈现
特定持久化
皇现源的鳳
http:// [serverRoot)/
presence/ (apiVersion)
(userld)/presence
Sources
/ (userld)/presence
Sources/(presence
Sourceldi
(userld)/presence
Sources(presence
SorcedResource
RelPath]
/(userid)/presence
Sources/persistent
/(userld)/presence
Sources/persistent
[ResourceRelPath]
数据结构
PresenceSourceList
(用于GET) Presence
Source（用于POST)
common:ResourceRef
erence（在POST响应
中条件可选）
PresenceSource（用于
PUT/GET)
数据结懋相当于呈现
源中说我U措性
的一个元题
(用PUT/GET)
PresenceSource
数据结构相当于呈瑰
源中由销求URL指出
的一个元素
（用于PUT/GET）
呈现者管理自身内容的资源概述见表2。GET
获得所有与
某‘呈现者
相关的星现，
获得某一呈
现者的特定
是现源的呈
现信息
注：观看者不
应使用这一
获得一个特
定呈现源的
特定基现属
性的值
获得一个呈
现者的持久
化的垦现源
的信息
获得一个特定
持久化是现源
的特定呈现属
性的值
表2呈现者管理自身内容
基础URL:
http://(serverRoot)
presence/ [apiVersion]
垦现者内容
fuserldfcontent
特定呈现体userldycontent/
(contentId)
数据结构
ContentList
在意MIME内
获与呈现体相关的所
有内容标识
获得一个垦现体的一个特
定内容（例如~个图片）
注：观看者不应使用这
一操作
HTTP方法
更新某一呈现
者的特定呈现
源的品现信息
创建或更新一
个特定呈现源
的个呈现属
创建更新
个呈现者的持
久化的呈现源
的信息
创建或更新一
个特定持久化
呈现源的一个
是现属性
HTTP方法
创建或替换服
务器上一个堂
现体的一个特
定内容
为是现
者创建
现资源
DELETE
删除某一呈
现者的特定
呈现源的呈
现信息
删除一个特
定呈现源的
“-个呈现属
删除．个望
现者的持久
化的垦现
的信息
删除一个特
定持久化呈
现源的一个
早现属性
DELETB
从服务器上
删除一个特
定内容
导现者头像
基础URL：
http:// (serverRoot)
presencel (apiVersian)
/(userld)/content/port
raiticon
表2呈现者管理自身内容（续）
数据结构
在意与…个
图片相关的
M内容
获得一个早现体的头像
图标注：观看者不应使
用这一操作
呈现者检索观看者感兴趣的信息资源概述见表3。HTTP方法
创建或替换
服务器上一
个呈现体的
头像图标，同
时服务器更
新这个图标
的链接
表3呈现者检索观看者感兴趣的信息基磁URL：
观看者列表
特定观看者
http://(serverRoot))
presence/ (apiVersion)
/ [userld) /watchers
userld] /watchers/ [wat
cherUserld!
数据结构
WatcherList
Watcher
HTTP方法
获得对呈现者的呈现信
息，包含当前的订阅状态，
感兴趣的观察者列表
默得一个特定观看者当前
的订阅状态和订阅属性
呈现者管理观看者对呈现信息的访间的资源概述见表4。表4呈现者管理观看者对呈现信息的访问基础URL：
鉴权规则
特定的整权
特定的鉴权
规则参数
http:/f (serverRoot)!
presence [apiVersion)
/(userld) /autharization
frules
/ userld]/authorization
frules/truleld!
fuserId)fauthorization
frulestfruleldResour
ceRelPatb
数据结构
（用于
RuleList
Rule（用于POST)
common:ResourceR
eference（在POST响
应中条件可选）
Rule（用于PUT/
散据结构相当丁星
现源中由请求URL
指出的一个元
(用于 PUT/GET)
获得所有鉴
权规则
HTTP方法
获得一个特「更新一个特
定的鉴权规
获得一·个特
定鉴权规则
的特定规则
定的鉴权规
创建或更新
个特定鉴
权规则的特
定规参数
YD/T 31892016
创建一个
新的鉴权
DELETE
从服务器上
删除一个皇
现体的头像
DELETE
DELETE
删除一个特
定的鉴权规
删除个特
定鉴权规则
的特定规划
YD/T 31892016
观看者从现者或垦现者列表中检索呈现信息的资源概述见表5。表5观看者从呈现者或呈现者列表中检索呈现信息基础URL：
个单独呈
现体的观察
者望现俯息
观看者的特
定呈现属性
呈现体列表
的观察者呈
现信息
http:// [serverRoot)?
presence/ (apiVersion)
I fuserld)/presence
Contacts/(presentity
Userldy
(userid)/presence
Cantacts/(presentity
Userld]/[ResourceRe]
/ (useriId)/presence
Lists/ (presezceListid)
数据结构
PresenceContact
数据结构相当于呈现
联系结构中由请求
URL指出的一个元索
PresenceList
观看者从呈现者中检索内容的资源概述见表6。GET
从··个呈现体获得
符合的皇现信息
江：获得的垦现信息
可包含从多个显现
源获得的呈现信息
获得一个呈现体的
特定呈现属性
获得特定呈现列表
中所有呈现体的呈
现信息
表6观看者从呈现者中检索内容
基础URL：
观看者内穿
http:// (serverRoot)/
presence/(apiVersion)
/(userld)/PresenceConta
ctsContenu (presentityUs
erId]/[contentId]
数据结构
年章MIME内容
获得一个特定呈现
者的·个特定内容
（例如一-张图片）
用户（包括观看者和呈现者）检索自身的订阅关系的资源概述见表7。HTTP方法
HTTP方法
表7用户（包括观看者和呈现者）检索自身的订阅关系基础URL：
所有订阅
http://[serverRoot))
presence/ (apiVersion)
/fuserld)fsubscriptions
数据结构
SubscriptionList
HTTP方法
获得。个用户的所有订阅
呈现者在观看者信息变化时管理通知的订阅的资源概述见表8。6
DELETE
DELETE
DELETE
所有观看
者的订阅
特定的观
看者订阅
表8呈现者在观看者信息变化时管理通知的订阅基础URL：
http://(serverRoot)/prese
ace/(apiVersion）
fuserld) /subscriptions/
watchersSubscriptions
/(userId)/subscriptions/
watchersSubscriptions/
[subscriptionld
数据结构
WatchersSubseription
List（用于 GET)
WatchersSubscription
（用于POST）
common:ResourceRef
erence（在POST响应
中条件可选）
WatchersSubscription
获得与观看者列
表相关的所有订
在管按着列表变
化时获得一个特
定的订阅
服务器向呈现者通知观看者订阅状态变化的资源概述见表9。HTTP方法
更新用户
列表的一
个特定订
表9服务器向呈现者通知观看者订阅状态变化资源
基础URL：
由客户端指定
观着者通
当观看者信息列表被创
建或者在配置过程中订
阅通知由变化时由客广
端确定
数据结构
WatchersNotification
YD/T 31892016
在观看者
列表变化
时创建—
个订阅通
HTTP方法
当呈现者信息变化时观看者管理自身通知的订阅的资源概述见表10。GET
向客户端通知
观看者订阅状
态的变化
表10当呈现者信息变化时观看者管理自身通知的订阅基础URL：
所有是现
一个单一
呈现体的
呈现订阅
特定的呈
现订阅
http:// (serverRoot)/
preseace/ (apiVersion)
/(userld) /subscriptions/
prescaceSubscriptions
/ userld]/subscriptions
presenceSubscriptions/
(presentityUserId)
ffuserld/subscriptions!
presenceSubsoriptions/
f presentityUserld)?
fsubscriptionld?
数据结构
PresenceSubscription
PresenceSubscription
List（用于GET）
PresenceSubscription
（用于POST)
common:ResourceRef
erence（在POST响
应中条件可选）
PresenceSubscription
（用于GET/PUT）
获得所有呈
现者的呈现
信息的所有
活跃的订阅
获得．个特
定呈现者的
呈现信息的
所有活跃的
获得现信
息的一个特
定活跃订阅
HTTP方法
更新星现信
息的特定订
在“个特定
的呈现体的
呈现信息变
化时创建一
个订阅通知
DELETE
终止用户
列表的一
个特定订
DELETE
DELETE
终结呈现
信息的特
定订阅
YD/T3189—2016
服务器向观看者通知呈现者信息变化的资源概述见表11。表11服务器向观看者通知呈现者信息变化资源
呈现通知
基础URL:
由客户端指定
当观看者倍息列表被
创建或者在配置过程
中订阅通知山变化时
由客端碗定
数据结构
PrescuceNotification
服务器向观看者通知呈现者信息变化的资源概述见表12。HTTP方法
表12服务器向观看者通知呈现者信息变化资源
所有星现列
表的订阅A1l
单一是现列
表的皇现列
表订阅
基础URL：
http://(serverRoot)
presence/ (apiVersion)
/(userld)/subscriptions/
presetceListsubscriptions
/(userid)/subscriptions
presenceListSubscriptions
fpresenceListId)
特定的现
/(userid)/subscriptions/
列表订闻
preseuceListSubscriptions/
(presenccListid)/
(subscriptiorld
数据结构
PresepceListSubsc
riptionCollection
PresenceListSubsc
riptionCollection
（用于GET）
PresenceListSubsc
ription
（用于POST）
common:Resource
Reference（在
POST啊应中条件
可选》
PresenceListSubsc
ription（用于GET/
获得所有垦现
列表的活跃的
订阅刻表
获得一个特定
的订阅列表的
所有活跃望现
列表订阅
获得一个特定
的呈现列表的
向客户端通知
一个单一呈现
体的呈现信感
HTTP方法
更新一个
特定的呈
现列表的
在特定的
呈现列表
的星现信
息变化时
创建一个
订阅通知
服务器向观看者通知呈现者列表中的某些呈现者信息发生变化的资源概述见表13。表13服务器向观看者通知呈现者列表中的某些呈现者信息发生变化资源
星现列表通知
基础URL:
由客户端指定
当观看者信息列表被
创建或者在配置过程
中订阅通知由变化时
由客户端确定
数据结构
PresenceListNotification
HITTP方法
向客户端通
知呈现列表
的呈现信息
的变化
DELETE
DELETE
终结·~个特
定的呈现列
表的订闵
DELETE
5.2枚举类型定义
ActivityValue
YD/T 3189-2016
该参数为枚举类型。描述用户活动状态的可能值，继承自IETFRFC4480，具体见表14。表14ActivityValue：枚举
枚举值
Appointment
Available
OnThePhone
Steering
Meeting
Breakfast
Dinner
PermanentAbsence
Vacation
Holiday
Performance
InTransit
Travel
Sleeping
LookingForWork
Playing
Presentation
Shopping
Spectalor
Working
Worship
ActivitiesUnknown
ActivitiesOther
PlaceTypeValue
这个用户有一个约会
这个用户有空聊人
这个用户忙，除非有骚急的事情这个用户正在通话中
这个用户正在驾驶汽车/火车/飞机等这个用户正在开会
这个用户离开了，但是不知道他在做什么这个用户正在吃饭
这个用户正在吃早餐
这个用户正在吃乍餐
这个用户正在吃晚餐
这个用户离开了，并且较长时间内不会回来这个用户正在度假
·个预定的国家或传统节月
这个用户在剧院/会议室
这个用户正在登机口的中转区
这个用户止在旅行
这个用广正在睡觉
这个用户正在找工作
这个用户在花时间在娱乐、运动或其他休闲上这个用户止在做演示、演讲或者参加一个圆桌讨论这个用户正在连商店寻找商品或服务这个用户正在观看一个赛事，例如体育赛事这个用户正在看电视
这个用广正在工作
这个用广正在参宗教仪式
这个用户的活跃度未知
这个用户在做不在列表中的活动该参数为枚举类型，描述用户当前所在的位置信息。继承自IETFRFC4480，具体见表15。表15PlaceTypeValue：枚举
枚举值
这个用户在体育场
这个用户在家
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。